2 Developing Converged Applications

This chapter describes how to develop converged HTTP and SIP applications with OWLCS, in the following sections:

2.1 Overview of Converged Applications

In a converged application, SIP protocol functionality is combined with HTTP or Java EE components to provide a unified communication service. For example, an online push-to-talk application might enable a customer to initiate a voice call to ask questions about products in their shopping cart. The SIP session initiated for the call is associated with the customer's HTTP session, which enables the employee answering the call to view customer's shopping cart contents or purchasing history.

You must package converged applications that utilize Java EE components (such as EJBs) into an application archive (.EAR file). Converged applications that use SIP and HTTP protocols must be packaged in a single SAR or WAR file containing both a sip.xml and a web.xml deployment descriptor file.You can optionally package the SIP and HTTP Servlets of a converged application into separate SAR and WAR components within a single EAR file.

The HTTP and SIP sessions used in a converged application can be accessed programmatically through a common application session object. The SIP Servlet API also helps you associate HTTP sessions with an application session.

2.2 Assembling and Packaging a Converged Application

The SIP Servlet specification fully describes the requirements and restrictions for assembling converged applications. The following statements summarize the information in the SIP Servlet specification:

  • Use the standard SIP Servlet directory structure for converged applications.

  • Store all SIP Servlet files under the WEB-INF subdirectory; this ensures that the files are not served up as static files by an HTTP Servlet.

  • Include deployment descriptors for both the HTTP and SIP components of your application. This means that both sip.xml and web.xml descriptors are required. A weblogic.xml deployment descriptor may also be included to configure Servlet functionality in the OWLCS container.

  • Observe the following restrictions on deployment descriptor elements:

    • The distributable tag must be present in both sip.xml and web.xml, or it must be omitted entirely.

    • context-param elements are shared for a given converged application. If you define the same context-param element in sip.xml and in web.xml, the parameter must have the same value in each definition.

    • If either the display-name or icons element is required, the element must be defined in both sip.xml and web.xml, and it must be configured with the same value in each location.

2.3 Working with SIP and HTTP Sessions

As shown in Figure 2-1, each converged application deployed to the OWLCS container has a unique SipApplicationSession, which can contain one or more SipSession and ConvergedHttpSession objects.

Figure 2-1 Sessions in a Converged Application

Sessions in a converged application
Description of "Figure 2-1 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, OWLCS 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 2-0 lists the SIP Servlet APIs to use in place of now deprecated methods. See the SIP Servlet v1.1 API JavaDoc for more information.

Table 2-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 SipApplicationSession object with a specified session ID.

getApplicationSessionsByCallId

None.

Obtains an Iterator of SipApplicationSession objects associated with the specified call ID.

createHttpSession

None.

Applications can instead cast an HttpSession into ConvergedHttpSession.

setApplicationSession

javax.servlet.sip.ConvergedHttpSession.

getApplicationSession

Associates an HTTP session with an existing SipApplicationSession.

removeApplicationSession

None.

Removes an HTTP session from an existing SipApplicationSession.

getEncodeURL

javax.servlet.sip.ConvergedHttpSession.

encodeURL

Encodes an HTTP URL with the jsessionid of an existing HTTP session object.


Note:

The com.bea.wcp.util.Sessions API is provided only for backward compatibility. Use the SIP Servlet APIs for all new development. OWLCS 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.

2.3.1 Modifying the SipApplicationSession

When using a replicated domain, OWLCS 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. 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, OWLCS extends the standard SipApplicationSession object with com.bea.wcp.sip.WlssSipApplicationSession, and adds two interfaces, com.bea.wcp.sip.WlssAction and com.bea.wcp.sip.WlssAsynchronous Action, 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 object is executed on a locked copy of the associated SipApplicationSession instance. The sections that follow describe each interface.

2.3.1.1 Synchronous Access

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 2-1, "Example Code using WlssAction API" shows an example of using this API.

Example 2-1 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.

2.3.1.2 Asynchronous Access

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 2-2, "Example Code using WlssAsynchronousAction API" shows an example of using this API.

To compile applications using this API, you need to include MIDDLEWARE_HOME/server/lib/wlss/wlssapi.jar, and MIDDLEWARE_HOME/server/lib/wlss/sipservlet.jar.

Example 2-2 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.

2.4 Using the Converged Application Example

OWLCS includes a sample converged application that uses the com.bea.wcp.util.Sessions API. All source code, deployment descriptors, and build files for the example can be installed in OWLCS_HOME\samples\sipserver\examples\src\convergence. See the readme.html file in the example directory for instructions about how to build and run the example.