Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Configuring a JMS Coordinated Cache (ELUG)

Configurable Options for a JMS Coordinated Cache

Option to Configure EclipseLink Workbench Java

Cache coordination change propagation at the descriptor level

Supported

Supported

Synchronous change propagation mode

Supported

Supported

JNDI naming service information

Supported

Supported

Topic name

Supported

Supported

Topic connection factory name

Supported

Supported

Topic host URL

Supported

Supported

Connection handling

Supported

Supported

Context properties

Supported

Supported

Packet time-to-live

Unsupported.

Supported



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 EclipseLink 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.


How to Configure a Topic Name Using 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 Cache Coordination for more information).
    Cache Coordination Tab, Topic Name Field, JMS
    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>.


How to Configure a Topic Name Using Java

Use the org.eclipse.persistence.sessions.coordination.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()

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 EclipseLink 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>.


How to Configure a Topic Connection Factory Name Using 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 Cache Coordination for more information).
    Cache Coordination Tab, Topic Connection Factory Name Field
    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>.


How to Configure a Topic Connection Factory Name Using Java

Use the org.eclipse.persistence.sessions.coordination.jms.JMSTopicTransportManager method setTopicConnectionFactoryName to configure the the JMS Topic connection factory name for the JMS Topic connections.

You obtain the JMSTopicTransportManager using the following Session API:

Session.getCommandManager().getTransportManager()

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 Configuring a Topic Name).


How to Configure a Topic Host URL Using 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 Cache Coordination for more information).
    Cache Coordination Tab, Topic Host URL Field
    Cache Coordination Tab, Topic Host URL Field

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


How to Configure a Topic Host URL Using Java

Use the org.eclipse.persistence.sessions.coordination.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()

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, EclipseLink 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 org.eclipse.persistence.sessions.coordination.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.


How to Configure Connection Handling Using Workbench

To specify how EclipseLink 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.
    Cache Coordination Tab, Remove Connection on Error Option
    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.


How to Configure Connection Handling Using Java

Use the org.eclipse.persistence.sessions.coordination.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()



Copyright Statement

Back to the top