Distributed Cache Synchronization

The need to maintain up-to-date data for all applications is a key design challenge for building a distributed application environment. The difficulty of this increases as the number of servers within an environment increases. OracleAS TopLink provides a distributed cache synchronization feature that ensures data in applications remains current.

Cache synchronization in no way eliminates the need for an effective locking policy. However, it does reduce the number of optimistic lock exceptions encountered in a distributed architecture, and decreases the number of failed or repeated transactions in an application.

OracleAS TopLink provides cache synchronization at the session level. This feature ensures that object updates associated with a given session propagate to the caches on all other servers in the cluster.

This section describes:

Configuring Cache Synchronization in the sessions.xml File
Explicit Query Refreshes

Configuring Cache Synchronization in the sessions.xml File

Because each application server approaches caching differently, you must configure cache synchronization to work effectively within the distributed system.

For more information about choosing cache configuration options, see the application server or J2EE container documentation.

To enable and configure cache synchronization in the sessions.xml file, specify the cache-synchronization-manager element, and configure the required subelements.

Example 8-1 illustrates how to configure cache synchronization in the sessions.xml file for a session that:

Runs in Oracle Application Server Containers for J2EE (OC4J)
Uses the default discovery settings
Uses JNDI to look up the remote objects
Distributes the changes using RMI

Example 8-1 Configuring Cache Synchronization in the sessions.xml File

<cache-synchronization-manager>
    <clustering-service>
        oracle.toplink.remote.rmi.RMIJNDIClusteringService
    </clustering-service>
    <jndi-user-name>userName</jndi-user-name>
    <jndi-password>password</jndi-password>
    <naming-service-initial-context-factory-name>
        oracle.com.evermind.server.rmi.RMIInitialContextFactory
    </naming-service-initial-context-factory-name>
    <naming-service-url>ormi://hostname:23791/appName</naming-service-url>
</cache-synchronization-manager>

The configuration in Example 8-1 includes the name, password, context factory class, and URL. OC4J requires all four subelements to enable name lookup on remote hosts. Other servers require different values for the context factory and URL.

For OC4J, the URL element includes the ormi:// protocol, the local host name and RMI server port, and the name of the application in which the OracleAS TopLink session is deployed.

Clustering Service

The clustering-service element specifies the name service and transport combination used to communicate changes. Choose the combination that works best with your application. Here are the choices:

oracle.toplink.remote.rmi.RMIJNDIClusteringService: Uses JNDI to look up remote sessions, and RMI point-to-point connections to propagate changes between sessions
oracle.toplink.remote.rmi.RMIClusteringService: Uses RMIRegistry to look up sessions, and RMI point-to-point connections to propagate changes between sessions
oracle.toplink.remote.ejb.EJBJNDIClusteringService: Uses JNDI to look up session beans that propagate changes between sessions
oracle.toplink.remote.corba.CORBAJNDIClusteringService: Uses JNDI to look up sessions, and CORBA point-to-point connections to propagate changes between sessions
oracle.toplink.remote.corba.JMSClusteringService: Uses JNDI to look up Java Message Service (JMS) topics that propagate changes between sessions

Example 8-2 Configuring a Clustering Service in the sessions.xml File

<cache-synchronization-manager>
    <clustering-service>
        oracle.toplink.remote.rmi.RMIJNDIClusteringService
    </clustering-service>
    ...
</cache-synchronization-manager>

Discovery

Discovery occurs when servers in a cluster learn of other servers in the cluster, and uses a multicast protocol to monitor sessions as they join and leave the OracleAS TopLink cluster. If you are running OracleAS TopLink with other Oracle Application Server 10g components, ensure the port you select does not conflict with other components. If the OracleAS TopLink default discovery configuration conflicts with settings for other services on the same host, you can override the discovery settings.

You can configure discovery to use specific optional multicast socket options, including:

multicast-port: Overrides the default multicast port used for discovery (default is 6018)
multicast-group-address: Overrides the default multicast group used for discovery (default is 226.18.6.18)
packet-time-to-live: Overrides the default time-to-live (TTL) setting for discovery multicast socket (default is 2)

Example 8-3 Configuring Discovery in the sessions.xml File

<cache-synchronization-manager>
    <clustering-service> … </clustering-service>
    <multicast-port>6020</multicast-port>
    <multicast-group-address>228.1.2.3</multicast-group-address>
    <packet-time-to-live>3</packet-time-to-live>
    ...
</cache-synchronization-manager>

Note:

When you select JMS as the transport mechanism in the clustering-service element, OracleAS TopLink ignores the discovery setting.

Name Service

A name service enables you to search for objects on remote caches. JNDI provides the name service for most applications, and offers the following optional elements to customize JNDI support in your application:

jndi-user-name: User name value assigned to Context.SECURITY_PRINCIPAL property when looking up names in JNDI
jndi-password: Password value assigned to Context.SECURITY_CREDENTIALS property when looking up names in JNDI
naming-service-initial-context-factory-name: The class employed when creating initial context instances to use for looking up in JNDI
naming-service-url: The URL to use when looking up through the naming service (value assigned to Context.PROVIDER_URL property in JNDI)

Not all servers require all four optional elements.

Example 8-4 Configuring JNDI Name Service in the sessions.xml File for WLS

<cache-synchronization-manager>
    <clustering-service> … </clustering-service>
    <naming-service-initial-context-factory-name>
        weblogic.jndi.WLInitialContextFactory
    </naming-service-initial-context-factory-name>
    <naming-service-url>t3://hostName:7001</naming-service-url>
</cache-synchronization-manager>

Using the Java Message Service

The JMS API is a protocol for communication that provides asynchronous communication between components in a distributed computing environment. Because OracleAS TopLink integrates with the JMS publish/subscribe mechanism, use JMS to improve the scalability of your cache synchronization.

For more information about the JMS API, see the JMS specification at

http://java.sun.com/products/jms

Preparing to use JMS

You must configure a JMS service in the environment before OracleAS TopLink can leverage the service. To enable the service:

Configure a JMS connection factory and note the name. OracleAS TopLink uses the factory name to look up the factory. For more information, see the JMS service provider documentation.
Configure a JMS topic and note the name. OracleAS TopLink uses the topic name to look up the topic. For more information, see the JMS service provider documentation.
Configure the OracleAS TopLink sessions.xml file to use the factory and topic names.
Start the JMS service. For more information, see the JMS service provider documentation. For more information, see "Configuring JMS in sessions.xml".

Example 8-5 illustrates a jms.xml configuration file for OC4J. Note that the host and port of the topic connection factory is the host and port of the JMS server hosting the topic—not the host or port of the local JMS server.

Example 8-5 Example of the OC4J jms.xml File

<jms-server port="9128">
    <topic name="MyCacheSyncTopic" location="jms/MyCacheSyncTopic"/>
    <topic-connection-factory 
      host="micky" 
      port="9127" 
      name="Cache Sync Topic Factory" 
      location="jms/MyTopicFactory" 
      password="password" 
      username="admin"/> 
    <log>
        <file path="../log/jms.log"/> 
    </log>
</jms-server>

Configuring JMS in sessions.xml

To configure JMS in the sessions.xml file, use the following optional elements:

jms-topic-connection-factory-name: The JNDI name to use when looking up the connection factory for the JMS topic
jms-topic-name: The JNDI name to use when looking up the JMS topic

Note:
These elements are exclusive to JMS use only. Do not apply these elements when you use a service other than JMS.

Example 8-6 JMS Entries in the sessions.xml File

<cache-synchronization-manager>
    <clustering-service>
        oracle.toplink.remote.jms.JMSClusteringService 
    </clustering-service>
    <jms-topic-connection-factory-name>
        jms/MyTopicFactory 
    </jms-topic-connection-factory-name>
    <jms-topic-name>jms/MyCacheSyncTopic</jms-topic-name>
    ...
</cache-synchronization-manager>

Note that JMS neither requires nor makes use of discovery.

Configuring JMS for OC4J

When you use JMS in OC4J, set the naming service URL to the hostname of the JMS server hosting the topic. Example 8-7 illustrates this for an OracleAS TopLink session running in OC4J using JMS.

Example 8-7 Configuring OracleAS TopLink with JMS for OC4J

<cache-synchronization-manager>
    <clustering-service>
        oracle.toplink.remote.jms.JMSClusteringService 
    </clustering-service>
    <jndi-user-name>admin</jndi-user-name>
    <jndi-password>password</jndi-password>
    <jms-topic-connection-factory-name>
        jms/MyTopicFactory 
    </jms-topic-connection-factory-name>
    <jms-topic-name>jms/MyCacheSyncTopic</jms-topic-name>
    <naming-service-initial-context-factory-name>
        oracle.com.evermind.server.rmi.RMIInitialContextFactory 
    </naming-service-initial-context-factory-name>
    <naming-service-url>ormi://micky</naming-service-url>
</cache-synchronization-manager>

Synchronous and Asynchronous Propagation

The Cache Synchronization Manager enables you to specify the propagation mode for your OracleAS TopLink application:

If you send changes synchronously, the current transaction does not commit until OracleAS TopLink sends changes successfully to the other sessions in the system.
If you send changes asynchronously, the transaction commits without waiting for OracleAS TopLink to propagate changes.

The optional is-asynchronous element controls the propagation mode, regardless of the transport used. By default, propagation occurs asynchronously.

Example 8-8 Configuring Propagation Mode

<cache-synchronization-manager>
    <clustering-service>...</clustering-service>
    <is-asynchronous>false</is-asynchronous>
    ...
</cache-synchronization-manager>

Error Handling

You can define error handlers to respond to raised exceptions. The should-remove-connection-on-error element (an optional sub-element of cache-synchronization-manager) specifies whether a connection to another session is discarded if an error occurs while sending an update. By default, OracleAS TopLink discards connections when errors occur.

Example 8-9 Configuring Error Handling

<cache-synchronization-manager>
    <clustering-service>...</clustering-service>
    <should-remove-connection-on-error>false</should-remove-connection-on-error>
    ...
</cache-synchronization-manager>

Explicit Query Refreshes

Some distributed systems require only a small number of objects to be consistent across the servers in the system. Conversely, other systems require that several specific objects must always be guaranteed to be up-to-date, regardless of the cost. If you build such a system, you can explicitly refresh selected objects from the database at appropriate intervals without incurring the full cost of distributed cache synchronization.

To implement this type of strategy:

Configure a set of queries that refresh the required objects.
Establish an appropriate refresh policy.
Invoke the queries, as required, to refresh the objects.

Refresh Policy

When you execute a query, if the required objects are in the cache, then OracleAS TopLink returns the cached objects without checking the database for a more recent version. This behavior reduces the number of objects that OracleAS TopLink must build from database results, and is optimal for nonclustered environments. However, this strategy may not always be the best for a clustered environment.

To override this behavior, set a refresh policy that specifies that the objects from the database always take precedence over objects in the cache. This updates the cached objects with the data from the database.

You can implement this type of refresh policy on each OracleAS TopLink descriptor, or just on certain queries, depending upon the nature of the application.

For more information about setting the refresh policy for a descriptor, see "Setting Descriptor Information" in the Oracle Application Server TopLink Mapping Workbench User's Guide.

For more information about setting the refresh policy for a query, see "Refresh".

Note:

Refreshing does not prevent phantom reads from occurring. See "Refreshing Finder Results".

EJB Finders and Refresh Policy

When you invoke a findByPrimaryKey finder, if the object exists in the cache, OracleAS TopLink returns that copy. This is the default behavior, regardless of the refresh policy. To force a database query, configure the query to refresh by setting refreshIdentityMapResult() on it.

For more information about caching options, see "Caching Options".