Converged Application Server Behavior

Converged Application Server instantiates and initializes the Application Router and provides to it the initial list of deployed applications. When new applications are deployed or when applications are undeployed, Converged Application Server also inform the Application Router.

Converged Application Server receives an initial request from an external entity or from an application, and invokes the Application Router to obtain the name of the application to service the initial request, and then dispatches the request to the main servlet within the application. Converged Application Server also maintains application selection state including:

The routing directive associated with this request.
Routing region (originating, terminating, or neutral).
Actions on the route returned from the Application Router in conjunction with the route modifier.
Arbitrary, opaque state information returned from the Application Router.

Procedure for Routing an Initial Request

When Converged Application Server receives a new initial request, it first creates and initializes the various pieces of application selection state as follows:

Directive:
- If a request is received from an external SIP entity, the directive is set to NEW.
- If a request is received from an application, the directive is set either implicitly or explicitly by the application.
Application router stateInfo:
- If a request is received from an application and the directive is CONTINUE or REVERSE, stateInfo is set to that of the original request with which this request is associated.
- Otherwise, stateInfo is not set initially.
Subscriber URI: Not set initially.
Routing Region: Not set initially.

With the application selection state initialized, the following procedure is executed:

The SipApplicationRouter.getNextApplication() method of the Application Router object is called. The Application Router returns a SipApplicationRouterInfo object, named result for the purposes of this discussion.
The result.getRouteModifier() method is checked.
- If result.getRouteModifier() is ROUTE, routes are retrieved using result.getRoutes().
  - If the first returned route is external (does not belong to Converged Application Server), all of the routes on the request's Route header stack are pushed, and the request is sent externally. Note that the first returned route becomes the top route header of the request.
  - If the first returned route is internal, Converged Application Server makes it available to the applications using the SipServletRequest.getPoppedRoute() method and ignores the remaining ones, if any. That allows the Application Router to modify the popped route before passing it to the application.
- If result.getRouteModifier() is ROUTE_FINAL, all of the routes, regardless of whether the route is internal or external, are pushed on the request's route header stack and the request is sent.
- If result.getRouteModifier() is ROUTE_BACK, a route is pushed back to Converged Application Server followed by all of the routes obtained from result.getRoutes() and the request is sent externally. When the request eventually returns, Converged Application Server sets the routing directive to CONTINUE and also retrieve the Application Router state (routingRegion, stateInfo) and passes it in the call to getNextApplication() to continue processing the application chain.
  
  To retrieve the Application Router state, the container route in the request originally sent externally includes Application Router state (routingRegion and stateinfo) encoded as a route parameter.
- If result.getRouteModifier() is NO_ROUTE, result.getRoutes() is disregarded and processing continues.
The result.getNextApplicationName() is checked.
- If result.getNextApplicationName() is not null:
  - The application selection state on the SipSession: stateInfo is set to result.getStateInfo(), region to result.getRegion(), and URI to result.getSubscriberURI().
  - A servlet is selected from the application.
- If result.getNextApplicationName() is null:
  - If the Request-URI is not addressed to this container, or if there are one or more Route headers, the request is sent out according to the standard SIP mechanism.
  - If the Request-URI is addressed to Converged Application Server and there is no Route header, the request is not sent since it will cause a loop. Instead, Converged Application Server rejects the request with a 404 Not Found final response with no Retry-After header.

The effect of sending the request externally, for example, as a result of ROUTE_FINAL or ROUTE_BACK routing directive, can cause the message to come back to Converged Application Server and be presented to the Application Router again. Converged Application Server optimizes this case by calling getNextApplication() directly instead of sending the message.

Note:

As a guideline, it is strongly recommended that applications to not rely on Via or Record-Route headers for their application logic, since SIP Servlet container compliance may vary. Applications should instead use the SipServletMessage methods getLocalXXX, getRemoteXXX if they are interested in the upstream entity.

If SipApplicationRouter.getNextApplication() throws an exception, Converged Application Server sends a 500 Server Internal Error final response to the initial request.

Application Router Packaging and Deployment

Converged Application Server loads and instantiates Application Router implementations. To be portable across containers, the Application Router implementation must be packaged in accordance with the rules specified by the Java SE Service Provider framework. Specifically, the JAR file containing the Application Router implementation must include the META-INF/services/javax.servlet.sip.ar.spi.SipApplicationRouterProvider file. The contents of that file indicate the name of the concrete public subclass of the javax.servlet.sip.ar.spi.SipApplicationRouterProvider class. The concrete subclass must have a no-arg public constructor.

As specified by the Service Provider framework, the providers may be installed by:

Including the provider JAR in the system classpath.
Including the provider JAR in the extension class path.
Container-specific means.

If the container uses classpath-based deployment, the first Application Router JAR file found in the classpath is installed. To avoid ambiguity when multiple Application Router implementations are present in the classpath, the javax.servlet.sip.ar.spi.SipApplicationRouterProvider system property can override loading behavior and force a specific provider implementation to be used.

Using the Legacy Custom Application Router

The Converged Application Server provides a built-in CAR that you can use. To use the CAR implementation, you supply configuration parameters to the CAR in the form of an XML file. The file specifies the applications in the chain, and the rules for targeting them.

The rules can impose conditions on application targeting based on factors such as the user identity or the request URI.

To use the prebuilt CAR, first create the configuration file that controls the behavior of the CAR.

After creating the configuration file, follow the steps listed in "Configuring a Custom Application Router" to apply the built-in CAR. In the configuration fields, provide the following values:

For the custom AR filename, use approuter-SDP.jar
In the AR configuration data field, specify the name of the configuration file you created as the value of the configFileName variable. For example:

configFileName=./app.xml
As the second line of the AR configuration data, enter the following:

byPassIfAppIsNotWorking=true

The following section provides more information on the prebuilt CAR configuration file format.

Configuring the Legacy Custom Application Router

You control the prebuilt custom application router using an XML-based configuration file. The file lets you specify the application chain and the conditions for invoking the applications.

The configuration file is specified by configFileName property in the AR Configuration Data field of the UI.

You place the file in the following location:

Domain_Home/approuter/lib, where Domain_Home is the domain's home directory.

The schema definition for the configuration file is located in the same location. It is named app-easydef.xsd.

Example 5-3 shows a sample configuration for the prebuilt CAR implementation:

Example 5-3 Example Prebuilt CAR Configuration File

<app-router-conf xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.oracle.com/sdp/easyapp-def" xsi:schemaLocation="http://www.oracle.com/sdp/easyapp-def easyapp-def.xsd">
  <external-resource>
    <file>
      <file-path>./approuter/lib/user.properties</file-path>
    </file>
  </external-resource>
  <user-identity-header>From</user-identity-header>
  <terminating>
    <app>
      <app-name>basic-call-app</app-name>
      <index>0</index>
      <mapping-rule>
        <protocol>SIP</protocol>
        <pattern>
          <and>
            <equal>
              <var>request.method</var>
              <value>INVITE</value>
            </equal>
            <not>
              <contains>
                <var>request.uri</var>
                <value>voicemail</value>
              </contains>
            </not>
          </and>
        </pattern>
        <subscriber-identity>.*</subscriber-identity>
        <request-uri>.*</request-uri>
      </mapping-rule>
    </app>
    <app>
      <app-name>presence-app</app-name>
      <index>1</index>
      <mapping-rule>
        <protocol>SIP</protocol>
        <pattern>
          <and>
            <equal>
              <var>request.method</var>
              <value>SUBSCRIBE</value>
            </equal>
            <equal>
              <var>request.method</var>
              <value>PUBLISH</value>
            </equal>
          </and>
        </pattern>
        <subscriber-identity>.*</subscriber-identity>
        <request-uri>.*</request-uri>
      </mapping-rule>
    </app>
    <app>
      <app-name>RouteToExternalURI</app-name>
      <index>2</index>
      <externalURI>sip:media@voicemail.com</externalURI>
      <mapping-rule>
        <protocol>SIP</protocol>
        <pattern>
          <and>
            <equal>
              <var>request.method</var>
              <value>INVITE</value>
            </equal>
            <contains>
              <var>request.uri</var>
              <value>voicemail</value>
            </contains>
          </and>
        </pattern>
        <subscriber-identity>.*</subscriber-identity>
        <request-uri>.*</request-uri>
      </mapping-rule>
    </app>
  </terminating>
</app-router-conf>

Notice the application named RouteToExternalURI, in the final app-name element. This is a symbolic application name that enables routing to an external URI. The CAR implementation adds the external URI to SipApplicationRouterInfo, which directs the container to route the request to the external URI. You can configure more than one special application, each with its own name, pattern, and index.

The pattern element syntax is the same as the pattern syntax used in sip.xml

The Application Router must provide the user identity of a subscriber to retrieve subscriber information from external sources. For the IMS environment, the P-Asserted-Identify header identifies the user by default. For non-IMS environments, the From header identifies the user. You can specify which header should be used to extract the user identity using the user-identity-header element.

For example:

<app-router-conf xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.oracle.com/sdp/app-def app-def.xsd"
    xmlns="http://www.oracle.com/sdp/app-def" >
  <external-resource>
      <file>
         <file-path>./approuter/lib/user.properties</file-path>   
      </file>    
  </external-resource>
  <user-identity-header>From</user-identity-header>

To access a database, you must specify the JNDI name for the JDBC connection the SQL statement that selects the subscriber information.

For example:

  <external-resource>
      <rdbms>
          <jdbc-jndi-name>jdbc/OwlcsLs</jdbc-jndi-name>
          <sql>select appname from userapp where aor=?</sql>
      </rdbms>      
  </external-resource>

In this example, appname identifies the column name in the table that contains the applications for the subscriber. The aor variable is the column name that represents the subscriber. The parameter for this SQL will be the P-Asserted-Identity header or From header of the initial request, as defined by the user-identity-header element.

If an HSS system is used as the external source, the diameter channel must be set up for each server, as specified in the Converged Application Server Administrator's Guide.

Additional information you need to specify in the configuration file includes:

file-path: The diameter configuration file path
service-indication: The Service-Indication AVP value which is defined in the 3GPP 29.328 section 7.4
app-element: The customer AVP name. Its value is the applications subscribed to by the subscriber. In the context of the HSS, the app-element is the value of the ServiceData AVP.

The configuration file may be like:

   <external-resource>
      <hss>
         <file-path>./approuter/lib/hssconfig.xml</file-path>
         <service-indication>ARTest</service-indication>
         <app-element>apps</app-element>    
      </hss>      
  </external-resource>

The diameter configuration file, hssconfig.xml in the example, must comply with the Converged Application Server diameter.xml format, and be located in the following directory:

Domain_Home/approuter/lib, where Domain_Home is the domain's home directory.

An example of the hssconfig.xml file is as follows:

<?xml version="1.0" encoding="utf-8"?>
<diameter xmlns="http://www.bea.com/ns/wlcp/diameter/300" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance">
  <configuration>
    <name>hssclient</name>
    <target>engine1</target>
    <target>engine2</target>
    <host>hssclient</host>
    <realm>bea.com</realm>
 
    <message-debug-enabled>true</message-debug-enabled>
 
      <application>
       <name>WlssShApplication</name>
        <class-name>com.bea.wcp.diameter.sh.WlssShApplication</class-name>
        <param>
          <name>destination.host</name>
          <value>hss</value>
        </param>
      </application>
 
      <peer>
        <host>hss</host>
        <address>10.0.0.206</address>
        <port>3900</port>
      </peer>
  </configuration>
</diameter>

Properties can also reside externally. This may be useful in testing or evaluation scenarios. In this case, you only need to configure the file path.

  <external-resource>
      <file>
         <file-path>./approuter/lib/user.properties</file-path>   
      </file>     
  </external-resource>

The file, user.properties in the example, should contain configuration information consisting of name-value pairs, and should be parsable by a Java Properties class. It should be located in the following directory:

Domain_Home/approuter/lib, where Domain_Home is the domain's home directory.

The format of each line in the user properties file should be subscriber name followed by the applications available to the subscriber.

For example:

alice@example.com=proxyregistrar,app2,app1bob@example.com=proxyregistrar,app1

The index element specifies the order of invocation for the applications. The lower number has higher priority. The index must start at 0.

The mapping-rule element is used to determine if the application should be invoked by a special initial request. The value of subscriber-identity and request-uri must be Java regular expression. Only if the initial request matches all conditions, including protocol, pattern, subscriber-identity and request-uri, can the request be targeted to the application.