JBoss.orgCommunity Documentation

Chapter 33. The JMS Bridge

33.1. JMS Bridge Parameters
33.2. Source and Target Connection Factories
33.3. Source and Target Destination Factories
33.4. Quality Of Service
33.4.1. AT_MOST_ONCE
33.4.2. DUPLICATES_OK
33.4.3. ONCE_AND_ONLY_ONCE
33.4.4. Time outs and the JMS bridge
33.4.5. Examples

HornetQ includes a fully functional JMS message bridge.

The function of the bridge is to consume messages from a source queue or topic, and send them to a target queue or topic, typically on a different server.

The source and target servers do not have to be in the same cluster which makes bridging suitable for reliably sending messages from one cluster to another, for instance across a WAN, and where the connection may be unreliable.

A bridge can be deployed as a standalone application, with HornetQ standalone server or inside a JBoss AS instance. The source and the target can be located in the same virtual machine or another one.

The bridge can also be used to bridge messages from other non HornetQ JMS servers, as long as they are JMS 1.1 compliant.

Note

Do not confuse a JMS bridge with a core bridge. A JMS bridge can be used to bridge any two JMS 1.1 compliant JMS providers and uses the JMS API. A core bridge (described in Chapter 36, Core Bridges) is used to bridge any two HornetQ instances and uses the core API. Always use a core bridge if you can in preference to a JMS bridge. The core bridge will typically provide better performance than a JMS bridge. Also the core bridge can provide once and only once delivery guarantees without using XA.

The bridge has built-in resilience to failure so if the source or target server connection is lost, e.g. due to network failure, the bridge will retry connecting to the source and/or target until they come back online. When it comes back online it will resume operation as normal.

The bridge can be configured with an optional JMS selector, so it will only consume messages matching that JMS selector

It can be configured to consume from a queue or a topic. When it consumes from a topic it can be configured to consume using a non durable or durable subscription

Typically, the bridge is deployed by the JBoss Micro Container via a beans configuration file. This would typically be deployed inside the JBoss Application Server and the following example shows an example of a beans file that bridges 2 destinations which are actually on the same server.

<?xml version="1.0" encoding="UTF-8"?>

<deployment xmlns="urn:jboss:bean-deployer:2.0">

       <bean name="JMSBridge" class="org.hornetq.api.jms.bridge.impl.JMSBridgeImpl">
           <!-- HornetQ must be started before the bridge -->
           <depends>HornetQServer</depends>
           <constructor>
               <!-- Source ConnectionFactory Factory -->
               <parameter>
                   <inject bean="SourceCFF"/>
               </parameter>
               <!-- Target ConnectionFactory Factory -->
               <parameter>
                   <inject bean="TargetCFF"/>
               </parameter>
               <!-- Source DestinationFactory -->
               <parameter>
                   <inject bean="SourceDestinationFactory"/>
               </parameter>
               <!-- Target DestinationFactory -->
               <parameter>
                   <inject bean="TargetDestinationFactory"/>
               </parameter>
               <!-- Source User Name (no username here) -->
               <parameter><null /></parameter>
               <!-- Source Password (no password here)-->
               <parameter><null /></parameter>
               <!-- Target User Name (no username here)-->
               <parameter><null /></parameter>
               <!-- Target Password (no password here)-->
               <parameter><null /></parameter>
               <!-- Selector -->
               <parameter><null /></parameter>
               <!-- Failure Retry Interval (in ms) -->
               <parameter>5000</parameter>
               <!-- Max Retries -->
               <parameter>10</parameter>
               <!-- Quality Of Service -->
               <parameter>ONCE_AND_ONLY_ONCE</parameter>
               <!-- Max Batch Size -->
               <parameter>1</parameter>
               <!-- Max Batch Time (-1 means infinite) -->
               <parameter>-1</parameter>
               <!-- Subscription name (no subscription name here)-->
               <parameter><null /></parameter>
               <!-- Client ID  (no client ID here)-->
               <parameter><null /></parameter>
               <!-- Add MessageID In Header -->
               <parameter>true</parameter>
               <!-- register the JMS Bridge in the AS MBeanServer -->
               <parameter>
                   <inject bean="MBeanServer"/>
               </parameter>
               <parameter>org.hornetq:service=JMSBridge</parameter>
             </constructor>
           <property name="transactionManager">
               <inject bean="RealTransactionManager"/>
           </property>
       </bean>

       <!-- SourceCFF describes the ConnectionFactory used to connect to the 
            source destination -->
       <bean name="SourceCFF" 
            class="org.hornetq.api.jms.bridge.impl.JNDIConnectionFactoryFactory">
           <constructor>
               <parameter>
                   <inject bean="JNDI" />
               </parameter>
               <parameter>/ConnectionFactory</parameter>
           </constructor>  
       </bean>

       <!-- TargetCFF describes the ConnectionFactory used to connect to the 
        target destination -->
       <bean name="TargetCFF" 
            class="org.hornetq.api.jms.bridge.impl.JNDIConnectionFactoryFactory">
           <constructor>
               <parameter>
                   <inject bean="JNDI" />
               </parameter>
               <parameter>/ConnectionFactory</parameter>
           </constructor>  
       </bean>

       <!-- SourceDestinationFactory describes the Destination used as the source -->
       <bean name="SourceDestinationFactory" 
            class="org.hornetq.api.jms.bridge.impl.JNDIDestinationFactory">
           <constructor>
               <parameter>
                   <inject bean="JNDI" />
               </parameter>
               <parameter>/queue/source</parameter>
           </constructor>  
       </bean>

       <!-- TargetDestinationFactory describes the Destination used as the target -->
       <bean name="TargetDestinationFactory" 
            class="org.hornetq.api.jms.bridge.impl.JNDIDestinationFactory">
           <constructor>
               <parameter>
                   <inject bean="JNDI" />
               </parameter>
               <parameter>/queue/target</parameter>
           </constructor>  
       </bean>
       
       <!-- JNDI is a Hashtable containing the JNDI properties required -->
       <!-- to connect to the sources and targets JMS resrouces         -->       
      <bean name="JNDI" class="java.util.Hashtable">
         <constructor class="java.util.Map">
            <map class="java.util.Hashtable" keyClass="String"
                                             valueClass="String">
               <entry>
                  <key>java.naming.factory.initial</key>
                  <value>org.jnp.interfaces.NamingContextFactory</value>
               </entry>
               <entry>
                  <key>java.naming.provider.url</key>
                  <value>jnp://localhost:1099</value>
               </entry>
               <entry>
                  <key>java.naming.factory.url.pkgs</key>
                  <value>org.jboss.naming:org.jnp.interfaces"</value>
               </entry>
               <entry>
                  <key>jnp.timeout</key>
                  <value>5000</value>
               </entry>
               <entry>
                  <key>jnp.sotimeout</key>
                  <value>5000</value>
               </entry>
            </map>
         </constructor>
      </bean>

      <bean name="MBeanServer" class="javax.management.MBeanServer">
         <constructor factoryClass="org.jboss.mx.util.MBeanServerLocator"
                      factoryMethod="locateJBoss"/>
      </bean>
</deployment>

The main bean deployed is the JMSBridge bean. The bean is configurable by the parameters passed to its constructor.

The source and target connection factory factories are used to create the connection factory used to create the connection for the source or target server.

The configuration example above uses the default implementation provided by HornetQ that looks up the connection factory using JNDI. For other Application Servers or JMS providers a new implementation may have to be provided. This can easily be done by implementing the interface org.hornetq.jms.bridge.ConnectionFactoryFactory.

Again, similarly, these are used to create or lookup up the destinations.

In the configuration example above, we have used the default provided by HornetQ that looks up the destination using JNDI.

A new implementation can be provided by implementing org.hornetq.jms.bridge.DestinationFactory interface.

The quality of service modes used by the bridge are described here in more detail.

This QoS mode ensures messages will reach the destination from the source once and only once. (Sometimes this mode is known as "exactly once"). If both the source and the destination are on the same HornetQ server instance then this can be achieved by sending and acknowledging the messages in the same local transaction. If the source and destination are on different servers this is achieved by enlisting the sending and consuming sessions in a JTA transaction. The JTA transaction is controlled by JBoss Transactions JTA * implementation which is a fully recovering transaction manager, thus providing a very high degree of durability. If JTA is required then both supplied connection factories need to be XAConnectionFactory implementations. This is likely to be the slowest mode since it requires extra persistence for the transaction logging.

This mode is only available for durable messages.

Please see Section 11.3.5, “JMS Bridge” which shows how to configure and use a JMS Bridge with JBoss AS to send messages to the source destination and consume them from the target destination.

Please see Section 11.1.27, “JMS Bridge” which shows how to configure and use a JMS Bridge between two standalone HornetQ servers.