Using the Application Router

Application composition is the process of “chaining" multiple SIP applications into a logical path to apply services to a SIP request. The SIP Servlet v2.0 specification introduces an Application Router (AR) deployment, which performs a key role in composing SIP applications. The Application Router examines an initial SIP request and uses custom logic to determine which SIP application must process the request. In Converged Application Server, all initial requests are first delivered to the AR, which determines the application used to process the request.

Converged Application Server supports the Default Application Router, which can be configured using a text file. Custom Application Routers are also supported. You create a Custom Application Router by implementing the SipApplicationRouter interface. A Custom Application Router can use complex processing to make routing decisions.

In contrast to the Application Router, which requires knowledge of which SIP applications are available for processing a message, individual SIP applications remain independent from one another. An individual application performs a very specific service for a SIP request, without requiring any knowledge of other applications deployed on the system. (The Application Router does require knowledge of deployed applications, and the SipApplicationRouter interface provides for automatic notification of application deployment and undeployment.)

Individual SIP applications may complete their processing of an initial request by proxying or relaying the request, or by terminating the request as a User Agent Server (UAS). If an initial request is proxied or relayed, the SIP container again forwards the request to the Application Router, which selects the next SIP application to provide a service for the request. In this way, the AR can chain multiple SIP applications as needed to process a request. The chaining process is terminated when:

A selected SIP application acts as a UAS to terminate the chain, or
There are no more applications to select for that request. (In this case, the request is sent out.)

When the chain is terminated and the request sent, the SIP container maintains the established path of applications for processing subsequent requests, and the AR is no longer consulted.

Figure 5-1 shows the use of an Application Router for applying multiple service to a SIP request.

Figure 5-1 Composed Application Model

Description of "Figure 5-1 Composed Application Model"

Note that the AR may select remote as well as local applications. The chain of services need not reside within the same Converged Application Server container.

Using the Default Application Router

Converged Application Server includes a Default Application Router (DAR), which provides the basic functionality described in the SIP Servlet Specification v2.0 (http://jcp.org/en/jsr/detail?id=359), Appendix C: Default Application Router.

The DAR JSON Configuration File

Converged Application Server lets you use a simple configuration text file that follows JavaScript Object Notation (JSON)-based application composition rules. The configuration file consists of an array of chains, each containing a criteria followed by an array of applications that form the application chain in JSON form. The criteria is expressed using a JSON encoding of rule language specified in Appending D SIP Request Object Model of Java Specification Requests (JSR)-359.

In Example 5-1, the DAR invokes two applications on an INVITE request with the host part of the From header as “example.com". The applications are identified by their names as defined in the application deployment descriptors. The subscriber identity returned is the URI from the From and To header respectively for the two applications. The DAR does not return any route to Converged Application Server and maintains the invocation state in the stateInfo as the index of the last application in the list.

Example 5-1 DAR JSON Configuration File

{
  "chains": [
    {
      "description": "Example Application Chain",
      "criteria": {
        "and": {
          "equal": {
            "request.method": "INVITE"
          },
          "contains": {
            "ignore-case": "true",
            "request.from.uri.host": "example.com"
          }
        }
      },
      "applications": [
        {
          "name": "OriginatingCallWaiting",
          "subscriber": "request.from",
          "region": "ORIGINATING",
          "route-modifier": "NO_ROUTE"
        },
        {
          "name": "CallForwarding",
          "subscriber": "request.to",
          "region": "TERMINATING",
          "route-modifier": "NO_ROUTE"
        }
      ]
    }
  ]
}

Example 5-2 shows a criteria element excerpted from a DAR JSON configuration file.

Example 5-2 DAR Criteria Element

"criteria": {
  "and": [
    { "equal": { "request.method": "INVITE" }},
    { "equal": { "request.to.uri.port": 5060 }},
    { "contains": {
      "ignore-case": "true",
      "request.from.uri.host": "example.com"
    }
  }]
},

The relevant JSON objects in a DAR configuration file are:

chains: An array of application chains. Each element in the array represents one application chain.
description: A description of the application chain.
criteria: The criteria contains JSON encoded rules that are based on the object model specified in Appendix D SIP Request Object Model of JSR-359. When this predicate evaluates to true, the chain is chosen for handling the request.
applications: An array of applications in this chain. This element contains the data for populating the SipApplicationRouterInfo object. Each application contains the following elements:
- name: Name of the application as known to Converged Application Server.
- subscriber: The SIP header which forms the identity of the subscriber that DAR returns. This is specified according to the object model in Appendix D SIP Request Object Model of JSR-359. Alternatively, it can return any string.
- region: The routing region that can be one of the strings "ORIGINATING", "TERMINATING", or "NEUTRAL".
- routes: An array of SIP URIs indicating the routes as returned by the Application Router. It can be an empty string.
- route-modifier: A route modifier that can be one of the strings "ROUTE", "ROUTE_BACK", or "NO_ROUTE".

Legacy DAR Configuration Files

For backwards compatibility, Converged Application Server supports DAR property files as described in this section.

Each line of the DAR properties file specifies one or more SIP methods, and is followed by SIP routing information in comma-delimited format. The DAR initially reads the properties file on startup, and then reads it each time a SIP application is deployed or undeployed from the container.

To specify the location of the configuration file used by the DAR, configure the properties using the Administration Console, as described in "Configuring a Custom Application Router", or include the following parameter when starting the Converged Application Server instance:

-Djavax.servlet.sip.ar.dar.configuration

(To specify a property file, rather than a URI, include the prefix file:///) This Java parameter is specified at the command line, or it can be included in your server startup script.

See Appendix C in the SIP Servlet Specification v1.1 (http://jcp.org/en/jsr/detail?id=289) for detailed information about the format of routing information used by the Default Application Router.

Note that the Converged Application Server DAR accepts route region strings in addition to “originating," “terminating," and “neutral." Each new string value is treated as an extended route region. Also, the Converged Application Server DAR uses the order of properties in the configuration file to determine the route entry sequence; the state_info value has no effect when specified in the DAR configuration.

Configuring a Custom Application Router

In contrast to DAR, which is property-file driven, a Custom Application Router is implemented as a Java class, which allows for complex decision-making processes.

If you develop a custom Application Router, you must store the implementation for the AR in the /approuter subdirectory of the domain home directory. Supporting libraries for the AR can be stored in a /lib subdirectory within /approuter. (If you have multiple implementations of SipApplicationRouter, use the -Djavax.servlet.sip.ar.spi.SipApplicationRouterProvider option at startup to specify which one to use.)

Note:

In a clustered environment, the custom AR is deployed to all engine tier instances of the domain; you cannot deploy different AR implementations within the same domain.

Converged Application Server provides several configuration parameters to specify the AR class and to pass initialization properties to the AR or AR. To configure these parameters using the Administration Console:

Log in to the Administration Console for your domain.
Select the SIP Server node in the left pane.
Click the Configuration tab and then select the Application Router subtab.
Use the options on the Application Router pane to configure the custom AR:
- Use Custom Application Router: Select this option to use a custom AR instead of the Default AR. Note that you must restart the server after selecting or clearing this option, to switch between using the DAR and a custom AR.
- Use Json form configuration file: Select this to load the AR configuration from a JavaScript Object Notation (JSON) file instead of a property file. For more information on the format of this file, see "The DAR JSON Configuration File".
- Custom Application Router filename: Specify only the filename of the custom AR (packaged as a JAR) to use. The custom AR implementation must reside in the $DOMAIN_HOME/approuter subdirectory.
- Default application name: The name of a default application that the container should call when the custom AR cannot find an application to process an initial request.
  If no default application is specified, the container returns a 500 error if the AR cannot select an application.
  
  Note:
  You must first deploy an application before specifying its name as the value of Default application name.
- Application Router configuration data: Enter properties to pass to the AR in the init method. The options are passed either to the DAR or custom AR, depending on whether the Use Custom AR option is selected.
  All configuration properties must conform to the Java Properties format. DAR properties must further adhere to the detailed property format described in Appendix C of the SIP Servlet Specification v1.1 (http://jcp.org/en/jsr/detail?id=289). Each property must be listed on a separate, single line without line breaks or spaces, as in:
```
INVITE:("OriginatingCallWaiting","DAR:From","ORIGINATING","","NO_ROUTE","0"),("CallForwarding","DAR:To","TERMINATING","","NO_ROUTE","1")
SUBSCRIBE:("CallForwarding","DAR:To","TERMINATING","","NO_ROUTE","1")
```
  You can optionally specify AR initialization properties when starting the Converged Application Server instance by including the -Djavax.servlet.sip.ar.dar.configuration Java option. (To specify a property file, rather than a URI, include the prefix file:///) If you specify the Java startup option, the container ignores any configuration properties defined in AR configuration data (stored in sipserver.xml). You can modify the properties in AR configuration data at any time, but the properties are not passed to the AR until the server is restarted with the -Djavax.servlet.sip.ar.dar.configuration option omitted.
Click Save.

See Appendix C in the SIP Servlet Specification v2.0 (http://jcp.org/en/jsr/detail?id=359) for more information about the function of the AR. See also the SIP Servlet v2.0 API for information about how to implement a custom AR.