20.11.2. Create a JMS Bridge

Summary

A JMS bridge consumes messages from a source JMS queue or topic and sends them to a target JMS queue or topic, which is typically on a different server. It can be used to bridge messages between any JMS servers, as long as they are JMS 1.1 compliant. The source and destination JMS resources are looked up using JNDI and the client classes for the JNDI lookup must be bundled in a module. The module name is then declared in the JMS bridge configuration.

Procedure 20.2. Create a JMS Bridge

This procedure demonstrates how to configure a JMS bridge to migrate messages from a JBoss EAP 5.x server to a JBoss EAP 6 server.
  1. Configure the Bridge On the Source JMS Messaging Server

    Configure the JMS bridge on the source server using the instructions provided for that server type. For an example of how to configure a JMS Bridge for a JBoss EAP 5.x server, see the topic entitled Create a JMS Bridge in the Migration Guide for JBoss EAP 6.
  2. Configure the Bridge on the Destination JBoss EAP 6 Server

    In JBoss EAP 6.1 and later, the JMS bridge can be used to bridge messages from any JMS 1.1 compliant server. Because the source and target JMS resources are looked up using JNDI, the JNDI lookup classes of the source messaging provider, or message broker, must be bundled in a JBoss Module. The following steps use the fictitious 'MyCustomMQ' message broker as an example.
    1. Create the JBoss module for the messaging provider.
      1. Create a directory structure under EAP_HOME/modules/system/layers/base/ for the new module. The main/ subdirectory will contain the client JARs and module.xml file. The following is an example of the directory structure created for the MyCustomMQ messaging provider: EAP_HOME/modules/system/layers/base/org/mycustommq/main/
      2. In the main/ subdirectory, create a module.xml file containing the module definition for the messaging provider. The following is an example of the module.xml created for the MyCustomMQ messaging provider.
        <?xml version="1.0" encoding="UTF-8"?>
        <module xmlns="urn:jboss:module:1.1" name="org.mycustommq">
            <properties>
                <property name="jboss.api" value="private"/>
            </properties> 
        
            <resources>
                <!-- Insert resources required to connect to the source or target   -->
                <resource-root path="mycustommq-1.2.3.jar" />
                <resource-root path="mylogapi-0.0.1.jar" />
            </resources> 
        
            <dependencies>
               <!-- Add the dependencies required by JMS Bridge code                 -->
               <module name="javax.api" />
               <module name="javax.jms.api" />
               <module name="javax.transaction.api"/>
               <!-- Add a dependency on the org.hornetq module since we send         -->
               <!-- messages tothe HornetQ server embedded in the local EAP instance -->
               <module name="org.hornetq" />
            </dependencies>
        </module>
        
      3. Copy the messaging provider JARs required for the JNDI lookup of the source resources to the module's main/ subdirectory. The directory structure for the MyCustomMQ module should now look like the following.
        modules/
        `-- system
            `-- layers
                `-- base
                    `-- org
                          `-- mycustommq
                              `-- main
                                  |-- mycustommq-1.2.3.jar
                                  |-- mylogapi-0.0.1.jar
                                  |-- module.xml
        
    2. Configure the JMS bridge in the messaging subsystem of the JBoss EAP 6 server.
      1. Before you begin, stop the server and back up the current server configuration files. If you are running a standalone server, this is the EAP_HOME/standalone/configuration/standalone-full-ha.xml file. If you are running a managed domain, back up both the EAP_HOME/domain/configuration/domain.xml and the EAP_HOME/domain/configuration/host.xml files.
      2. Add the jms-bridge element to the messaging subsystem in the server configuration file. The source and target elements provide the names of the JMS resources used for JNDI lookups. If user and password credentials are specified, they are passed as arguments when JMS connection is created.
        The following is an example of the jms-bridge element configured for the MyCustomMQ messaging provider:
        <subsystem xmlns="urn:jboss:domain:messaging:1.3">
           ...
           <jms-bridge name="myBridge" module="org.mycustommq">
              <source>
                 <connection-factory name="ConnectionFactory"/>
                 <destination name="sourceQ"/>
                 <user>user1</user>
                 <password>pwd1</password>
                 <context>
                    <property key="java.naming.factory.initial" value="org.mycustommq.jndi.MyCustomMQInitialContextFactory"/>
                    <property key="java.naming.provider.url"    value="tcp://127.0.0.1:9292"/>
                 </context>
              </source>
              <target>
                 <connection-factory name="java:/ConnectionFactory"/>
                 <destination name="/jms/targetQ"/>
              </target>
              <quality-of-service>DUPLICATES_OK</quality-of-service>
              <failure-retry-interval>500</failure-retry-interval>
              <max-retries>1</max-retries>
              <max-batch-size>500</max-batch-size>
              <max-batch-time>500</max-batch-time>
              <add-messageID-in-header>true</add-messageID-in-header>
           </jms-bridge>
        </subsystem>
        
        In the above example, the JNDI properties are defined in the context element for the source. If the context element is omitted, as in the target example above, the JMS resources are looked up in the local instance.