Sun GlassFish Communications Server 1.5 High Availability Administration Guide

The Data Centric Rules File

The default path and name of the data centric rules file is domain-dir/cluster/config/data-centric-rules.xml. If the converged load balancer configuration that specifies the data centric rules file does not reference any cluster or stand-alone server instance, the default path and name is domain-dir/config/data-centric-rules.xml. The DTD file that validates the file format is as-install/lib/dtds/sun-data-centric-rule_1_0.dtd.

If a data centric rules file is specified, a consistent hash algorithm determines the server instance to which the request is forwarded. The server instance selection is based on a hash key. The key is extracted from incoming SIP and HTTP requests according to the data centric rules. These rules apply to all applications deployed on the LB targets and can be changed during operation. Only new initial requests are affected by such changes.

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.

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.

Here is an example data centric rules file:

<?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 following sections describe the elements in the data-centric-rules.xml file.

Top-Level Elements

The top-level elements determine the rules for SIP/SIPS and HTTP/HTTPS requests.

user-centric-rules

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.

sip-rules

Determines the data centric rules for SIP and SIPS requests.

Superelements

user-centric-rules

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

http-rules

Determines the data centric rules for HTTP and HTTPS requests.

Superelements

user-centric-rules

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

Operator Elements

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.

or

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

and

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

if

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.

else

Specifies an alternative when the parent if element's condition evaluates to null.

Superelements

Attributes

The following attribute is required and case-sensitive.

return: Specifies a variable that evaluates to the return value. See Variables.

Condition Elements

The condition elements specify the kind of data on which rule decisions are based. All attribute values are case-sensitive.

header

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:

exist, notexist

Attributes

The following attributes are required.

name: Specifies the name of the request header.
return: Specifies a variable that evaluates to the return value. See Variables.

request-uri

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:

exist, notexist, match

Attributes

The following attributes are required if the subelement is exist or notexist and optional if the subelement is match.

parameter: Specifies the request URI parameter.
return: Specifies a variable that evaluates to the return value. See Variables.

session-case

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

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:.

exist, notexist

Attributes

The following attributes are required.

name: Specifies the name of the cookie.
return: Specifies a variable that evaluates to the return value. See Variables.

Condition Type Elements

The condition type elements compare request data to the data expected by the rules. All comparisons are case-sensitive.

exist

Specifies that a variable must evaluate to a header, request-uri, or cookie that exists in the request. See Variables.

Superelements

header, request-uri, cookie

notexist

Specifies that a variable must evaluate to a header, request-uri, or cookiethat does not exist in the request. See Variables.

Superelements

header, request-uri, cookie

equal

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

session-case

match

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

request-uri

Variables

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