Search
SupportConsoleDevelopersStart a trialContact

Chapter 31. The JMS Bridge

download PDF
HornetQ includes a fully-functional JMS message bridge, which consumes messages from a source queue or topic and sends them to a target queue or topic, usually 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.
The bridge can also be used to bridge messages from other non-HornetQ JMS servers that are JMS 1.1 compliant.

Important

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 34, Core Bridges) is used to bridge any two HornetQ instances and uses the core API. A core bridge will typically provide better performance than a JMS bridge, and provides 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 (for example, due to network failure), the bridge will attempt to reconnect to the target server until it comes back on line, at which point operations will resume 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.
The bridge is typically deployed by JBoss Microcontainer using a beans configuration file (jms-bridge-jboss-beans.xml), which is located in the JBOSS_DIST/jboss-as/server/PROFILE/deploy directory.
Example 31.1, “jms-bridge-jboss-beans.xml Sample Config” shows a configuration sample that bridges two destinations on the same server.

Example 31.1. jms-bridge-jboss-beans.xml Sample Config

<?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 user name here) -->
         <parameter><null /></parameter>
         <!-- Source Password (no password here)-->
         <parameter><null /></parameter>
         <!-- Target User Name (no user name 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 resources         -->       
  <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>
      </map>
   </constructor>
  </bean>

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

31.1. JMS Bridge Parameters

The JMSBridge bean, as shown in Example 31.1, “jms-bridge-jboss-beans.xml Sample Config”, is configured via parameters passed to its constructor in a particular order. This order, and a description of each parameter, is outlined in the list following.

Note

To leave a parameter unspecified (for example, if the authentication is anonymous or no message selector is provided), use <null /> for the unspecified parameter value.
Source Connection Factory Factory
Injects the SourceCFF bean defined in the jms-bridge-jboss-beans.xml file, which creates the ConnectionFactory.
Target Connection Factory Factory
Injects the TargetCFF bean defined in the jms-bridge-jboss-beans.xml file, which creates the target ConnectionFactory.
Source Destination Factory Factory
Injects the SourceDestinationFactory bean defined in the jms-bridge-jboss-beans.xml file, which creates the source Destination.
Target Destination Factory Factory
Injects the TargetDestinationFactory bean defined in the jms-bridge-jboss-beans.xml file, which creates the target Destination.
Source User Name
Defines the username used to create the source connection.
Source Password
Defines the password for the user name used to create the source connection.
Target User Name
Defines the user name used to create the target connection.
Target Password
Defines the password of the user name used to create the target connection.
Selector
Specifies a JMS selector expression used when consuming messages from the source destination. Only messages that match the selector expression will be bridged from the source to the target destination. The selector expression must follow the JMS selector syntax.
Failure Retry Interval
Specifies the time in milliseconds to wait in between attempting to recreate connections to the source or target servers when the bridge detects a connection failure.
Max Retries
Specifies the number of times to attempt to recreate connections to the source or target servers when the bridge detects a connection failure. The bridge will stop trying to reconnect after this number of tries. -1 means 'try forever'.
Quality of Service
Defines the quality of service mode. The possible values are:
  • AT_MOST_ONCE
  • DUPLICATES_OK
  • ONCE_AND_ONLY_ONCE
See Section 31.4, “Quality Of Service Modes” for a explanation of these modes.
Max Batch Size
Defines the maximum number of messages that should be consumed from the source connection before the messages are sent in a batch to the target destination. Its value must be 1 or greater.
Max Batch Time
Defines the number of milliseconds to wait before sending a batch to the target destination, even if the number of messages consumed has not reached MaxBatchSize. Its value must be 1 or greater, or -1 to specify 'wait forever'.
Subscription Name
If the source destination is a topic, and you want to consume from the topic with a durable subscription, this parameter defines the durable subscription name.
Client ID
If the source destination is a topic, and you want to consume from the topic with a durable subscription, this parameter defines the JMS client ID to use when creating or looking up the durable subscription.
Add MessageID In Header
When true, the original message's message ID is appended to the message sent to the destination in the HORNETQ_BRIDGE_MSG_ID_LIST header. If the message is bridged multiple times, each message ID is appended. This lets you use a distributed response pattern.

Note

When a message is received, a response can be sent using the correlation ID of the first message ID so that when the original sender receives the response it is able to correlate the message.
MBean Server
Set this to the place where the JMS Bridge is registered (the application server MBeanServer) to manage the JMS Bridge with JMX.
ObjectName
If MBeanServer is set, this parameter must be set to define the name used to register the JMS Bridge MBean. This name must be unique.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.