Configuring and Using Coherence*Extend-JMS

Overview

Coherence*Extend-JMS allows you to use Coherence caching from outside of a Coherence cluster, using your existing JMS infrastructure as the means to connect to the cluster. Coherence*Extend-JMS uses a JMS-based protocol to invoke cache operations on a remote cluster node, but the details of doing so are hidden behind a local interface. Coherence*Extend-JMS includes support for the CacheStore and NamedCache interfaces.

The client (non-clustered) portion of Coherence*Extend-JMS is configured using the <jms-scheme> caching scheme. The <jms-scheme> can be used directly, from within a <cachestore-scheme>, or as the <back-scheme> of a near cache.

The clustered portion of Coherence*Extend-JMS can either be deployed as part of a J2EE application using the included NamedCacheProxyBean Message-Driven EJB or run in a stand-alone JVM using the included AdapterFactory command line application.

To configure and use Coherence*Extend-JMS:

• Specify a <jms-scheme> cache scheme in your Coherence cache configuration deployment descriptor.
• Create a properties file for your JNDI provider.
• Configure and deploy a JMS QueueConnectionFactory, TopicConnectionFactory, Queue, and Topic.
• Configure the cluster-side Coherence*Extend-JMS proxy.

The <jms-scheme> Cache Scheme

The <jms-scheme> cache scheme allows a non-clustered application JVM to access cached data from a Coherence cluster using a JMS-based protocol.

Consider the following scenario: there are a number of nodes on a local subnet running in a Coherence cluster. Each node of the cluster is reacheable by both UDP unicast and multicast and takes part in caching application data and performing various cluster-related tasks. Assume that you have another machine that you would like to be able to retrieve or update the cached application data, but due to network topology limitations the machine cannot be part of the Coherence cluster. In this case, the <jms-scheme> cache configuration descriptor element can be leveraged to access clustered application data from outside the Coherence cluster.

The following jms-cache-config.xml cache configuration descriptor is an example of using the <jms-scheme> element:

<cache-config>
  <caching-scheme-mapping>
    <cache-mapping>
      <cache-name>dist-jms-direct</cache-name>
      <scheme-name>jms-direct</scheme-name>
    </cache-mapping>
    <cache-mapping>
      <cache-name>dist-jms-local</cache-name>
      <scheme-name>jms-local</scheme-name>
    </cache-mapping>
    <cache-mapping>
      <cache-name>dist-jms-near</cache-name>
      <scheme-name>jms-near</scheme-name>
    </cache-mapping>
  </caching-scheme-mapping>

  <caching-schemes>
    <jms-scheme>
      <scheme-name>jms-direct</scheme-name>
      <queue-connection-factory-name>jms/tangosol/ConnectionFactory</queue-connection-factory-name>
      <topic-connection-factory-name>jms/tangosol/ConnectionFactory</topic-connection-factory-name>
      <queue-name>jms/tangosol/Queue</queue-name>
      <topic-name>jms/tangosol/Topic</topic-name>
      <request-timeout>10</request-timeout>
    </jms-scheme>

    <local-scheme>
      <scheme-name>jms-local</scheme-name>

      <eviction-policy>HYBRID</eviction-policy>
      <expiry-delay>30</expiry-delay>
      <flush-delay>30</flush-delay>

      <cachestore-scheme>
        <jms-scheme>
          <scheme-ref>jms-direct</scheme-ref>
        </jms-scheme>
      </cachestore-scheme>
    </local-scheme>

    <near-scheme>
      <scheme-name>jms-near</scheme-name>

      <front-scheme>
        <local-scheme>
          <high-units>100</high-units>
        </local-scheme>
      </front-scheme>

      <back-scheme>
        <jms-scheme>
          <scheme-ref>jms-direct</scheme-ref>
        </jms-scheme>
      </back-scheme>

      <invalidation-strategy>all</invalidation-strategy>
    </near-scheme>
  </caching-schemes>
</cache-config>

Assuming one or more Coherence*Extend-JMS proxies are running in the cluster (see below), start your Java application pointing to this cache configuration file using the following Java command:

java -Dtangosol.coherence.cacheconfig=jms-cache-config.xml ...

The NamedCache returned by the CacheFactory.getCache(String sCacheName) method will uses JMS to communicate with the Coherence cluster to retrieve and update data from the clustered cache with the same name.

Note that unlike other cache configurations, the <jms-scheme> will not cause any Coherence clustered service to be started.

Specifying JNDI Properties for your JNDI Provider

Coherence*Extend-JMS uses JNDI to obtain references to all JMS resources. To specify the JNDI properties that Coherence*Extend-JMS uses to create a JNDI InitialContext, create a file called jndi.properties that contains your JNDI provider's configuration properties and add the directory that contains the file to your classpath.

For example, if you are using WebLogic Server as your JNDI provider, your jndi.properties file would look something like the following:

java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
java.naming.provider.url=t3://localhost:7001
java.naming.security.principal=system
java.naming.security.credentials=weblogic

Configuring JMS Resources for the JMS Adapter

Coherence*Extend-JMS uses a JMS Queue and Topic to pass messages between the JMS stub (non-clustered node) and proxy (clustered node). Therefore, you must deploy an appropriately configured JMS QueueConnectionFactory, TopicConnectionFactory, Queue, and Topic. You must also be sure to register the JMS resources under the JNDI names that you specified in the <jms-scheme> cache scheme configuration.

For example, if you are using WebLogic Server as your JMS provider:

• If you haven't already done so, create and configure a JMS server.
• Create and configure a new JMS ConnectionFactory called TangosolConnectionFactory and register it under the JNDI name that you specified in your <jms-scheme> (e.g. jms/tangosol/ConnectionFactory). Be sure to add your server to the list of deployment targets for the JMS ConnectionFactory.
• Create and configure a new JMS Queue called TangosolQueue and register it under the JNDI name that you specified in your <jms-scheme> (e.g. jms/tangosol/Queue). Be sure to add your server to the list of deployment targets for the JMS Queue.
• Create and configure a new JMS Topic called TangosolTopic and register it under the JNDI name that you specified in your <jms-scheme> (e.g. jms/tangosol/Topic). Be sure to add your server to the list of deployment targets for the JMS Topic.
• Create and configure a new JMS Template called TangosolTemplate and specify it as the temporary template for your JMS server.

Starting a Coherence*Extend-JMS Proxy

The cluster-side portion of Coherence*Extend-JMS is called a JMS proxy. You can run the JMS proxy as part of a J2EE application using an included Message-Driven EJB or in one or more stand-alone JVMs. Coherence includes an example of running the JMS proxy in a stand-alone JVM that launches a DefaultCacheServer, but you can create your own JMS proxy application using the com.tangosol.net.jms.AdapterFactory class. See the AdapterFactory JavaDoc for additional information.

To deploy the JMS proxy as part of a J2EE application:

• Change the current directory to the Tangosol library directory (%TANGOSOL_HOME%\lib on Windows and $TANGOSOL_HOME/lib on Unix).
• Make sure that the paths are configured so that the Java Jar command will run.
• Unjar the coherence-jms.jar Message-Driven EJB to a temporary directory.
• Edit the ejb-jar.xml EJB deployment descriptor in the META-INF directory under the temporary directory in which you extracted coherence-jms.jar. The following environment entries must be configured appropriately:

  <env-entry>
    <env-entry-name>QueueConnectionFactory</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>jms/tangosol/ConnectionFactory</env-entry-value>
  </env-entry>
  <env-entry>
    <env-entry-name>TopicConnectionFactory</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>jms/tangosol/ConnectionFactory</env-entry-value>
  </env-entry>
  <env-entry>
    <env-entry-name>Queue</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>jms/tangosol/Queue</env-entry-value>
  </env-entry>
  <env-entry>
    <env-entry-name>Topic</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>jms/tangosol/Topic</env-entry-value>
  </env-entry>
  <env-entry>
    <env-entry-name>ClusterOwned</env-entry-name>
    <env-entry-type>java.lang.Boolean</env-entry-type>
    <env-entry-value>true</env-entry-value>
  </env-entry>

   

The QueueConnectionFactory environment entry must be set to the JNDI name of the JMS QueueConnectionFactory that you configured for your JMS provider. This entry defaults to jms/tangosol/ConnectionFactory.

The TopicConnectionFactory environment entry must be set to the JNDI name of the JMS TopicConnectionFactory that you configured for your JMS provider. This entry defaults to jms/tangosol/ConnectionFactory.

The Queue environment entry must be set to the JNDI name of the JMS Queue that you configured for your JMS provider. This entry defaults to jms/tangosol/Queue. Note that the destination of this MDB must be the same Queue as specified by the Queue environment entry.

The Topic environment entry must be set to the JNDI name of the JMS Topic that you configured for your JMS provider. This entry defaults to jms/tangosol/Topic.

The ClusterOwned environment entry indicates whether or not the Coherence cluster should be shut down fully by the Message-Driven EJB when it shuts down. This entry defaults to true.

• Add your container-specific EJB deployment descriptor to the META-INF directory. A WebLogic Server deployment descriptor is included for illustrative purposes. Be sure to specify the JNDI name of the JMS Queue that you configured for your JMS provider as the destination JNDI name of the Message-Driven EJB.
• Jar the contents of the temporary directory into a new coherence-jms.jar EJB JAR file, run any container-specific EJB deployment tools, and deploy the Message-Driven EJB to your J2EE application server.

To run the example of launching a JMS proxy in a stand-alone JVM:

• Change the current directory to the Tangosol library directory (%TANGOSOL_HOME%\lib on Windows and $TANGOSOL_HOME/lib on Unix).
• Make sure that the paths are configured so that the Java command will run.
• Add the directory that contains your jndi.properties file to the classpath environment variable.
• Start the AdapterFactory example command line application. For example, on Windows you would run the following command (note that it is broken up into multiple lines here only for formatting purposes; this is a single command typed on one line):

  java -cp coherence.jar;%classpath% com.tangosol.net.jms.AdapterFactory
                                     <QueueConnectionFactory name>
                                     <TopicConnectionFactory name>
                                     <Queue name>
                                     <Topic name>
                                     [<DefaultCacheServer args>*]
  

   
  On Unix:

  java -cp coherence.jar:$classpath com.tangosol.net.jms.AdapterFactory
                                    <QueueConnectionFactory name>
                                    <TopicConnectionFactory name>
                                    <Queue name>
                                    <Topic name>
                                    [<DefaultCacheServer args>*]
  

   

Advanced Configuration

The following table summarizes the various Java System properties that can be used to override advanced Coherence*Extend-JMS settings: