Sun GlassFish Communications Server 2.0 High Availability Administration Guide

The Data Centric Rules File

A consistent hash algorithm determines the server instance to which the request is forwarded. The server instance selection is based on a hash key. You can define data centric rules, using which the key is extracted from incoming SIP and HTTP requests. Data centric rules are not application-specific and apply to all applications deployed on the LB targets. Only new initial requests are affected by such changes.

The default path to the data centric rules file is domain-dir/config/cluster-config-name. 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 is domain-dir/config/.

Data centric rules are dynamically re-configurable. The admin framework generates an admin event into the converged load balancer where the data centric rules file is supplied as an argument and the converged load balancer loads a new version of the data centric rules file.

If the data centric rules do not match any incoming SIP or HTTP requests, one of the following happens: .

For HTTP requests, a hash key is generated using the remote host and port.
For SIP requests, a hash key is generated using from-tag,call-id

The data centric rules file can be a JAR file or an XML file, as described in the following sections:

Creating a Data Centric Rules JAR File
Creating a Data Centric Rules XML File

To set a data centric rules JAR or XML file for a converged load balancer, see the instructions at Setting the Data Centric Rules File for a Converged Load Balancer

Creating a Data Centric Rules JAR File

The data centric rules of the converged load balancer is configurable using an implementation of the org.glassfish.comms.api.datacentric.DcrPlugin interface , which is supplied as a pre-compiled Java class packaged in a JAR file. When routing a request, the converged load balancer calls the instantiated plug-in to extract the key from initial SIP and HTTP requests. The converged load balancer uses the result returned from the plug-in, to lookup the serving instance in the consistent hash.

The org.glassfish.comms.api.datacentric.DcrPlugin interface specifies two methods:

String getKey(javax.servlet.sip.SipServletRequest request, javax.servlet.sip.SipFactory sipFactory, org.glassfish.comms.api.uriutils.UriTools uriTools, org.glassfish.comms.api.telurl.TelUrlResolver telUrlResolver)
String getKey(javax.servlet.http.HttpServletRequest request, javax.servlet.sip.SipFactory sipFactory, org.glassfish.comms.api.uriutils.UriTools uriTools, org.glassfish.comms.api.telurl.TelUrlResolver telUrlResolver)

You can implement these methods to extract the key to be used for lookup in the consistent hash in the converged load balancer, for initial requests. Each method can return a non-null value, which indicates that the request matches a rule and a hash key is successfully extracted. If none of the rules match a request, a null value is returned and the hash key is extracted using default rules.

To facilitate the implementation of the data centric rules plug-in, the following entities are provided as method arguments:

TelUrlResolver — For resolving Tel URIs
UriTools— For normalizing and canonicalizing URIs
SipFactory — For converting header values to URIs and extracting the various components from such a URI

The data centric rules JAR file must contain a compiled implementation of the plug-in interface. It can also contain other application specific helper classes. It must also have a manifest that specifies the class name of this data centric rules plug-in implementation. The converged load balancer uses the manifest to identify the class that implements data centric rules plug-in. It then loads the plug-in class and creates an instance.

Here is an example Java class file that specifies data centric rules:

package mydcr;

import org.glassfish.comms.api.datacentric.DcrPlugin;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.sip.SipFactory;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipURI;
import org.glassfish.comms.api.telurl.TelUrlResolver;
import org.glassfish.comms.api.uriutils.UriTools;

public class MyDcrPluginImpl implements DcrPlugin{

    public String getKey(SipServletRequest request,
            SipFactory sipFactory, UriTools uriTools,
            TelUrlResolver telUrlResolver) {
        String key = null;
        String method = request.getMethod().toUpperCase();
        if(method.equals( "PUBLISH" ) || method.equals( "INVITE" ) 
              || method.equals( "CANCEL" )){
           key = SipURI.class.cast(request.getTo().getURI()).getUser();
        } else if (method.equals( "REGISTER" )
                || method.equals( "SUBSCRIBE" )){
            key = SipURI.class.cast(request.getFrom().getURI()).getUser();
        }
        System.out.println("MY DCR PLUGIN - Key extracted from SIP request : " + key);
        return key;
    }

    public String getKey(HttpServletRequest request,
            SipFactory sipFactory, UriTools uriTools,
            TelUrlResolver telUrlResolver) {
        String key =  request.getParameter( "j_username" );
        System.out.println("MY DCR PLUGIN - Key extracted from HTTP request : " + key);
        return key;
    }


}

After you have written the data centric rules class, follow these steps:

Compile the data centric rules class as shown in the following example command. You must include ssa-api.jar, javaee.jar, and comms-appserv-api.jar in the classpath. The classes directory must exist.
javac -classpath as-install/lib/ssa-api.jar:as-install/lib/javaee.jar:as-install/lib/comms-appserv-api.jar -d classes src/mydcr/MyDcrPluginImpl.java

Write the manifest file. For example:

Manifest-Version: 1.0
Dcr-Plugin-Class: mydcr.MyDcrPluginImpl

Create the data centric rules JAR file. For example:

jar -cvfm mydcrplugin.jar mymanifest -C classes mydcr/MyDcrPluginImpl.class

Set the data centric rules file using the asadmin set-dcr-file command. Refer the instructions at Setting the Data Centric Rules File for a Converged Load Balancer.

Creating a Data Centric Rules XML File

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:

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

Setting the Data Centric Rules File for a Converged Load Balancer

The following tasks use the Admin Console or the CLI to set a data centric rules file for a converged load balancer.

To Set the Data Centric Rules File Using the Admin Console

Create the data centric rules file.

In the left-hand pane, click Converged Load Balancer.

Select a Converged Load Balancer from the list of Converged Load Balancers.

The Settings page appears. The DCR File Settings section in this page displays the current data centric rules file.

In the Upload DCR File field, click Browse to upload the data centric rules XML or JAR file you have created.

Note –
Communications Server does not expect the file extension to be case-sensitive.

Click Save.

To Set the Data Centric Rules File Using CLI

Create the data centric rules file.

To set the XML or JAR file as the data centric rules file for Communications Server, use the asadmin set-dcr-file command.

The following are sample commands:

asadmin set-dcr-file --host myhost --port 4850 --clbconfig my-cluster-config mydcrfile.jar

asadmin set-dcr-file --host myhost --port 4850 --clbconfig my-cluster-config mydcrfile.xml