104 Configuring a JMS Coordinated Cache

This chapter describes the various components that you must configure in order to use a JMS coordinated cache.

This chapter includes the following sections:

• Introduction to JMS Coordinated Cache Configuration

• Configuring a Topic Name

• Configuring a Topic Connection Factory Name

• Configuring a Topic Host URL

• Configuring Connection Handling

Table 104-1 lists the configurable options for a JMS coordinated cache.

104.1 Introduction to JMS Coordinated Cache Configuration

Table 104-1 lists the configurable options for a JMS coordinated cache.

Table 104-1 Configurable Options for a JMS Coordinated Cache

Option to Configure	Oracle JDeveloper	TopLink Workbench	Java
Cache coordination change propagation at the descriptor level (see Section 119.15, "Configuring Cache Coordination Change Propagation at the Descriptor Level")
Synchronous change propagation mode (see Section 103.2, "Configuring the Synchronous Change Propagation Mode")
JNDI naming service (see Section 103.7, "Configuring JNDI Naming Service Information")
Topic name (see Section 104.2, "Configuring a Topic Name")
Topic connection factory name (see Section 104.3, "Configuring a Topic Connection Factory Name")
Topic host URSL (see Section 104.4, "Configuring a Topic Host URL")
Connection handling (see Section 104.5, "Configuring Connection Handling")
Context properties (see Section 103.11, "Configuring Context Properties")
Packet time-to-live (see Section 103.12, "Configuring a Packet Time-to-Live")

104.2 Configuring a Topic Name

A JMS topic identifies a publish/subscribe destination for a JMS server. JMS users who wish to share messages subscribe to the same JMS topic.

The topic name you configure is the name that TopLink uses to look up the javax.jms.Topic instance from the JNDI service. You must provide a fully qualified JNDI name, such as jms/<topic_name>.

All the members of the same JMS coordinated cache must use the same JMS topic.

104.2.1 How to Configure a Topic Name Using TopLink Workbench

To specify the topic name for JMS cache coordination, use this procedure:

1. Select a server session in the Navigator. Its properties appear in the Editor.

2. Click the Cache Coordination tab. The Cache Coordination tab appears.

3. Ensure Enable Cache Coordination is selected and the Type is JMS (see Section 102.3, "Cache Coordination" for more information).

   Figure 104-1 Cache Coordination Tab, Topic Name Field, JMS

   
   Description of "Figure 104-1 Cache Coordination Tab, Topic Name Field, JMS"
   
   

4. Enter the topic name to use with the JMS coordinated cache for this session. This must be a fully qualified JNDI name, such as jms/<topic_name>.

Enter the topic name to use with the JMS coordinated cache for this session. This must be a fully qualified JNDI name, such as jms/<topic_name>.

104.2.2 How to Configure a Topic Name Java

User the oracle.toplink.remotecommand.broadcast.BroadcastTransportManager method setTopicName to configure the Topic name for the Topic to which this transport manager will be connecting.

You obtain the BroadcastTransportManager using the following Session API:

Session.getCommandManager().getTransportManager()

104.3 Configuring a Topic Connection Factory Name

A JMS topic connection factory creates connections with the JMS provider for a specific JMS destination. Each connection factory contains the specific configuration information to create a connection to a JMS destination.

The topic connection factory name you configure is the name that TopLink uses to look up the javax.jms.TopicConnectionFactory instance from the JNDI service. This must be a fully qualified JNDI name, such as jms/<resource_name>.

104.3.1 How to Configure a Topic Connection Factory Name Using TopLink Workbench

To specify the topic connection factory for a JMS coordinated cache, use this procedure:

1. Select a server session in the Navigator. Its properties appear in the Editor.

2. Click the Cache Coordination tab. The Cache Coordination tab appears.

3. Ensure Enable Cache Coordination is selected and the Type is JMS (see Section 102.3, "Cache Coordination" for more information).

   Figure 104-2 Cache Coordination Tab, Topic Connection Factory Name Field

   
   Description of "Figure 104-2 Cache Coordination Tab, Topic Connection Factory Name Field"
   
   

4. Enter the topic connection factory name to use with the JMS coordinated cache for this session. This must be a fully qualified JNDI name, such as jms/<resource_name>.

Enter the topic connection factory name to use with the JMS coordinated cache for this session. This must be a fully qualified JNDI name, such as jms/<resource_name>.

104.3.2 How to Configure a Topic Connection Factory Name Using Java

Use the oracle.toplink.remotecommand.jms.JMSTopicTransportManager method setTopicConnectionFactoryName to configure the JMS Topic connection factory name for the JMS Topic connections.

You obtain the JMSTopicTransportManager using the following Session API:

Session.getCommandManager().getTransportManager()

104.4 Configuring a Topic Host URL

The JMS topic host URL is the URL of the machine on the network that hosts the JMS topic (see Section 104.2, "Configuring a Topic Name").

104.4.1 How to Configure a Topic Host URL Using TopLink Workbench

To specify the topic host URL for a JMS coordinated cache, use this procedure:

1. Select a server session in the Navigator. Its properties appear in the Editor.

2. Click the Cache Coordination tab. The Cache Coordination tab appears.

3. Ensure Enable Cache Coordination is selected and the Type is JMS (see Section 102.3, "Cache Coordination" for more information).

   Figure 104-3 Cache Coordination Tab, Topic Host URL Field

   
   Description of "Figure 104-3 Cache Coordination Tab, Topic Host URL Field"
   
   

Enter the URL of the machine on the network that hosts the JMS topic (see Section 104.2, "Configuring a Topic Name") to use with the JMS coordinated cache for this session.

104.4.2 How to Configure a Topic Host URL Using Java

Use the oracle.toplink.remotecommand.jms.JMSTopicTransportManager method setTopicHostURL to configure the URL of the computer on the network that hosts the JMS Topic.

You obtain the JMSTopicTransportManager using the following Session API:

Session.getCommandManager().getTransportManager()

104.5 Configuring Connection Handling

The session's transport manager creates connections to the various members of the coordinated cache. If a communication error occurs on one of these connections, you can configure the session to either ignore the error or remove the connection.

If you configure the session to remove the connection on error, the next time the session tries to communicate with that coordinated cache member, it will construct a new connection. If an error occurs during the connection creation phase, TopLink will either throw a RemoteCommandManagerException.ERROR_CREATING_JMS_CONNECTION (if the error occurred while sending a message) or a RemoteCommandManagerException.ERROR_CREATING_LOCAL_JMS_CONNECTION (if the error occurred while receiving a message). If you want to recover from this failure, consider the following options:

• You may choose to take no action: messages will not be sent or received.

• You may choose to handle the exception. You may do so by changing some of the oracle.toplink.remotecommand.jms.JMSTopicTransportManager settings and calling the createExternalConnection or createInternalConnection method of the JMSTopicTransportManager.

If you configure the session to ignore the error, the next time the session tries to communicate with that coordinated cache member, it will continue to use the same connection. In this case, if the listening (local) connection gets a RemoteCommandManagerException.ERROR_RECEIVING_JMS_MESSAGE exception, the coordinated cache waits for 10 seconds before resuming listening. If you want to recover from this failure, consider the following options:

• You may choose to take no action (wait for the connection recovery).

• You may choose to handle the RemoteCommandManagerException.ERROR_PROPAGATING_COMMAND or RemoteCommandManagerException.ERROR_RECEIVING_JMS_MESSAGE exception. You may do so by shutting down the remote command manager.

In either case, if the coordinated cache receives a null JMS message, it will throw a RemoteCommandManagerException.ERROR_RECEIVED_JMS_MESSAGE_IS_NULL exception.

104.5.1 How to Configure Connection Handling Using TopLink Workbench

To specify how TopLink handles session connections in the event of an error, use this procedure:

1. Select a session or session broker in the Navigator. Its properties appear in the Editor.

2. Click the Cache Coordination tab. The Cache Coordination tab appears.

3. Ensure the Enable Cache Coordination option is selected, then select the appropriate coordinated cache Type (JMS). The cache coordination options appear on the tab.

   Figure 104-4 Cache Coordination Tab, Remove Connection on Error Option

   
   Description of "Figure 104-4 Cache Coordination Tab, Remove Connection on Error Option"
   
   

4. Select the Remove Connection on Error option to configure the session to remove the data source connection in the event of an error.

Select the Remove Connection on Error option to configure the session to remove the data source connection in the event of an error.

104.5.2 How to Configure Connection Handling Using Java

Use the oracle.toplink.remotecommand.TransportManager method setShouldRemoveConnectionOnError to define whether connections to remote services should be disconnected when an error occurs.

You obtain the TransportManager using the following Session API:

Session.getCommandManager().getTransportManager()