5 Composing SIP Applications

This chapter describes how to use OWLCS application composition features, in the following sections:

Section 5.1, "Application Composition Model"
Section 5.2, "Using the Default Application Router"
Section 5.3, "Configuring a Custom Application Router"
Section 5.4, "Session Key-Based Request Targeting"
Note:
The SIP Servlet v1.1 specification (http://jcp.org/en/jsr/detail?id=289) describes a formal application selection and composition process, which is fully implemented in OWLCS. Use the SIP Servlet v1.1 techniques, as described in this document, for all new development. Application composition techniques described in earlier versions of OWLCS are now deprecated.
OWLCS provides backwards compatibility for applications using version 1.0 composition techniques, provided that:
- you do not configure a custom Application Router, and
- you do not configure Default Application Router properties.

5.1 Application Composition Model

Application composition is the process of "chaining" multiple SIP applications into a logical path to apply services to a SIP request. The SIP Servlet v1.1 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 OWLCS, all initial requests are first delivered to the AR, which determines the application used to process the request.

OWLCS provides a default Application Router, which can be configured using a text file. However, most installations can develop and deploy a custom Application Router by implementing the SipApplicationRouter interface. A custom Application Router enables you to consult data stores when determining which SIP application must handle a request.

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 OWLCS container.

5.2 Using the Default Application Router

OWLCS includes a Default Application Router (DAR) having the basic functionality described in the SIP Servlet Specification v1.1 (http://jcp.org/en/jsr/detail?id=289), Appendix C: Default Application Router. In summary, the OWLCS DAR implements all methods of the SipApplicationRouter interface, and is configured using the simple Java properties file described in the v1.1 specification.

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 OWLCS 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, therefore 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 OWLCS 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 OWLCS 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.

5.3 Configuring a Custom Application Router

By default OWLCS uses its DAR implementation.

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.

See Section 15 in the SIP Servlet Specification v1.1 (http://jcp.org/en/jsr/detail?id=289) for more information about the function of the AR. See also the SIP Servlet v1.1 API for information about how to implement a custom AR.

5.4 Session Key-Based Request Targeting

The SIP Servlet v1.1 specification also 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. 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 15 in the SIP Servlet Specification v1.1 (http://jcp.org/en/jsr/detail?id=289) for more information about using session key-based targeting.