The following sections describe how to develop converged HTTP and SIP applications with Oracle Communications Converged Application Server:
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 into an application archive (.EAR file). Converged applications that use utilize SIP and HTTP protocols should 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 via a common application session object. The SIP Servlet API also helps you associate HTTP sessions with an application session.
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:
WEB-INF
subdirectory; this ensures that the files are not served up as static files by an HTTP Servlet.sip.xml
and web.xml
descriptors are required. A weblogic.xml
deployment descriptor may also be included to configure Servlet functionality in the Oracle Communications Converged Application Server container.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.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.
As shown in Figure 6-1, each converged application deployed to the Oracle Communications Converged Application Server container has a unique SipApplicationSession
, which can contain one or more SipSession
and HttpSession
objects.
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, Oracle Communications Converged Application Server extended the basic SIP Servlet API to provide methods for:
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 6-1 lists the SIP Servlet APIs to use in place of now deprecated methods. See the
SIP Servlet v1.1 API JavaDoc for more information.
Notes: | The com.bea.wcp.util.Sessions API is provided only for backward compatibility. Use the SIP Servlet APIs for all new development. Oracle Communications Converged Application Server does not support converged applications that mix the com.bea.wcp.util.Sessions API and JSR 289 convergence APIs. |
Note: | 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 for more information about this targeting mechanism. |
When using a replicated domain, Oracle Communications 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, Oracle Communications Converged Application Server extends the standard SipApplicationSession
object with com.bea.wcp.sip.WlssSipApplicationSession
, and adds a new interface, com.bea.wcp.sip.WlssAction
to encapsulate changes to the session. When these APIs are used, the SIP container ensures that all business logic contained within the WlssAction
object is executed on a locked copy of the associated SipApplicationSession
instance.
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;
}
});
Oracle Communications Converged Application Server 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 WLSS_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.