This chapter describes how to configure a Oracle Communications Converged Application Server domain to use an Oracle or MySQL RDBMS with the Coherence cluster, in order to conserve RAM.
Converged Application Server enables you to store long-lived call state data in an Oracle or MySQL RDBMS in order to conserve RAM. When you enable RDBMS persistence, by default the Coherence cache persists a call state's data to the RDBMS after the call dialog has been established, and at subsequent dialog boundaries, retrieving or deleting the persisted call state data as necessary to modify or remove the call state.
Oracle also provides an API for application designers to provide "hints" as to when the Coherence cache should persist call state data. These hints can be used to persist call state data to the RDBMS more frequently, or to disable persistence for certain calls.
Note that Converged Application Server only uses the RDBMS to supplement the Coherence cache's in-memory replication functionality. To improve latency performance when using an RDBMS, the Coherence cache maintains SIP timers in memory, along with call states being actively modified (for example, in response to a new call being set up). Call states are automatically persisted only after a dialog has been established and a call is in progress, at subsequent dialog boundaries, or in response to persistence hints added by the application developer.
When used in conjunction with an RDBMS, the Coherence cache selects one engine to process all call state writes (or deletes) to the database. Any available server can be used to retrieve call states from the persistent store as necessary for subsequent reads.
RDBMS call state storage can be used in combination with an engine cache, if your domain uses a SIP-aware load balancer to manage connections to the engine tier. See "Using the Engine Cache".
Enable RDBMS call state storage only when all of the following criteria are met:
The call states managed by your system are typically long-lived.
The size of the call state to be stored is large. Very large call states may require a significant amount of RAM in order to store the call state.
Latency performance is not critical to your deployed applications.
The latency requirement, in particular, must be well understood before choosing to store call state data in an RDBMS. The RDBMS call state storage option measurably increases latency for SIP message processing, as compared to using a Coherence cache cluster. If your system must handle a large number of short-lived SIP transactions with brief response times, Oracle recommends storing all call state data in the Coherence cache.
Note:
RDBMS persistence is designed only to reduce the RAM requirements in the Coherence cache for large, long-lived call states. The persisted data cannot be used to restore a failed engine.To change an existing Converged Application Server domain to store call state data in an Oracle or MySQL RDBMS, you must configure the required JDBC datasource, edit the Converged Application Server configuration, and add the required schema to your database. Follow the instructions in the sections below to configure an Oracle Database.
Converged Application Server includes a SQL script, callstate.sql, that you can use to create the tables necessary for storing call state information. The script is installed to the user_staged_config subdirectory of the domain directory when you configure a replicated domain using the Configuration Wizard.
The contents of the callstate.sql SQL script are shown in Example 9-1.
Example 9-1 callstate.sql Script for Call State Storage Schema
drop table callstate; create table callstate ( key1 int, key2 int, bytes blob default empty_blob(), constraint pk_callstate primary key (key1, key2) );
Follow these steps to execute the script commands using SQL*Plus:
Move to the Converged Application Server utils directory, in which the SQL Script is stored:
cd ~/WL_HOME/common/templates/scripts/db/oracle
where WL_HOME is the path to the directory where the WebLogic Server component of Converged Application Server is installed.
Start the SQL*Plus application, connecting to the Oracle database in which you will create the required tables. Connect to the database using the user name, password and database name that you specified when you installed the database software. For example:
sqlplus username/password@connect_identifier
where connect_identifier connects to the database identified in the JDBC connection pool.
Execute the Converged Application Server SQL script, callstate.sql:
START callstate.sql
Exit SQL*Plus:
EXIT
Follow these steps to create the required JDBC resources in your domain:
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.
Note:
The default administration console port for Converged Application Server is 7001.Access the Administration Console for the domain.
If your domain is running in Production mode, click Lock & Edit.
Expand Services, then select the Data Sources node in the left pane.
In the Summary of JDBC Data Sources pane, click the Configuration tab, and then click New in the Data Sources table and choose Generic Data Source from the pop up menu.
Fill in the fields of the Create a New JDBC Data Source page as follows:
Name: Enter CallStateDataSource
JNDI Name: Enter wlss.callstate.datasource.
Database Type: Select Oracle or MySQL depending on your database.
Click Next.
Select an appropriate JDBC driver from the Database Driver list. Note that some of the drivers listed in this field may not be installed by default on your system. Install third-party drivers as necessary using the instructions from your RDBMS vendor. For more information on JDBC drivers, see "Selecting a JDBC Driver" in Administering JDBC Data Sources for WebLogic Server.
Click Next.
Configure any Transaction Options as required for your database. For more information on JDBC transaction options, see "Configure Transaction Options" in Administering JDBC Data Sources for WebLogic Server.
Click Next.
Fill in the fields of the Connection Properties tab using connection information for the database you want to use. For more information, see "Configure Connection Properties" in Administering JDBC Data Sources for WebLogic Server.
Click Next.
Click Test Configuration to test your connection to the RDBMS, or click Next to continue.
On the Select Targets page, select the name of your SIP engine cluster (for example, BEA_ENGINE_TIER_CLUST).
Click Finish to save your changes.
If your domain is running in Production mode, click Activate Changes.
Follow these steps to configure the Converged Application Server persistence options to use an RDBMS call state store:
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.
Note:
The default administration console port for Converged Application Server is 7001.If your domain is running in Production mode, click Lock & Edit.
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 Configuration, then select the Persistence tab in the right pane.
Configure the Persistence attributes as follows:
DB Enabled: Check to enable call states to be stored in an RDBMS.
Default Handling: Select db or all. It is acceptable to select all because geographically-redundant replication is only performed if the Geo Site ID and Geo Remote T3 URL fields have been configured.
For information on configuring geographical redundancy, see "Configuring Geographically-Redundant Installations".
Click Save to save your configuration changes.
If your domain is running in Production mode, click Activate Changes.
Converged Application Server provides a simple API to provide "hints" as to when the Coherence cache should persist call state data. You can use the API to disable persistence for specific calls or SIP requests, or to persist data more frequently than the default setting (at SIP dialog boundaries).
To use the API, simply obtain a WlssSipApplicationSession instance and use the setPersist method to enable or disable persistence. Note that you can enable or disable persistence either to an RDBMS store, or to as geographically-redundant Converged Application Server installation (see "Configuring Geographically-Redundant Installations").
For example, some SIP-aware load balancing products use the SIP OPTIONS message to determine if a SIP Server is active. To avoid persisting these messages to an RDBMS and to a geographically-redundant site, a Servlet might implement a doOptions method to echo the request and turn off persistence for the message, as shown in Example 9-2.
Example 9-2 Disabling RDBMS Persistence for Option Methods
protected void doOptions(SipServletRequest req) throws IOException {
WlssSipApplicationSession session =
(WlssSipApplicationSession) req.getApplicationSession();
session.setPersist(WlssSipApplicationSession.PersistenceType.DATABASE,
false);
session.setPersist(WlssSipApplicationSession.PersistenceType.GEO_REDUNDANCY, false);
req.createResponse(200).send();
}