The data centric rule language is similar to the triggering language for mapping requests to servlets. The rule language consists of conditions and variables supporting SIP and HTTP key extraction. In contrast to the servlet mapping language, the data centric rules file needs to return a value, either non-null (true) or null (false).
Each incoming SIP and HTTP request is matched with the current rule set. The first rule that matches is used for key extraction. The rules are evaluated sequentially until a condition returns a non-null value. For an OR expression, the first non-null sub-result is returned. For an AND expression, the last sub-result is returned. The key is set to null if no rule matches.
Here is an example XML file that specifies data centric rules:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE user-centric-rules PUBLIC "-//Sun Microsystems Inc.//DTD Sailfin 1.0//EN" "http://www.sun.com/software/appserver/dtds/sun-data-centric-rule_1_0.dtd"> <user-centric-rules> <sip-rules> <if> <session-case> <equal>ORIGINATING</equal> <if> <header name="P-Asserted-Identity" return="request.P-Asserted-Identity.uri.resolve.user"> <exist/> </header> <if> <header name="P-Asserted-Identity" return="request.from.uri.resolve.user"> <notexist/> </header> <if> <header name="P-Asserted-Identity" return="request.to.uri.resolve.user"> <notexist/> </header> </if> </if> </if> </session-case> <else return="request.uri.resolve.user" /> </if> </sip-rules> <http-rules> <or> <request-uri return="match.resolve.user"> <match>/users/([^/]+)</match> </request-uri> <and> <request-uri> <match>^/css/</match> </request-uri> <or> <request-uri parameter="referredBy" return="parameter.requestUri.uri.resolve.user"> <exist/> </request-uri> <request-uri parameter="referredBy" return="parameter.from.uri.resolve.user"> <notexist/> </request-uri> </or> </and> </or> </http-rules> </data-centric-rules>
The default name is data-centric-rules.xml. The DTD file that validates the file format is as-install/lib/dtds/sun-data-centric-rule_1_0.dtd.
The following sections describe the elements in the data-centric-rules.xml file:
The top-level elements determine the rules for SIP/SIPS and HTTP/HTTPS requests.
This is the top level or root element in the data-centric-rules.xml file.
Subelements
You can specify one or both of the following subelements: sip-rules, http-rules.
Determines the data centric rules for SIP and SIPS requests.
Superelements
Subelements
All of the following subelements are optional and can occur in any number and any order:
or, and, if, header, request-uri, session-case, cookie
Determines the data centric rules for HTTP and HTTPS requests.
Superelements
Subelements
All of the following subelements are optional and can occur in any number and any order:
or, and, if, header, request-uri, session-case, cookie
The operator elements specify decisions between different rules. The or, and, and if elements are recursive. You can specify any number of branches and levels of these elements, as long as the lowest level of each branch contains one of the Condition Elements.
Evaluates to true if and only if at least one contained condition evaluates to a non-null value.
Superelements
sip-rules, http-rules, or, and, if
Subelements
All of the following subelements are optional and can occur in any number and any order:
or, and, if, header, request-uri, session-case, cookie
Evaluates to true if and only if all contained conditions evaluate to a non-null value.
Superelements
sip-rules, http-rules, or, and, if
Subelements
All of the following subelements are optional and can occur in any number and any order:
or, and, if, header, request-uri, session-case, cookie
Contains a single condition. If the condition evaluates to a non-null value, the evaluation continues in the if branch. If the condition evaluates to null, the evaluation continues in the optional else branch.
Superelements
sip-rules, http-rules, or, and, if
Subelements
All of the following subelements are optional and can occur in any number and any order:
or, and, if, header, request-uri, session-case, cookie
The else subelement is optional and must occur last if specified.
Specifies an alternative when the parent if element's condition evaluates to null.
Superelements
Attributes
The following attribute is required and case-sensitive.
Specifies a variable that evaluates to the return value. See Variables.
The condition elements specify the kind of data on which rule decisions are based. All attribute values are case-sensitive.
Specifies a rule based on a request header.
Superelements
sip-rules, http-rules, or, and, if
Subelements
Exactly one of the following subelements is required:
Attributes
The following attributes are required.
Specifies the name of the request header.
Specifies a variable that evaluates to the return value. See Variables.
Specifies a rule based on a request URI and its parameters.
Superelements
sip-rules, http-rules, or, and, if
Subelements
Exactly one of the following subelements is required:
Attributes
The following attributes are required if the subelement is exist or notexist and optional if the subelement is match.
Specifies the request URI parameter.
Specifies a variable that evaluates to the return value. See Variables.
Specifies a rule based on the call parameter of a SIP session. Only relevant in IMS/3GPP (Internet Protocol Multimedia Subsystem Third Generation Partnership Project) environments. For details, see the equal subelement description.
Superelements
sip-rules, http-rules, or, and, if
Subelements
The equal subelement is required and must occur first.
All of the following subelements are optional and can occur in any number and any order:
or, and, if, header, request-uri, session-case, cookie
Specifies a rule based on an HTTP cookie.
Superelements
sip-rules, http-rules, or, and, if
Subelements
Exactly one of the following subelements is required:
Attributes
The following attributes are required.
Specifies the name of the cookie.
Specifies a variable that evaluates to the return value. See Variables.
The condition type elements compare request data to the data expected by the rules. All comparisons are case-sensitive.
Specifies that a variable must evaluate to a header, request-uri, or cookie that exists in the request. See Variables.
Superelements
Specifies that a variable must evaluate to a header, request-uri, or cookiethat does not exist in the request. See Variables.
Superelements
Specifies which part of a call is processed, the originating or terminating side of the call. Only relevant in IMS/3GPP environments. Allowed values are:
EXTERNAL — Specifies that there is no route header in the SIP request or no call parameter in the route header.
ORIGINATING — Specifies that the route header contains call=orig.
TERMINATING — Specifies that the route header contains call=term_registered.
TERMINATING_UNREGISTERED — Specifies that the route header contains call=term_unregistered.
Superelements
Specifies the regular expression that a request-uri must match. The return value is the match of the first capturing group in the regular expression. For more information about regular expressions, see http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html.
The match element may have an optional prefix that is prepended to the return value.
Superelements
The name, parameter, and return attributes and the exist and notexist elements in the data centric rules file use variables. Variables containing the string resolve contain values retrieved by performing ENUM lookups of TEL URIs. Some variables contain replaceable text. For example, in the request.header variable, the header is replaced by the name of a SIP or HTTP header. The syntax for matching SIP and HTTP requests is slightly different.
The following SIP variables are supported:
request.uri request.uri.scheme request.uri.user request.uri.host request.uri.port request.method request.uri.resolve request.uri.resolve.user request.uri.resolve.host request.header request.header.uri request.header.uri.scheme request.header.uri.user request.header.uri.host request.header.uri.port request.header.uri.display-name request.header.uri.resolve request.header.uri.resolve.user request.header.uri.resolve.host request.header.match request.header.match.resolve.user match match.resolve.user
The following HTTP variables are supported:
request.header request.header.uri request.header.uri.user request.header.uri.host request.header.uri.resolve request.header.uri.resolve.user request.header.uri.resolve.host parameter.parameter parameter.parameter.uri parameter.parameter.uri.user parameter.parameter.uri.host parameter.parameter.uri.resolve parameter.parameter.uri.resolve.user parameter.parameter.uri.resolve.host match match.resolve.user cookie.cookie-name
The resolution of the HTTP variable parameter.parameter.uri.resolve.user is complex. The variable matches a parameter value in an HTTP request, and this value may be a single name-addr or a comma-separated sequence of them. The name-addr elements are resolved until a usable user centric hash key is found. The order of resolution is as follows:
If a name-addr contains a user=phone parameter, it is resolved as a TEL URL, otherwise the user part of the URI is extracted. Resolution of a SIP URI may thus fail if it specifies a telephone number entity that cannot be resolved by ENUM, or else because there is no user part present in the SIP URI.
If all SIP URIs have been considered, a second attempt is made, and the TEL URLs are read from left to right. Evaluation stops as soon as a usable user centric key has been found.
If every resolution attempt fails, no user centric key is found. If an HTTP request doesn't match any DCR file rules, a hash key is generated using the remote host and port. If a SIP request doesn't match any DCR file rules, a hash key is generated using from-tag,call-id.
For example, if the variable is parameter.from.uri.resolve.user and the HTTP request is GET ...?...&from=...&...HTTP/1.1, the outcome may be according to the values in the following table. Some of the characters in the examples may in reality need to be URL-encoded (< would appear as %3C and so on.)
Table 2–3 Examples of from Parameter Values
Value of from Parameter |
User Centric Key |
---|---|
<sip:server.xx.yy> |
none |
<sip:alice@server.xx.yy> |
alice |
<tel:+1-333-555>,<sip:+1-22-22@server.xx.yy;user=phone> |
from ENUM |