| Oracle® Communications Converged Application Server Developer's Guide Release 5.1 Part Number E27707-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Converged Application Server Developer's Guide Release 5.1 Part Number E27707-01 |
|
|
PDF · Mobi · ePub |
This chapter describes how to use Oracle Communications Converged Application Server application composition features.
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 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 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.
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 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 9-1 shows the use of an Application Router for applying multiple service to a SIP request.
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.
Converged Application Server includes a Default Application Router (DAR), which provides 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 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 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.
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 SipServer node in the left pane.
Click the Configuration tab and then the Application Router tab.
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 (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.
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.Select Save.
Note:
These configuration options are persisted as XML elements in the sipserver.xml file. See the chapter “Engine Tier Configuration Reference (sipserver.xml)” in the Converged Application Server Administrator's Guide for more information.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.
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.
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
The schema definition for the configuration file is located in the same location. It is named app-easydef.xsd.
Figure 9-1 shows a sample configuration for the prebuilt CAR implementation:
Example 9-1 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 Oracle Communications 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
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
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.
As shown in Figure 9-2, each converged application deployed to the Converged Application Server container has a unique SipApplicationSession, which can contain one or more SipSession and HttpSession objects.
Figure 9-2 Sessions in a Converged Application
The API provided by javax.servlet.SipApplicationSession enables you to iterate through all available sessions in a given SipApplicationSession. It also provides methods to encode a URL with the unique application session when developing converged applications.
In prior releases, Converged Application Server extended the basic SIP Servlet API to provide methods for:
Creating new HTTP sessions from a SIP Servlet
Adding and removing HTTP sessions from SipApplicationSession
Obtaining SipApplicationSession objects using either the call ID or session ID
Encoding HTTP URLs with session IDs from within a SIP Servlet
This functionality is now provided directly as part of the SIP Servlet API version 1.1, and the proprietary API (com.bea.wcp.util.Sessions) is now deprecated. Table 9-0 lists the SIP Servlet APIs to use in place of now deprecated methods. See the SIP Servlet v1.1 API JavaDoc at the Java Community Process web site (JSR 289: SIP Servlet v1.1 at jcp.org) for more information.
Table 9-1 Deprecated com.bea.wcp.util.Sessions Methods
| Deprecated Method (in com.bea.wcp.util.Sessions) | Replacement Method | Description |
|---|---|---|
|
getApplicationSession |
javax.servlet.sip.SipSessionsUtil. getApplicationSession |
Obtains the |
|
getApplicationSessionsByCallId |
None. |
Obtains an Iterator of |
|
createHttpSession |
None. |
Applications can instead cast an |
|
setApplicationSession |
javax.servlet.sip.ConvergedHttpSession. getApplicationSession |
Associates an HTTP session with an existing |
|
removeApplicationSession |
None. |
Removes an HTTP session from an existing |
|
getEncodeURL |
javax.servlet.sip.ConvergedHttpSession. encodeURL |
Encodes an HTTP URL with the |
Note:
Thecom.bea.wcp.util.Sessions API is provided only for backward compatibility. Use the SIP Servlet APIs for all new development. Converged Application Server does not support converged applications that mix the com.bea.wcp.util.Sessions API and JSR 289 convergence APIs.
Specifically, the deprecated Sessions.getApplicationSessionsByCallId(String callId method cannot be used with v1.1 SIP Servlets that use the session key-based targeting method for associating an initial request with an existing SipApplicationSession object. See Section 15.11.2 in the SIP Servlet Specification v1.1 (http://jcp.org/en/jsr/detail?id=289) for more information about this targeting mechanism.
When using a replicated domain, Converged Application Server automatically provides concurrency control when a SIP Servlet modifies a SipApplicationSession object. In other words, when a SIP Servlet modifies the SipApplicationSession object, the SIP container automatically locks other applications from modifying the object at the same time.
Non-SIP applications, such as HTTP Servlets, must themselves ensure that the application call state is locked before modifying it in a replicated environment. This is also required if a single SIP Servlet needs to modify other call state objects, such as when a conferencing Servlet joins multiple calls.
To help application developers manage concurrent access to the application session object, Converged Application Server extends the standard SipApplicationSession object with com.bea.wcp.sip.WlssSipApplicationSession, and adds a two new interfaces, com.bea.wcp.sip.WlssAction and com.bea.wcp.sip.WlssAsynchronousAction, to encapsulate tasks performed to modify the session. When these APIs are used, the SIP container ensures that all business logic contained within the WlssAction and WlssAsynchronousAction objects is executed on a locked copy of the associated SipApplicationSession instance. The sections that follow describe each interface.
Applications that need to read and update a session attribute in a transactional and synchronous manner must use the WlssAction API. WlssAction obtains an explicit lock on the session for the duration of the action. Example 9-2 shows an example of using this API.
Example 9-2 Example Code using WlssAction API
final SipApplicationSession appSession = ...;
WlssSipApplicationSession wlssAppSession = (WlssSipApplicationSession) appSession;
wlssAppSession.doAction(new WlssAction() {
public Object run() throws Exception {
// Add all business logic here.
appSession.setAttribute("counter", latestCounterValue);
sipSession.setAttribute("currentState", latestAppState);
// The SIP container ensures that the run method is invoked
// while the application session is locked.
return null;
}
});
Because the WlssAction API obtains an exclusive lock on the associated session, deadlocks can occur if you attempt to modify other application session attributes within the action.
Applications that need to update a different SipApplicationSession while in the context of a locked SipApplicationSession can perform asynchronous updates using the WlssAsynchronousAction API. This API reduces contention when multiple applications might need to update attributes in the same SipApplicationSession at the same time. Example 9-3 shows an example of using this API.
To compile applications using this API, you need to include wlssapi.jar, and sipservlet.jar to your class path. Both JARs are located in the directory MW_HOME/wlserver_10.3/sip/server/lib.
Example 9-3 Example Code using WlssAsynchronousAction API
SipApplicationSession sas1 = req.getSipApplicationSession(); // SipApplicationSession1 is already locked by the container
// Obtain another SipApplicationSession to schedule work on it
WlssSipApplicationSession wlssSipAppSession = SipSessionsUtil.getApplicationSessionById(conferenceAppSessionId);
// The work is done on the application session asynchronously
appSession.doAsynchronousAction(new WlssAsynchronousAction() {
Serializable run(SipApplicationSession appSession) {
// Add all business logic here.
int counter = appSession.getAttribute("counter");
++ counter;
appSession.setAttribute("counter", counter);
return null;
}
});
Performing the work on appSession in an asynchronous manner prevents nested locking and associated deadlock scenarios.
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.
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 289 documentation and APIs.
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.
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.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.
Converged Application Server provides a setRecordRouteUriTransport API on the WlssProxy interface which will allow proxy applications to set the transport parameter of the Record-Route header, in scenarios where the proxy is aware of the transport supported by the next downstream element.
RFC 3261 (Section 16.6, Item4) states that “The URI SHOULD NOT contain the transport parameter unless the proxy has knowledge (such as in a private network) that the next downstream element that will be in the path of subsequent requests supports that transport.”
The API consists of the method setRecordRouteUriTransport on the WlssProxy interface. This method takes a string value for the required transport. Use the API to set the transport parameter of a Record-Route header as shown in the following code sample:
...
WlssProxy p = (WlssProxy)req.getProxy();
p.setRecordRouteUriTransport("tcp");
...
Converged Application Server provides you with a System property to specify whether SIP Proxy applications that are acting in supervised Proxy mode should be able to modify the content of SIP responses before forwarding such messages upstream. By default, a SIP application will be able to modify the content of a SIP response when that application acts in a supervised Proxy mode.
Converged Application Server reconciles the different approaches specified in JSR289 (Section 10.2.4) and RFC 3261 (Section 16.7, Item 9) by implementing a flag to control the behavior of message content modification by a Proxy application that is functioning in a supervised mode.
The system property is wlss.proxy.setcontent and the default value for the property is true. Maintain this default setting to allow proxy applications in supervised mode to set the content of the responses that such applications forward upstream. To prevent such proxy applications from modifying the content in SIP responses, set the system property wlss.proxy.setcontent to false in the startWebLogic.sh script. The startWebLogic.sh script is located in the DOMAIN_HOME/bin directory, where DOMAIN_HOME is the domain's home directory.
|
 Copyright © 2005, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|