Developing Applications with WebLogic SIP Server

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

Requirements and Best Practices for WebLogic SIP Server Applications

The following sections describe requirements and best practices for developing applications for deployment to WebLogic SIP Server:


Overview of Developing and Porting Applications for WebLogic SIP Server

In a typical production environment, SIP applications are deployed to a cluster of WebLogic SIP Server instances that form the engine tier cluster. A separate cluster of servers in the data tier provides a replicated, in-memory database of the call states for active calls. In order for applications to function reliably in this environment, you must observe the programming practices and conventions described in the sections that follow to ensure that multiple deployed copies of your application perform as expected in the clustered environment.

If you are porting an application from a previous version of WebLogic SIP Server, many of the conventions and restrictions described below may be new to you, because previous WebLogic SIP Server implementations did not support a clustering. As always, thoroughly test and profile your ported applications to discover problems and ensure adequate performance in the new environment.


Applications Must Not Create Threads

WebLogic SIP Server is a multi-threaded application server that carefully manages resource allocation, concurrency, and thread synchronization for the modules it hosts. To obtain the greatest advantage from the WebLogic SIP Server architecture, construct your application modules according to the SIP Servlet and J2EE API specifications.

Avoid application designs that require creating new threads in server-side modules such as SIP Servlets:

WARNING: If your application must spawn threads, you must guard against deadlocks and carefully manage concurrent access to session data. At a minimum, never spawn threads inside the service method of a SIP Servlet. Instead, maintain a separate thread pool outside of the service method, and be careful to synchronize access to all session data.


Servlets Must Be Non-Blocking

SIP and HTTP Servlets must not block threads in the body of a SIP method because the call state remains locked while the method is invoked. For example, no Servlet method should actively wait for data to be retrieved or written before returning control to the SIP Servlet container.


Store all Application Data in the Session

If you deploy your application to more than one engine tier server (in a replicated WebLogic SIP Server configuration) you must store all application data in the session as session attributes. In a replicated configuration, engine tier servers maintain no cached information; all application data must be de-serialized from the session attribute available in data tier servers.


All Session Data Must Be Serializable

To support in-memory replication of SIP application call states, you must ensure that all objects stored in the SIP Servlet session are serializable. Every field in an object must be serializable or transient in order for the object to be considered serializable. If the Servlet uses a combination of serializable and non-serializable objects, WebLogic SIP Server cannot replicate the session state of the non-serializable objects.


Use setAttribute() to Modify Session Data in “No-Call” Scope

The SIP Servlet container automatically locks the associated call state when invoking the doxxx method of a SIP Servlet. However, applications may also attempt to modify session data in “no-call” scope. No-call scope refers to the context where call state data is modified outside the scope of a normal doxxx method. For example, data is modified in no-call scope when an HTTP Servlet attempts to modify SIP session data, or when a SIP Servlet attempts to modify a call state other than the one that the container locked before invoking the Servlet.

Applications must always use the SIP Session’s setAttribute method to change attributes in no-call scope. Likewise, use removeAttribute to remove an attribute from a session object. Each time setAttribute/removeAttribute is used to update session data, the SIP Servlet container obtains and releases a lock on the associated call state. (The methods enqueue the object for updating, and return control immediately.) This ensures that only one application modifies the data at a time, and also ensures that your changes are replicated across data tier nodes in a cluster.

If you use other set methods to change objects within a session, WebLogic SIP Server cannot replicate those changes.

Note that the WebLogic SIP Server container does not persist changes to a call state attribute that are made after calling setAttribute. For example, in the following code sample the setAttribute call immediately modifies the call state, but the subsequent call to modifyState() does not:

  Foo foo = new Foo(..);
  appSession.setAttribute("name", foo); // This persists the call state.
  foo.modifyState(); // This change is not persisted.

Instead, ensure that your Servlet code modifies the call state attribute value before calling setAttribute, as in:

  Foo foo = new Foo(..);
  appSession.setAttribute("name", foo);

Also, keep in mind that the SIP Servlet container obtains a lock to the call state for each individual setAttribute call. For example, when executing the following code in an HTTP Servlet, the SIP Servlet container obtains and releases a lock on the call state lock twice:

appSess.setAttribute("foo1", "bar2");
appSess.setAttribute("foo2", "bar2");

This locking behavior ensures that only one thread modifies a call state at any given time. However, another process could potentially modify the call state between sequential updates. The following code is not considered thread safe when done no-call state:

Integer oldValue = appSession.getAttribute("counter");
Integer newValue = incrementCounter(oldValue);
appSession.setAttribute("counter", newValue);

To make the above code thread safe, you must enclose it using the wlssAppSession.doAction method, which ensures that all modifications made to the call state are performed within a single transaction lock, as in:

wlssAppSession.doAction(new WlssAction() {
       public Object run() throws Exception {
         Integer oldValue = appSession.getAttribute("counter");
         Integer newValue = incrementCounter(oldValue);
         appSession.setAttribute("counter", newValue);
         return null;

Finally, be careful to avoid deadlock situations when locking call states in a “doSipMethod” call, such as doInvite(). Keep in mind that the WebLogic SIP Server container has already locked the call state when the instructions of a doSipMethod are executed. If your application code attempts to access the current call state from within such a method (for example, by accessing a session that is stored within a data structure or attribute), the lock ordering results in a deadlock.

Listing 2-1 shows an example that can result in a deadlock. If the code is executed by the container for a call associated with callAppSession, the locking order is reversed and the attempt to obtain the session with getApplicationSession(callId) causes a deadlock.

Listing 2-1 Session Access Resulting in a Deadlock
WlssSipApplicationSession confAppSession = (WlssSipApplicationSession) appSession;
confAppSession.doAction(new WlssAction() {  
  // confAppSession is locked
  public Object run() throws Exception {
    String callIds = confAppSession.getAttribute("callIds");
    for (each callId in callIds) {
      callAppSess = Session.getApplicationSession(callId); 
      // callAppSession is locked
      attributeStr += callAppSess.getAttribute("someattrib");
    confAppSession.setAttribute("attrib", attributeStr);

See Modifying the SipApplicationSession for more information about using the com.bea.wcp.sip.WlssAction interface.


send() Calls Are Buffered

If your SIP Servlet calls the send() method within a SIP request method such as doInvite(), doAck(), doNotify(), and so forth, keep in mind that the WebLogic SIP Server container buffers all send() calls and transmits them in order after the SIP method returns. Applications cannot rely on send() calls to be transmitted immediately as they are called.

WARNING: Applications must not wait or sleep after a call to send(), because the request or response is not transmitted until control returns to the SIP Servlet container.


Mark SIP Servlets as Distributable

If you have designed and programmed your SIP Servlet to be deployed to a cluster environment, you must include the distributable marker element in the Servlet’s deployment descriptor when deploying the application to a cluster of engine tier servers. If you omit the distributable element, WebLogic SIP Server will not deploy the Servlet to a cluster of engine tier servers.

The distributable element is not required, and is ignored if you deploy to a single, combined-tier (non-replicated) WebLogic SIP Server instance.


Observe Best Practices for J2EE Applications

If you are deploying applications that use other J2EE APIs, observe the basic clustering guidelines associated with those APIs. For example, if you are deploying EJBs you should design all methods to be idempotent and make EJB homes clusterable in the deployment descriptor. See Clustering Best Practices in the WebLogic Server 9.2 Documentation for more information.

  Back to Top       Previous  Next