3 Configuring Converged Application Container Properties

This chapter describes how to configure SIP container features in the engine tier of an Oracle Communications Converged Application Server deployment:

Creating the Engine Tier Cluster
Configure General SIP Application Server Properties
Configuring Timer Processing
Configuring the JSR 309 Media Server Control Driver

Creating the Engine Tier Cluster

In most implementations, the Converged Application Server instances are grouped into clusters. You create clusters and servers for the Converged Application Server in the same manner as other WebLogic servers. In the Administration Console, access the Environment page in the Domain Structure tree.

When configuring clusters for production deployments of the Converged Application Server, Oracle recommends that you use multicast cluster communication instead of unicast communication. While unicast may be easier to configure, using multicast reduces the likelihood of performance degradation that may result from excessive work load on group leaders and retransmissions during periods of high traffic.

After defining servers and clusters, you associate the cluster with the Converged Application Server as follows:

In a browser, open the Administration Console for your domain.
Click the SipServer link in the Domain Structure pane.

The General configuration page appears, which shows two top-level tabs, Configuration and Monitoring.
In the Configuration tab, click the Targets subtab.
In the SIP Server Targets field, enter the name of the cluster that contains the servers you want to act as Converged Application Server instances.
Click Save to save your configuration changes.

For more information on clustering, see Oracle Fusion Middleware Using Clusters for Oracle WebLogic Server.

Configure General SIP Application Server Properties

Loading SIP applications to the Converged Application Server in the Administration Console is similar to loading any application to WebLogic server. You use the Deployments page in the Administration Console to load, update, or remove an application or module.

The Converged Application Server defines general settings that apply to all SIP applications. Before deploying applications to the Converged Application Server, you should verify and modify the default values for the general settings. You can configure the general settings in the SIP Server page of the Administration Console.

To configure general SIP application server properties:

Open the Administration Console for your domain.
Click the SipServer link in the Domain Structure pane.

The right pane of the console provides two levels of tabbed pages that are used for configuring and monitoring Converged Application Server. By default, the General configuration page appears.
Use the fields in the General subtab of the Configuration tab to configure the general settings applicable to serving SIP applications.

Among the settings that determine common application handling are:
- The default servlet invoked if a specific servlet is not identified for a request based on the servlet mapping rules.
- Timer values. See "Configuring Timer Processing" for more information.
- Header handling settings.
- Application session settings.
For details, see the onscreen field descriptions in the Administration Console.
Click Save to save your configuration changes.
Click Activate Changes to apply your changes to the engine tier servers.

Configuring Timer Processing

As engine tier servers add new call state data to the SIP data tier, SIP data tier instances queue and maintain the complete list of SIP protocol timers and application timers associated with each call. Engine tier servers periodically poll partitions in the SIP data tier to determine which timers have expired, given the current time. By default, multiple engine tier polls to the SIP data tier are staggered to avoid contention on the timer tables. Engine tier servers then process all expired timers using threads allocated in the sip.timer.Default execute queue.

Configuring Timer Affinity (Optional)

With the default timer processing mechanism, a given engine tier server processes all timers that are currently due to fire, regardless of whether or not that engine was involved in processing the calls associated with those timers. However, some deployment scenarios require that a timer is processed on the same engine server that last modified the call associated with that timer. One example of this scenario is a hot standby system that maintains a secondary engine that should not process any call data until another engine fails. Converged Application Server enables you to configure timer affinity in such scenarios.

When you enable timer affinity, replicas request that each engine tier server periodically poll the SIP data tier for processed timers. When polling the SIP data tier, an engine processes only those timers associated with calls that were last modified by that engine, or timers for calls that have no owner.

Note:

When an engine tier server fails, any call states that were last modified by that engine no longer have an owner. Expired timers that have no owner are processed by the next engine server that polls the SIP data tier.

To enable timer affinity:

Access the Administration Console for your domain.
Select the SipServer node in the left pane. The right pane of the console provides two levels of tabbed pages that are used for configuring and monitoring Converged Application Server.
Select the Configuration > General tab in the right pane.
Select Enable Timer Affinity.
Click Save to save your configuration changes.
Click Activate Changes to apply your changes to the engine tier servers.

The Enable Timer Affinity setting is persisted in sipserver.xml in the enable-timer-affinity element.

Configuring NTP for Accurate SIP Timers

In order for the SIP protocol stack to function properly, all engine and SIP data tier servers must accurately synchronize their system clocks to a common time source, to within one or two milliseconds. Large differences in system clocks cause a number of severe problems such as:

SIP timers firing prematurely on servers with fast clock settings.
Poor distribution of timer processing in the engine tier. For example, one engine tier server may process all expired timers, whereas other engine tier servers process no timers.

Oracle recommends using a Network Time Protocol (NTP) client or daemon on each Converged Application Server instance and synchronizing to a common NTP server.

Caution:

You must accurately synchronize server system clocks to a common time source (to within one or two milliseconds) in order for the SIP protocol stack to function properly. Because the initial T1 timer value of 500 milliseconds controls the retransmission interval for INVITE request and responses, and also sets the initial values of other timers, even small differences in system clock settings can cause improper SIP protocol behavior. For example, an engine tier server with a system clock 250 milliseconds faster than other servers will process more expired timers than other engine tier servers, will cause retransmits to begin in half the allotted time, and may force messages to timeout prematurely.

Configuring the JSR 309 Media Server Control Driver

Converged Application Server allows you to control third-party media servers using a Media Server Control API based on JSR 309, a standard Java interface. The JSR 309 specification defines a protocol agnostic API for controlling media servers. JSR 309 provides a portable interface to create media rich applications with interactive voice response (IVR), conferencing, speech recognition, and similar features. Vendors of IP media servers provide JSR 309 based driver implementations that work with their IP media servers.

See “Media Server Control” in the Converged Application Server Technical Product Description for more information about the Media Server Control feature. For information about JSR 309, see the JSR 309 specification at:

http://jcp.org/en/jsr/detail?id=309

To enable your converged SipServlet-Java EE applications deployed on the Converged Application Server to communicate with the media server using the Media Server Control API, you must configure Converged Application Server to recognize the custom, JSR 309 resource; install the Media Server Control driver; and configure the driver using the Administration Console.

Install the Media Server Control Driver

For a standalone deployment of Converged Application Server, you must to install the Media Server Control driver on the Administration Server. For a replicated deployment, you must to install the Media Server Control driver on each engine in the Engine tier cluster.

Follow these steps to install the Media Server Control driver:

Shutdown all servers in the domain.
Copy the Media Server Control JAR file(s) to share into a lib subdirectory of the domain directory. For example:

CAS_home\user_projects\domains\domain_name\lib\

where CAS_home is the root directory where you installed Converged Application Server.

Note:
The Administration Server does not automatically distribute Media Server Control drivers to Managed Servers on remote machines. If you have Managed Servers that do not share the same physical domain directory as the Administration Server, you must manually install Media Server Control drivers to the CLASSPATH of each Managed Server.

Alternatively, you can add the JAR file to the system or Converged Application Server classpath.

See the discussion on adding JARs to the system classpath in Developing Applications with WebLogic Server for more information about adding JAR files to the system or Converged Application Server classpath.

Start the Administration Server and all Managed Servers in the domain. Converged Application Server appends JAR files found in the lib directory to the system classpath.
When the Converged Application Server starts, you can configure the installed driver(s) using the Converged Application Server Administration Console. See "Configure the Media Server Control Factory" for more information.

Configure the JSR 309 Resource for the Media Server Control Driver

The Media Server Control driver is not configured with a JSR 309 resource during the initial installation of the software. You must manually configure a custom JSR 309 resource for all servers in your Converged Application Server domain that will use the Media Server Control driver.

Configure the JSR 309 Resource for Proxy Registrar Domains

To configure the JSR 309 resource for deployments using Proxy Registrar domains:

Shutdown all servers in the domain.

Add the custom resource shown in the example below to the domain's config.xml file on the Administration Server. This example uses AdminServer as the target for the JSR309 resource. Specify the target parameters applicable to your Converged Application Server deployment.

<custom-resource>
<name>jsr309driveroam</name>
<target>AdminServer</target>
<descriptor-file-name>custom/jsr309driver.xml</descriptor-file-name>
<resource-class>
oracle.sdp.jsr309.configuration.resources.Jsr309Resource
</resource-class> 
<descriptor-bean-class>
oracle.sdp.jsr309.configuration.beans.Jsr309ConfigurationBean
</descriptor-bean-class>
</custom-resource>

Start the Administration Server, and all instances of Managed Servers on which you will install a Media Server Control driver.
When the Converged Application Server starts, you can configure the installed driver(s) using the Converged Application Server Administration Console. See "Configure the Media Server Control Factory" for more information.

Configure the JSR 309 Resource for Administration and Replicated Domains

The mscontrol.jar and jsr309-descriptor-binding.jar JAR files are not added to the WebLogic CLASSPATH during installation. For this reason, you must manually add these JAR files to the CLASSPATH for your deployment. If you do not add these files to the CLASSPATH, the following exception is thrown during server start-up:

<Error> <netuix> <BEA-423168> 
<An exception or error occurred in the backing file
 
[oracle.sdp.jsr309.console.util.JSR309NavTreeBac
kingFile] while executing its init method. It was
 
java.lang.NoClassDefFoundError
: oracle/sdp/jsr309/configuration/resources/Jsr309Resource

To add the mscontrol.jar and jsr309-descriptor-binding.jar JAR files to the WebLogic CLASSPATH:

Shutdown all servers in the domain.
Modify the CLASSPATH variable of the startWebLogic script as follows:

For Windows-based operating systems:

Modify the startWebLogic.cmd script located at CAS_home\user_projects\domains\domain_name\bin as follows:
```
set
CLASSPATH=%SAVE_CLASSPATH%;
%ORCL_HOME%\server\modules\mscontrol.jar;%
%ORCL_HOME%\server\lib\jsr309-descriptor-binding.jar
```
For UNIX-based operating systems:

Modify the startWebLogic.sh script located at CAS_home/user_projects/domains/domain_name/bin as follows:
```
CLASSPATH="${SAVE_CLASSPATH}:
${ORCL_HOME}/server/modules/mscontrol.jar:
${ORCL_HOME}/server/lib/jsr309-descriptor-binding.jar"
```

Add the custom resource shown in the example below to the domain's config.xml file on the Administration Server. This example uses AdminServer as the target for the JSR309 custom resource. Specify the target parameters applicable to your Converged Application Server deployment.

<custom-resource>
<name>jsr309driveroam</name>
<target>AdminServer</target>
<descriptor-file-name>custom/jsr309driver.xml</descriptor-file-name>
<resource-class>
oracle.sdp.jsr309.configuration.resources.Jsr309Resource
</resource-class> 
<descriptor-bean-class>
oracle.sdp.jsr309.configuration.beans.Jsr309ConfigurationBean
</descriptor-bean-class>
</custom-resource>

Create an XML file called jsr309driver.xml with the following contents:

<?xml version='1.0' encoding='UTF-8'?>
<jsr309-configuration xmlns="http://www.oracle.com/ns/occas/sdp/jsr309/100" xmlns:sec="http://xmlns.oracle.com/weblogic/security"
xmlns:wls="http://xmlns.oracle.com/weblogic/security/wls"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
</jsr309-configuration>

Save the jsr309driver.xml file to the directory CAS_home/user_projects/domains/domain_name/config/custom (UNIX) or CAS_home\user_projects\domains\domain_name\config\custom (Windows) on your domain's Administration Server.
Start the Administration Server, and all instances of Managed Servers on which you will install a Media Server Control driver.
When the Converged Application Server starts, you can configure the installed driver(s) using the Converged Application Server Administration Console. See "Configure the Media Server Control Factory" for more information.

Configure the Media Server Control Factory

Follow these steps to configure the Media Server Control factory:

Access the WebLogic Server Administration Console. Use your browser to access the URL:

http://address:port/console

where address is the Administration Server's listen address and port is the listen port.
Select Media Server Control in the Domain Structure navigation tree.

The Media Server Control Factory page displays any previously configured Media Server Control drivers.
Click New to create a new Media Server Control Factory.
Fill in the fields of the Create a Media Server Control Factory page as follows:
- Factory name: The name to assign to the Media Server Control factory.
- JNDI name: The JNDI name under which to create the Media Server Control factory. The JNDI name uniquely identifies this instance of the driver.
  
  Observe the conventions of the Java Naming and Directory Interface (JNDI) service when you create JNDI factory names. The following naming conventions are supported for the JNDI name:
  - Only a-z, A-Z, 0-9,'_', '@' and '/' are valid characters for the JNDI name.
    
    All other characters are treated as invalid, and will cause the configuration to fail.
  - '/' is treated as a subcontext character. For example, the name test1/test2/factory will be treated as a JNDI hierarchy.
  When registering a JNDI name for the Media Server Control factory, Converged Application Server prepends the term mscontrol to the name. For example: mscontrol/mediasrv1
- Driver name: Select a Media Server Control driver from the Driver list.
Click Next.
The properties of the Media Server Control configuration are displayed in an editable text field. You can edit this field to add new properties, or you can modify or delete an existing property.

The only property specified by the Media Server Control API is MEDIA_SERVER_URI, which defines the Uniform Resource Identifier (URI) of the media server. The URI is a string of characters used to identify a resource on the Internet. You can edit the MEDIA_SERVER_URI property with the URI of the media server to use in conjunction with Converged Application Server. While the MEDIA_SERVER_URI is an optional property, and may not be required by all media server vendors, Oracle recommends specifying a URI value whenever possible.

Note:
Certain properties defined by the MsControlFactory class are required to create a Media Server Control factory. If you delete a required property, the creation of the factory will fail.
Click Finish.

A new Media Server Control factory instance that can be injected or looked up from inside your converged applications to communicate with the media server is created.

About Monitoring the Count of Application Sessions

The current count of active application sessions in a domain is displayed in the Administration Console under the SIP Server Monitoring tab, in the General subtab. The counters for created sessions and destroyed sessions on each engine-tier server are maintained in runtime MBeans on those servers locally and do not survive server restarts. To minimize the performance impact of data storage and serialization, a server's counters are not replicated to the data tier and hence are reset to zero each time the server is restarted.

The count of active sessions in a domain at any given time is the sum of sessions created on all engine-tier servers, less the sum of sessions destroyed on all engine-tier servers, from the time that the domain servers are started. This count is a best estimate and may not reflect the actual count of active sessions if servers are started at different times or when one or more servers are shut down.

For example, an engine-tier cluster contains server 1 and server 2. Server 2 is shut down. This causes the created- and destroyed-session counters on server 2 to be zero. Because sessions created on server 2 will eventually invalidate on server 1, the sum of destroyed sessions for the cluster-wide count will be greater than the sum of the created sessions for the cluster-wide count, resulting in a negative value for the active-session counter in the cluster. The total count will continue to be negative even if server 2 is restarted.

If you need to ensure that the domain-wide count of active application sessions is accurate at all times, you can use a custom, external JMX-based agent that maintains counters outside of the engine-tier servers.