This chapter describes requirements and best practices for developing applications for deployment to Oracle Communications Converged Application Server.
In a typical production environment, Session Initiation Protocol (SIP) applications are deployed to a Coherence cluster of Converged Application Servers. 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.
Converged Application 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 Converged Application Server architecture, make use of the Converged Application Server concurrency utilities as described in "SIP Servlet Concurrency".
If an application needs to access the Future object of a task that belongs to a SIP application session that is not the current SIP application session, create a non-scheduled managed task to access it. For more information about submitting a task with a different application session as its context, see "Specifying Application Session Programmatically".
For scheduled managed tasks, applications should always access future objects from the SIPApplicationSession interface so that they get consistent access to a task's state across the cluster. This approach is highly recommended if a task needs to be cancelled so as to avoid a locally-stored reference. Cancellation of a running task, using the Future or ScheduledFuture object, in interrupted mode does not always guarantee that the task is aborted. See the description of the cancel method in:
https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html
Customers should use appropriate concurrency modes based on their application needs so that messages and/or timers belonging to the same Sip application session do not lead to concurrency access issues, such as race conditions or deadlocks. Converged Application Server employs its own locking framework based on the chosen concurrency mode. Discrete multiple operations associated with the same Sip Application session may lead to multiple lock-and-unlock routines. Such a situation should be avoided by combining these operations into a single non-scheduled managed task for that SIP application session.
Avoid nested lock situations. However, when applications employ nested SIP Application Session locks, the application logic associated with managing these locks must be designed with great care. Sometimes and in special circumstances, a nested SIP Application Session lock may lead to a deadlock. In such a situation, enabling the wlss.concurrent debug flag in the Converged Application Server Administration Console can assist you in your attempts to troubleshoot the issue. For information about setting the debug flag in Converged Application Server, see Converged Application Server Administrator's Guide.
MessageListener implementations provided by Converged Application Server Java API SDK are solely meant for read-only purposes, such as logging. They must not be used for any type of SIP manipulation such as adding, removing, or modifying a session attribute or any other manipulation of a container-managed object.
The SIP container does not handle any sort of exception scenario; so it is not advisable for an application to rely on implementing the MessageListener interfaces for any type of SIP manipulation.
Applications must not store container-managed objects for example, future objects, tasks, SIP request, and SIP response objects in local data structures.
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, Servlet method must not actively wait for data to be retrieved or written before returning control to the SIP Servlet container.
Servlets should also avoid sleep or wait operations in the body of a SIP method as such operations block the container thread and the callstate lock is held for the duration of each operation. Methods need to be written in such a way that control is returned back to the container and the flow is not compromised.
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, Converged Application Server cannot replicate the session state of the non-serializable objects.
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 engines. If you omit the distributable element, Converged Application Server does not deploy the SIP Servlet in a clustered environment.
Converged Application Server ignores the distributable element in non-clustered environments.
The SipApplicationSessionActivationListener interface can provide callbacks to an application when SIP Sessions are not active or activated. Keep in mind that callbacks occur only in a replicated Converged Application Server deployment.
Keep in mind that in a replicated deployment, Converged Application Server activates and passivates a SIP Session many times before and after the SIP messages are processed for the session. (This occurs normally in any deployment, even when RDBMS-based persistence is not configured.) Because this constant cycle of activation and passivation results in frequent callbacks, use SipApplicationSessionActivationListener sparingly in your applications.
If you are deploying applications that use other Java EE APIs, observe the basic clustering guidelines associated with those APIs. For example, if you are deploying EJBs, you must design all methods to be idempotent and make EJB homes clusterable in the deployment descriptor. For more information, see the discussion about "Clustering Best Practices" in the Fusion Middleware Using Clusters for Oracle WebLogic Server.
By default, Converged Application Server serializes and de-serializes call states, which optimizes your standalone domains for memory utilization. However, you can disable serialization in Converged Application Server to optimize your standalone domains for performance. You configure whether Converged Application Server uses serialization by using the wlss.local.serialization system property. This system property must be provided to the Java Virtual Machine (JVM) that starts Converged Application Server.
When you set the wlss.local.serialization system property to true, Converged Application Server optimizes a standalone domain for efficient memory utilization. Maintain this setting if memory utilization is of concern in your environment, especially in scenarios where the application session time-out values are large. Converged Application Server serializes the call state after a dialog is established and de-serializes that call state as it becomes necessary to do so. Note that performance may be impacted by the serialization and de-serialization of call states.
When you set the wlss.local.serialization system property to false, Converged Application Server optimizes a standalone domain for performance. Set this property to false when performance is critical in your environment and calls have fewer hold times or lower application session time-out values. Converged Application Server does not serialize or de-serialize call states. Note that, since the call state are held in memory for the life of each call, an increase in the hold times for the calls has an impact on memory utilization.
To enable or disable serialization:
Go to the Domain_Home/bin directory, where Domain_Home is the domain's home directory.
Open the startWebLogic.sh script in a text editor.
Change the wlss.local.serialization system property to true or false as required.
Save and close the file.