Developing SIP Applications

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Composing SIP Applications

The following sections describe how to use Oracle Communications Converged Application Server application composition features:

Notes: The SIP Servlet v1.1 specification describes a formal application selection and composition process, which is fully implemented in Oracle Communications Converged Application Server. Use the SIP Servlet v1.1 techniques, as described in this document, for all new development. Application composition techniques described in earlier versions of Oracle Communications Converged Application Server are now deprecated.
Note: Oracle Communications Converged Application Server provides backwards compatibility for applications using version 1.0 composition techniques, provided that:

 

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 should process the request. In Oracle Communications Converged Application Server, all initial requests are first delivered to the AR, which determines the application used to process the request.

Oracle Communications Converged Application Server provides a default Application Router, which can be configured using a text file. However, most installations will 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 should 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 should perform 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:

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

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 Oracle Communications Converged Application Server container.

 

Using the Default Application Router

Oracle Communications Converged Application Server includes a Default Application Router (DAR) having the basic functionality described in the SIP Servlet Specification v1.1, Appendix C: Default Application Router. In summary, the Oracle Communications Converged Application Server 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 Oracle Communications 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 for detailed information about the format of routing information used by the Default Application Router.

Note that the Oracle Communications 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 Oracle Communications 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

By default Oracle Communications Converged Application Server 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.

Oracle Communications 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:

  1. Access the Administration Console for your domain.
  2. Select the SipServer node in the left pane.
  3. Select Configuration->Application Router in the right pane.
  4. Use the options on the Application Router pane to configure the custom AR:
    • Use Custom AR: 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.
    • Custom AR 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.
    • AR 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. 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 Oracle Communications 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.

    • Default application name: Enter 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.
  5. Select Save.
Note: These configuration options are persisted as XML elements in the sipserver.xml file. See the Configuration Reference Manual for more information.

See Section 15 in the SIP Servlet Specification v1.1 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.

 

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 should 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 for more information about using session key-based targeting.


  Back to Top       Previous  Next