5 Composing SIP Applications

This chapter describes how to use Oracle Communications Converged Application Server application composition features.

Note:

The Session Initiation Protocol (SIP) Servlet v2.0 specification (https://jcp.org/en/jsr/detail?id=359) describes a formal application selection and composition process, which is fully implemented in Converged Application Server. Use the SIP Servlet v2.0 techniques, as described in this document, for all new development. Application composition techniques described in earlier versions of Converged Application Server are now deprecated.

Converged Application Server provides backwards compatibility for applications using version 1.0 composition techniques, provided that:

You do not configure a custom Application Router.
You do not configure the Default Application Router properties.

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.

Application Router Behavior

When Converged Application Server receives an initial request from an external entity, or when an application acts as a User Agent Client (UAC) and sends an initial request with a new routing directive, the application selection process is started fresh. In that case, the Application Router is called with the following information:

The SipServletRequest.
The new routing directive.

Based on the supplied information, the configuration of which subscriber subscribes to which set of applications, and any other information that it may wish to use, for example, time of day, network condition, or external subscriber profile database, the Application Router returns the following information:

The name of the selected application.
The subscriber identity that the selected application is to serve.
The routing region that the application serves.
An array of zero or more routes to push (the routes array).
A route modifier that tells the container how to interpret the route.
An optional stateInfo serializable object.

The Application Router can return routes to Converged Application Server using its SipApplicationRouterInfo.getRoutes() method. The routes can be external or internal. External routes are used by the Application Router to instruct Converged Application Server to send the request externally. An internal route is returned when the Application Router wishes to modify the popped route header as seen by the application code, through the SipServletRequest.getPoppedRoute() method. When the request is received by Converged Application Server, the request may have had a Route header belonging to Converged Application Server, which it removes and makes available as described in "Popped Route Header". The route modifier returned by the Application Router tells Converged Application Server how to use the routes returned by it and also how the popped route needs to be presented.

The route modifier can be one of the following enum values:

ROUTE indicates that SipApplicationRouterInfo.getRoutes() returns valid routes. Converged Application Server decides if they are external or internal. All of the routes returned must be of the same type, so Converged Application Server can make the determination by examining the first route only.
ROUTE_FINAL indicates that SipApplicationRouterInfo.getRoutes() returns valid routes. The returned route can contain internal routes, external routes, or both. Converged Application Server pushes all routes returned by the Application Router.
ROUTE_BACK directs Converged Application Server to push its own route before pushing the routes obtained from SipApplicationRouterInfo.getRoutes().
NO_ROUTE indicates that Application Router is not returning any routes and the SipApplicationRouterInfo.getRoutes() value, if any, should be disregarded.

The behavior of the container with respect to the route modifiers is explained in "Procedure for Routing an Initial Request".

The stateInfo serializable object is useful for the Application Router to store state information from one invocation to the next. An Application Router implementation may choose to put any information in the stateInfo object, and this object is opaque to Converged Application Server and not accessible to the applications. Typically, an Application Router implementation may store information such as subscriber identity, the name of the application last invoked, and a precomputed list of applications that are to be invoked next. Application Router must not change the stateinfo after it is returned to Converged Application Server, and each result returned to Converged Application Server must contain a different stateinfo object.

If the selected application subsequently proxies or sends a new initial request based on the first one with a CONTINUE or REVERSE routing directive, the Application Router is called again. This time, in addition to the SipServletRequest and the routing directive, it is also supplied with the stateInfo object that it previously returned. In this way, the Application Router delegates the maintenance of the application selection state to Converged Application Server, and thus it can be stateless with respect to each initial request it processes.

If the Application Router determines that no application is selected to service a request, it returns null as the name.

Note:

For details on the API described in this section, see the Java SIP Servlet API 2.0 JavaDocs.

Order of Routing Regions

Because proximity of an application to its subscriber confers priority, it is beneficial for the management of feature interaction that originating applications are closest to the caller, and that terminating applications are closest to the callee. This can be satisfied if the following rules are followed:

The originating region applications should be invoked first followed by terminating region applications.
The applications that service a subscriber are contiguous (that is, no insertion of applications that service other subscribers in between).

On the other hand, it is entirely possible that the Application Router progresses directly to the terminating region if the caller is not a subscriber, or the caller does not subscribe to any applications. It is also possible that the application server does not serve any originating subscribers or has determined through some means that the originating applications have already been invoked and it should only look for terminating applications.

Inter-Container Application Routing

Converged Application Server supports applications distributed across multiple containers. The Application Router may return external routes in its SipApplicationRouterInfo.getRoutes() method that point to other application servers that it wishes the request to be routed to. Converged Application Server then pushes the routes onto the Route header stack of the request and sends the request externally. If this request arrives at another JSR-359 compliant container, it invokes the Application Router residing in that container so that the application selection process may continue. The first Application Router may pass any state information to the second Application Router by embedding it in the Route header. This is in accordance with the cascaded services model (SERL) as the applications can reside on different hosts and still participate in the application composition process.

Note:

Some architectures require that the originating and terminating applications be hosted on different servers. The deployer can easily accomplish this by configuring the Application Routers such that one server hosts only originating applications and the other only terminating applications. Either the subscriber data can be partitioned such that the first server only serves originating users and the second serves terminating users. Alternatively, the Application Routers can collaborate by passing some state information in the Route headers, indicating for example that the first server has already completed the invocation of originating services.

Popped Route Header

On receiving an initial request that contains a SIP Route header (preloaded) or receiving a subsequent request with a Route header (converted from a Record-Route header), Converged Application Server determines if the request is intended for itself (based on local policy, for example IP addresses of interfaces or representative DNS entries). If it is, Converged Application Server removes the Route header before passing it to any application or the Application Router.

A side effect of removing a SIP Route message header before presenting the request to applications (and the Application Router) is that applications do not have access to the SIP Route message header and its associated information. Certain architectures utilize the SIP Route header for transporting application and other related information.

The following methods return the Route header popped by the container:

Address getPoppedRoute();
Address getInitialPoppedRoute();

If application composition is being used, the values returned by those methods may differ. The getPoppedRoute method returns the route popped before the current application invocation in the composition chain. The getInitialPoppedRoute method returns the route popped by Converged Application Server when it first received the request.

If no header is popped by Converged Application Serer on an initial request, both methods return null.

Both methods return the Route header as an Address, so, parameters added to the Record-Route header using the Proxy.getRecordRouteURI() method should be retrieved not from the popped route Address directly, but from the URI of the popped route Address.

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"
    xsi:schemaLocation="http://www.oracle.com/sdp/easyapp-def easyapp-def.xsd"
    xmlns="http://www.oracle.com/sdp/easyapp-def/" >
  <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 OCCAS 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.182.101.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.

Session Key-Based Request Targeting

The SIP Servlet v2.0 specification provides a mechanism for associating an initial request with an existing SipApplicationSession object. This mechanism is called session key-based targeting. Session key-based targeting is used to direct initial requests having a particular subscriber (request URI) or region, or other feature to an already-existing SipApplicationSession, rather than generating a new session.

Accessing SIP Applications Using SIP Application Index Keys

To use this targeting mechanism with an application, you create a method that generates a unique key and annotate that method with @SipApplicationKey. When the SIP container selects that application (for example, as a result of the AR choosing it for an initial request), it obtains a key using the annotated method, and uses the key and application name to determine if the SipApplicationSession exists. If one exists, the container associates the new request with the existing session, rather than generating a new session.

Note:

If you develop a spiral proxy application using this targeting mechanism, and the application modifies the record-route more than once, it must generate different keys for the initial request, if necessary, when processing record-route hops. If it does not, then the application cannot discriminate record-route hops for subsequent requests.

See section 18-30 in the SIP Servlet Specification v2.0 (http://jcp.org/en/jsr/detail?id=359) for more information about using session key-based targeting.

Application Composition and SIP-HTTP Convergence

The @SipApplicationKey annotation is a useful tool you can employ to process HTTP requests in a converged module. You can set up a JavaServer page to manage the call states of a SIP application, an HTTP servlet to process HTTP requests and a proxy application to proxy the call request to more than one user agent server (UAS).

Converged Application Server provides an example called convergence_indexkey that shows how SIP application session index keys can be used to access SIP applications. It uses application composition whereby more than one application is called to process the same SIP request; and also shows SIP-HTTP session convergence.

The convergence_indexkey example employs the JSR 289 API interfaces called javax.servlet.sip.ConvergedHttpSession and javax.servlet.sip.SipSessionsUtil. The example is packaged as an exploded EAR file containing a web application and the Enterprise Java Beans (EJB).

Note:

The web application and EJB access do not require the configuration file sip.xml.

For more information about accessing convergence_indexkey, see "Examples".

Join and Replaces Header Support

Converged Application Server provides support for the use of both the Join and Replaces headers. To learn how to create SIP applications that use the functionality provided by the Join and Replaces headers, refer to the JSR 359 documentation and APIs.

About the Join Header

The Join header, defined in RFC 3911, is for use with SIP Call Control and Multi-Party applications. The Join header logically joins an existing SIP dialog with a new SIP dialog. You can use this to enable features such as Call Forwarding, Message Screening, and Call Center Monitoring.

The Join header contains information an application can use to match an existing SIP dialog to a new dialog. You can use the Join header to add a new dialog or SIP application session to an existing SIP application session in the same way that an encoded URI is used. This is achieved by setting the call-id, to-tag, and from-tag in the Join header of the SIP INVITE to match that of the existing dialog.

About the Replaces Header

The Replaces header, defined in RFC 3891, logically replaces an existing SIP dialog with a new SIP dialog. You can use this functionality to enable features such as Attended Call Transfer and Call Pickup.

The Replaces header contains information used to match and replace an existing SIP dialog (using the call-id, to-tag, and from-tag) to the newly created dialog. The Join header can be used to replace an existing SIP session associated with a SIP application session with a new dialog/session. This is achieved by setting the call-id, to-tag, and from-tag in the Replaces header of the INVITE to match that of an existing dialog.

Note:

The SIP application must determine to send a BYE message using the original dialog. Converged Application Server does not automatically send a BYE message to terminate the original dialog.

Enabling Support for Join and Replaces Headers

Support for the Join and Replaces headers is disabled by default. If you have applications that need to use the Join and Replaces headers, you must enable Converged Application Server to handle these types of headers.

Note:

Enabling support for the Join and Replaces header may affect the performance of Converged Application Server. When enabling this feature ensure that your deployment of Converged Application Server has enough memory, computing power, and network bandwidth to function properly using Join- and Replaces-enabled applications.

To enable support for Join and Replaces headers, edit the entry for the –Dwlss.dialog.index.enabled=false command in the startWebLogic.sh script, and set its value to true. The startWebLogic.sh script is located in the DOMAIN_HOME/bin directory, where DOMAIN_HOME is the domain's home directory. When support for Join and Replace headers is enabled, the entry in the startWebLogic.sh script appears as shown below:

–Dwlss.dialog.index.enabled=true

See the Converged Application Server Administrator's Guide learn more about the startWebLogic.sh script and the start-up options it controls.