Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

10.3. Native ActiveMQ JMS-to-JMS Bridge

10.3.1. Embedded Native Configuration
Copy link

Overview
Copy link

The normal way to configure a native ActiveMQ JMS-to-JMS bridge is to embed it in an ActiveMQ broker instance. This makes sense, because the JMS-to-JMS bridge requires an ActiveMQ broker to be running in any case. This deployment approach means that you start and stop the ActiveMQ broker and the JMS-to-JMS bridge simultaneously, which is convenient from a systems management perspective.

Spring configuration
Copy link

Example 10.2, “Embedded native JMS-to-JMS Bridge” shows the outline configuration of a native JMS-to-JMS bridge embedded in a broker configuration. The native JMS-to-JMS bridge configuration is introduced by the jmsBridgeConnectors element, which can contain any number of jmsQueueConnector elements and jmsTopicConnector elements. The detailed configuration of the bridge is described in the following sections.

Example 10.2. Embedded native JMS-to-JMS Bridge

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" ... >
  ...
  <broker xmlns="http://activemq.apache.org/schema/core"
      id="localbroker"
      brokerName="localBroker"
      persistent="false">

    <jmsBridgeConnectors>
      <jmsQueueConnector> ... </jmsQueueConnector>
      ...
      <jmsTopicConnector> ... </jmsTopicConnector>
      ...
    </jmsBridgeConnectors>

    <transportConnectors>
      <transportConnector uri="tcp://localhost:61234" />
    </transportConnectors>

  </broker>
  ...
</beans>
Copy to Clipboard Toggle word wrap

Router rules
Copy link

The heart of the JMS-to-JMS bridge is a simple set of routing rules, where each rule describe how to pull messages off a particular queue or topic, and how to push the messages to the corresponding queue or topic in the other JMS provider. Figure 10.2, “Routing Rules in the JMS-to-JMS Bridge” shows an overview of the kinds of routing rule you can define in the JMS-to-JMS bridge.

Figure 10.2. Routing Rules in the JMS-to-JMS Bridge

Rule types
Copy link

The JMS-to-JMS bridge enables you to define the following types of routing rule:
  • Inbound queue-to-queue mapping—defines a rule for pulling messages off a queue in the third-party JMS provider and forwarding the messages to a queue (possibly with a different name) in the ActiveMQ broker.
  • Outbound queue-to-queue mapping—defines a rule for pulling messages off a queue in the ActiveMQ broker and forwarding the messages to a queue (possibly with a different name) in the third-party JMS provider.
  • Inbound topic-to-topic mapping—defines a rule for receiving messages from a topic in the third-party JMS provider and forwarding the messages to a topic (possibly with a different name) in the ActiveMQ broker.
  • Outbound topic-to-topic mapping—defines a rule for receiving messages from a topic in the ActiveMQ broker and forwarding the messages to a topic (possibly with a different name) in the third-party JMS provider.

10.3.2. Connecting to the ActiveMQ Broker
Copy link

Bootstrapping an embedded bridge
Copy link

In the case of an embedded JMS-to-JMS bridge (as shown in Example 10.2, “Embedded native JMS-to-JMS Bridge”), connecting to the ActiveMQ broker is trivial. The bridge automatically connects to the broker in which it is embedded, using the ActiveMQ VM (virtual machine) protocol.
In other words, no configuration is required to connect to the ActiveMQ broker in the embedded case.

Non-embedded deployments
Copy link

It is also possible to deploy a native JMS-to-JMS bridge separately from an ActiveMQ broker (non-embedded case). For this type of deployment, the jmsQueueConnector supports various attributes (localQueueConnection, localQueueConnectionFactory, and so on), which you can use to configure the ActiveMQ broker connection explicitly. Likewise, the jmsTopicConnector element supports attributes for configuring an ActiveMQ broker connection explicitly. This type of deployment lies beyond the scope of the current guide. We recommend that you use an embedded deployment of the native JMS-to-JMS bridge.

10.3.3. Connecting to the Third-Party JMS Provider
Copy link

Overview
Copy link

Reference a connection factory bean
Copy link

You can configure connections to a third-party JMS provider by instantiating a javax.jms.QueueConnectionFactory instance directly as a Spring bean. You can then reference this bean from the native JMS-to-JMS bridge by setting the outboundQueueConnectionFactory attribute of the jmsQueueConnector element.
For example, you can instantiate and reference a WebSphere MQ queue connection factory as follows: 
<beans ... >
  ...
  <broker xmlns="http://activemq.apache.org/schema/core" ... >

    <jmsBridgeConnectors>
      <jmsQueueConnector outboundQueueConnectionFactory="#remoteFactory">
        ...
      </jmsQueueConnector>
    </jmsBridgeConnectors>
    ...
  </broker>
  ...
  <!-- Configure IBM WebSphere MQ queue connection factory -->
  <bean id="remoteFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">
    <property name="transportType" value="1"/>
    <property name="hostName" value="localhost"/>
    <property name="port" value="1414"/>
    <property name="queueManager" value="QM_TEST"/>
  </bean>
  ...
</beans>
Copy to Clipboard Toggle word wrap
Similarly, you can configure the jmsTopicConnector element by setting the outboundTopicConnectionFactory attribute to reference a javax.jms.TopicConnectionFactory instance.

Look up a connection factory in JNDI
Copy link

You can configure connections to a third-party JMS provider by looking up a javax.jms.QueueConnectionFactory instance in a JNDI directory (assuming that some administrative tool has already instantiated and registered the connection factory in JNDI).
For example, to look up a WebSphere MQ connection factory in an LDAP based JNDI server, you could use a configuration like the following: 
<beans ... >
  ...
  <broker xmlns="http://activemq.apache.org/schema/core" ... >

    <jmsBridgeConnectors>
      <jmsQueueConnector
          jndiOutboundTemplate="#remoteJndi"
          outboundQueueConnectionFactoryName="cn=MQQueueCF">
        ...
      </jmsQueueConnector>
    </jmsBridgeConnectors>
    ...
  </broker>
  ...
  <!-- Configure a Spring JNDI template instance -->
  <bean id="remoteJndi" class="org.springframework.jndi.JndiTemplate">
    <property name="environment">
      <props>
        <prop key="java.naming.factory.initial">
            com.sun.jndi.ldap.LdapCtxFactory
        </prop>
        <prop key="java.naming.provider.url">
            ldap://server.company.com/o=company_us,c=us
        </prop>
      </props>
    </property>
  </bean>
  ...
</beans>
Copy to Clipboard Toggle word wrap
Where the jndiOutboundTemplate attribute references an org.springframework.jndi.JndiTemplate bean instance, which is a Spring wrapper class that configures a JNDI directory. In this example, the JNDI directory is LDAP based, so the JndiTemplate bean is configured with the URL for connecting to the LDAP server. The outboundQueueConnectionFactoryName attribute specifies a query on the LDAP server, which should return a javax.jms.QueueConnectionFactory instance.

10.3.4. Configuring Queue Bridges
Copy link

Overview
Copy link

The routing of queue messages within the native JMS-to-JMS bridge is configured using the inboundQueueBridges element and the outboundQueueBridges element. Using these elements, you can specify which queues to bridge between the third-party JMS provider and the ActiveMQ broker.

Inbound queue bridges
Copy link

The inboundQueueBridges element and the inboundQueueBridge child elements are used to route queue messages from the third-party JMS provider to the ActiveMQ broker. In this case, inbound means heading into the ActiveMQ broker.
For example, consider the following inbound queue bridge configuration in Spring XML: 
<inboundQueueBridges>
  <inboundQueueBridge inboundQueueName="QueueA" />
</inboundQueueBridges>
Copy to Clipboard Toggle word wrap
The preceding configuration creates a JMS consumer client, which is connected to the third-party JMS provider, and a JMS producer client, which is connected to the ActiveMQ broker. The bridge pulls messages off the QueueA queue on the third-party JMS provider and pushes the messages on to the QueueA queue on the ActiveMQ broker.
If the names of the corresponding queues in each provider are different, you can map between the queues using the following configuration: 
<inboundQueueBridges>
  <inboundQueueBridge
      inboundQueueName="QueueA"
      localQueueName="org.activemq.example.QueueA" />
</inboundQueueBridges>
Copy to Clipboard Toggle word wrap
Where inboundQueueName specifies the name of the queue on the third-party JMS provider and localQueueName specifies the name of the queue on the ActiveMQ broker.

Outbound queue bridges
Copy link

The outboundQueueBridges element and the outboundQueueBridge child elements are used to route queue messages from the ActiveMQ broker to the third-party JMS provider. In this case, outbound means heading away from the ActiveMQ broker.
For example, consider the following outbound queue bridge configuration in Spring XML: 
<outboundQueueBridges>
  <outboundQueueBridge outboundQueueName="QueueX" />
</inboundQueueBridges>
Copy to Clipboard Toggle word wrap
The preceding configuration creates a JMS consumer client, which is connected to the ActiveMQ broker, and a JMS producer client, which is connected to the third-party JMS provider. The bridge pulls messages off the QueueX queue on the ActiveMQ broker and pushes the messages on to the QueueX queue on the third-party JMS provider.
If the names of the corresponding queues in each provider are different, you can map between the queues using the following configuration: 
<outboundQueueBridges>
  <outboundQueueBridge
      outboundQueueName="QueueX"
      localQueueName="org.activemq.example.QueueX" />
</inboundQueueBridges>
Copy to Clipboard Toggle word wrap
Where outboundQueueName specifies the name of the queue on the third-party JMS provider and localQueueName specifies the name of the queue on the ActiveMQ broker.

Sample queue bridges
Copy link

Example 10.3, “Sample Queue Bridges” shows a sample configuration of a native JMS-to-JMS bridge, which routes three inbound queues, QueueA, QueueB, and QueueC, and three outbound queues, QueueX, QueueY, and QueueZ.

Example 10.3. Sample Queue Bridges

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" ... >
  ...
  <broker xmlns="http://activemq.apache.org/schema/core" ... >

    <jmsBridgeConnectors>
      <jmsQueueConnector
        outboundQueueConnectionFactory="#remoteFactory">

        <inboundQueueBridges>
          <inboundQueueBridge inboundQueueName="QueueA" />
          <inboundQueueBridge inboundQueueName="QueueB" />
          <inboundQueueBridge inboundQueueName="QueueC" />
        </inboundQueueBridges>

        <outboundQueueBridges>
          <outboundQueueBridge outboundQueueName="QueueX" />
          <outboundQueueBridge outboundQueueName="QueueY" />
          <outboundQueueBridge outboundQueueName="QueueZ" />
        </outboundQueueBridges>
      </jmsQueueConnector>
    </jmsBridgeConnectors>

    <transportConnectors>
      <transportConnector uri="tcp://localhost:61234" />
    </transportConnectors>

  </broker>
  ...
</beans>
Copy to Clipboard Toggle word wrap

10.3.5. Configuring Topic Bridges
Copy link

Overview
Copy link

The routing of topic messages within the native JMS-to-JMS bridge is configured using the inboundTopicBridges element and the outboundTopicBridges element. Using these elements, you can specify which topics to bridge between the third-party JMS provider and the ActiveMQ broker.

Inbound topic bridges
Copy link

The inboundTopicBridges element and the inboundTopicBridge child elements are used to route topic messages from the third-party JMS provider to the ActiveMQ broker. In this case, inbound means heading into the ActiveMQ broker.
For example, consider the following inbound topic bridge configuration in Spring XML: 
<inboundTopicBridges>
  <inboundTopicBridge inboundTopicName="TopicA" />
</inboundTopicBridges>
Copy to Clipboard Toggle word wrap
The preceding configuration creates a JMS consumer client, which is connected to the third-party JMS provider, and a JMS producer client, which is connected to the ActiveMQ broker. The bridge pulls messages off the TopicA topic on the third-party JMS provider and pushes the messages on to the TopicA topic on the ActiveMQ broker.
If the names of the corresponding topics in each provider are different, you can map between the topics using the following configuration: 
<inboundTopicBridges>
  <inboundTopicBridge
      inboundTopicName="TopicA"
      localTopicName="org.activemq.example.TopicA" />
</inboundTopicBridges>
Copy to Clipboard Toggle word wrap
Where inboundTopicName specifies the name of the topic on the third-party JMS provider and localTopicName specifies the name of the topic on the ActiveMQ broker.

Outbound topic bridges
Copy link

The outboundTopicBridges element and the outboundTopicBridge child elements are used to route topic messages from the ActiveMQ broker to the third-party JMS provider. In this case, outbound means heading away from the ActiveMQ broker.
For example, consider the following outbound topic bridge configuration in Spring XML: 
<outboundTopicBridges>
  <outboundTopicBridge outboundTopicName="TopicX" />
</inboundTopicBridges>
Copy to Clipboard Toggle word wrap
The preceding configuration creates a JMS consumer client, which is connected to the ActiveMQ broker, and a JMS producer client, which is connected to the third-party JMS provider. The bridge pulls messages off the TopicX topic on the ActiveMQ broker and pushes the messages on to the TopicX topic on the third-party JMS provider.
If the names of the corresponding topics in each provider are different, you can map between the topics using the following configuration: 
<outboundTopicBridges>
  <outboundTopicBridge
      outboundTopicName="TopicX"
      localTopicName="org.activemq.example.TopicX" />
</inboundTopicBridges>
Copy to Clipboard Toggle word wrap
Where outboundTopicName specifies the name of the topic on the third-party JMS provider and localTopicName specifies the name of the topic on the ActiveMQ broker.

Sample topic bridges
Copy link

Example 10.4, “Sample Topic Bridges” shows a sample configuration of a native JMS-to-JMS bridge, which routes three inbound topics, TopicA, TopicB, and TopicC, and three outbound topics, TopicX, TopicY, and TopicZ.

Example 10.4. Sample Topic Bridges

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" ... >
  ...
  <broker xmlns="http://activemq.apache.org/schema/core" ... >

    <jmsBridgeConnectors>
      <jmsTopicConnector
        outboundTopicConnectionFactory="#remoteFactory">

        <inboundTopicBridges>
          <inboundTopicBridge inboundTopicName="TopicA" />
          <inboundTopicBridge inboundTopicName="TopicB" />
          <inboundTopicBridge inboundTopicName="TopicC" />
        </inboundTopicBridges>

        <outboundTopicBridges>
          <outboundTopicBridge outboundTopicName="TopicX" />
          <outboundTopicBridge outboundTopicName="TopicY" />
          <outboundTopicBridge outboundTopicName="TopicZ" />
        </outboundTopicBridges>
      </jmsTopicConnector>
    </jmsBridgeConnectors>

    <transportConnectors>
      <transportConnector uri="tcp://localhost:61234" />
    </transportConnectors>

  </broker>
  ...
</beans>
Copy to Clipboard Toggle word wrap

10.3.6. Deploying a Bridge
Copy link

Overview
Copy link

To deploy a native JMS-to-JMS bridge in the JBoss A-MQ broker, perform the following steps:

Deploy the Third-Party Client Libraries
Copy link

A basic prerequisite for using the third-party JMS provider is that the third-party JMS client libraries are installed in the JBoss A-MQ OSGi container. Before they are deployed into the OSGi container, however, the third-party client JARs must also be packaged as OSGi bundles. A quick and easy way to convert a JAR into an OSGi bundle is to prefix it with the wrap: URL prefix.
For example, given the client JAR file foo-jms-client.jar located in the /tmp directory, you could deploy it into the OSGi container as follows: 
JBossA-MQ:karaf@root> osgi:install -s wrap:file:///tmp/foo-jms-client.jar
Copy to Clipboard Toggle word wrap
If the third-party client libraries are already packaged as OSGi bundles, you can leave out the wrap: prefix.

Deploy the Bridge
Copy link

To deploy the native JMS-to-JMS bridge in embedded mode, edit the InstallDir/etc/activemq.xml file, and insert the jmsBridgeConnectors element as a child of the broker element, as follows: 
<beans ... >

    <!-- Allows us to use system properties and fabric as variables in this configuration file -->
    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="properties">
            <bean class="org.fusesource.mq.fabric.ConfigurationProperties"/>
        </property>      
    </bean>

    <broker xmlns="http://activemq.apache.org/schema/core"
            brokerName="${broker-name}"
            dataDirectory="${data}"
            start="false">
        ...
        <jmsBridgeConnectors>
            <jmsQueueConnector> ... </jmsQueueConnector>
            ...
            <jmsTopicConnector> ... </jmsTopicConnector>
            ...
        </jmsBridgeConnectors>
        ...
    </broker>

</beans>
Copy to Clipboard Toggle word wrap
The native JMS-to-JMS bridge will be enabled when you restart the A-MQ broker.

10.3.7. Sample Bridge Configuration
Copy link

Overview
Copy link

This section describes a sample configuration for native JMS-to-JMS bridge between a JBoss A-MQ broker and a WebSphere MQ server. This example assumes you are using the Java client libraries from WebSphere MQ version 7.0.1.3.

ActiveMQ-to-WebSphere MQ bridge
Copy link

Example 10.5, “ActiveMQ-to-WebSphere MQ Configuration” shows a sample configuration for an ActiveMQ-to-WebSphere MQ bridge, which you could add to the broker configuration in the InstallDir/etc/activemq.xml file.

Example 10.5. ActiveMQ-to-WebSphere MQ Configuration

<beans ... >

    <!-- Allows us to use system properties and fabric as variables in this configuration file -->
    <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="properties">
            <bean class="org.fusesource.mq.fabric.ConfigurationProperties"/>
        </property>      
    </bean>

    <broker xmlns="http://activemq.apache.org/schema/core"
            brokerName="${broker-name}"
            dataDirectory="${data}"
            start="false">
        ...
        <jmsBridgeConnectors>
            <jmsQueueConnector outboundQueueConnectionFactory="#remoteFactory">
                <inboundQueueBridges>
                    <inboundQueueBridge inboundQueueName="QueueA" />
                </inboundQueueBridges>

                <outboundQueueBridges>
                    <outboundQueueBridge outboundQueueName="QueueX" />
                </outboundQueueBridges>
            </jmsQueueConnector>
        </jmsBridgeConnectors>
        ...
    </broker>
    ...
    <!-- Configure IBM WebSphere MQ queue connection factory -->
    <bean id="remoteFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">
        <property name="transportType" value="1"/>
        <property name="hostName" value="localhost"/>
        <property name="port" value="1414"/>
        <property name="queueManager" value="QM_TEST"/>
    </bean>
    ...
</beans>
Copy to Clipboard Toggle word wrap
This example assumes that you have already created a QueueA queue and a QueueX queue on the WebSphere MQ server. ActiveMQ will create the corresponding queues dynamically—there is no need to create them in advance.

Deploying the WebSphere MQ client libraries
Copy link

Conveniently, WebSphere MQ 7.0 provides OSGi bundle versions of the client libraries in the following directory: 
$MQ_INSTALL_DIR/java/lib/OSGI
Copy to Clipboard Toggle word wrap
For the WebSphere MQ Java client, you need to install the following JARs (OSGi bundles): 
com.ibm.mq.osgi.directip_7.0.1.3.jar
com.ibm.msg.client.osgi.commonservices.j2se_7.0.1.3.jar
com.ibm.msg.client.osgi.jms.prereq_7.0.1.3.jar
com.ibm.msg.client.osgi.jms_7.0.1.3.jar
com.ibm.msg.client.osgi.nls_7.0.1.3.jar
com.ibm.msg.client.osgi.wmq.nls_7.0.1.3.jar
com.ibm.msg.client.osgi.wmq.prereq_7.0.1.3.jar
com.ibm.msg.client.osgi.wmq_7.0.1.3.jar
Copy to Clipboard Toggle word wrap
You can deploy these client libraries into JBoss A-MQ OSGi container using the following series of install commands: 
JBossA-MQ:karaf@root> osgi:install -s file:/tmp/mqclient/com.ibm.mq.osgi.directip_7.0.1.3.jar
JBossA-MQ:karaf@root> osgi:install -s file:/tmp/mqclient/com.ibm.msg.client.osgi.commonservices.j2se_7.0.1.3.jar
JBossA-MQ:karaf@root> osgi:install -s file:/tmp/mqclient/com.ibm.msg.client.osgi.jms.prereq_7.0.1.3.jar
JBossA-MQ:karaf@root> osgi:install -s file:/tmp/mqclient/com.ibm.msg.client.osgi.jms_7.0.1.3.jar
JBossA-MQ:karaf@root> osgi:install -s file:/tmp/mqclient/com.ibm.msg.client.osgi.nls_7.0.1.3.jar
JBossA-MQ:karaf@root> osgi:install -s file:/tmp/mqclient/com.ibm.msg.client.osgi.wmq.nls_7.0.1.3.jar
JBossA-MQ:karaf@root> osgi:install -s file:/tmp/mqclient/com.ibm.msg.client.osgi.wmq.prereq_7.0.1.3.jar
JBossA-MQ:karaf@root> osgi:install -s file:/tmp/mqclient/com.ibm.msg.client.osgi.wmq_7.0.1.3.jar
Copy to Clipboard Toggle word wrap

10.3.8. Handling ReplyTo Destinations
Copy link

Overview
Copy link

One of the features of the native ActiveMQ JMS-to-JMS bridge is its ability to handle ReplyTo destinations automatically. No special configuration is necessary—this feature is enabled by default.

ReplyTo destinations
Copy link

ReplyTo destinations are a feature of the JMS specification. An individual JMS message can be created with a JMSReplyTo header, which specifies the Destination (Queue or Topic) on which the sender expects to receive a reply.

Automatic proxification
Copy link

To support ReplyTo destinations effectively, the native JMS-to-JMS bridge implements support for automatic proxification. The problem is that whenever a message defines a JMSReplyTo header, a corresponding rule must be put in place to ensure that the reply message is propagated back through the bridge. In general, the most effective approach is for the bridge to create the required rule dynamically, whenever a JMSReployTo header is encountered.
For example, Figure 10.3, “Automatic Proxification in the native JMS-to-JMS Bridge” shows how the native JMS-to-JMS bridge automatically creates a return route for the reply to message M1, where the ReplyTo destination is a queue named ReplyA.

Figure 10.3. Automatic Proxification in the native JMS-to-JMS Bridge

10.3.9. Implementing Message Convertors
Copy link

Overview
Copy link

Sometimes, in addition to forwarding messages, it is also necessary to reformat the messages that pass through the bridge. The native JMS-to-JMS bridge provides interception points for converting queue messages and topic messages.
You can implement two different kinds of message convertor, as follows:
  • Inbound message convertor—converts third-party JMS messages to ActiveMQ messages.
  • Outbound message convertor—converts ActiveMQ messages to third-party JMS messages.

JmsMessageConvertor interface
Copy link

Example 10.6, “JmsMessageConvertor interface” shows the definition of the JmsMessageConvertor interface, which can be used as the basis for implementing either an inbound message convertor or an outbound message convertor.

Example 10.6. JmsMessageConvertor interface

package org.apache.activemq.network.jms;

import javax.jms.Connection;
import javax.jms.Destination;
import javax.jms.JMSException;
import javax.jms.Message;

/**
 * Converts Message from one JMS to another
 */
public interface JmsMesageConvertor {

    Message convert(Message message) throws JMSException;

    Message convert(Message message, Destination replyTo) throws JMSException;

    void setConnection(Connection connection);

}
Copy to Clipboard Toggle word wrap

Message converter methods
Copy link

The JmsMesageConvertor interface exposes the following methods:
Message convert(Message message)
This variant of the convert method is called, if the doHandleReplyTo option is set to false or if the ReplyTo destination on the message is null. In this case, the convert method should simply reformat the message content as required.
Message convert(Message message, Destination replyTo)
This variant of the convert method is called, if the ReplyTo destination on the message is non-null. In this case, in addition to reformatting the message, you have the ability to change the replyTo destination, so that the reply to this message is redirected to a different destination.
The replyTo argument contains the original destination of the message. If you want to change the ReplyTo destination, you can do so by calling the message.setJMSReplyTo() method, passing in the changed destination.
The reason you might want to change the ReplyTo destination is in order to take control of proxification (see Section 10.3.8, “Handling ReplyTo Destinations”). Proxification is necessary, because the ActiveMQ broker is not able to make a direct connection back to the third-party JMS provider.
void setConnection(Connection connection)
Provides a reference to the javax.jms.Connection object to which messages will be forwarded. In other words, if this message convertor is used as an inbound message convertor, this connection is the connection to the ActiveMQ broker. If this message convertor is used as an outbound message convertor, this connection is the connection to the third-party JMS provider.

Sample implementation
Copy link

Example 10.7, “Sample Message Convertor” shows a trivial implementation of a message convertor, which passes messages through without performing any conversion.

Example 10.7. Sample Message Convertor

package org.apache.activemq.network.jms;

import javax.jms.Connection;
import javax.jms.Destination;
import javax.jms.JMSException;
import javax.jms.Message;

/**
 * Converts Message from one JMS to another
 *
 * @org.apache.xbean.XBean
 */
public class SimpleJmsMessageConvertor implements JmsMesageConvertor {

    public Message convert(Message message) throws JMSException {
        return message;
    }

    public Message convert(Message message, Destination replyTo) throws JMSException {
        Message msg = convert(message);
        if (replyTo != null) {
            msg.setJMSReplyTo(replyTo);
        } else {
            msg.setJMSReplyTo(null);
        }
        return msg;
    }

    public void setConnection(Connection connection) {
        // do nothing
    }
}
Copy to Clipboard Toggle word wrap

Configuring the message convertor
Copy link

Message convertors can be attached to the native JMS-to-JMS bridge using the inboundMessageConvertor and outboundMessageConvertor attributes.
For example, to use the SimpleJmsMessageConvertor implementation both as an inbound message convertor and as an outbound message convertor, you could configure a JMS queue connector as follows: 
<jmsBridgeConnectors>
  <jmsQueueConnector
      outboundQueueConnectionFactory="#remoteFactory"
      inboundMessageConvertor="org.apache.activemq.network.jms.SimpleJmsMessageConvertor"
      outboundMessageConvertor="org.apache.activemq.network.jms.SimpleJmsMessageConvertor">

    <inboundQueueBridges>
      <inboundQueueBridge inboundQueueName="QueueA" />
    </inboundQueueBridges>

    <outboundQueueBridges>
      <outboundQueueBridge outboundQueueName="QueueX" />
    </outboundQueueBridges>
  </jmsQueueConnector>
</jmsBridgeConnectors>
Copy to Clipboard Toggle word wrap

10.3.10. Configuration Reference
Copy link

Overview
Copy link

jmsQueueConnector attributes
Copy link

The following attributes can be used to configure the jmsQueueConnector element:
id
Optional beran ID of xs:ID type, which could be used to reference this bean.
inboundMessageConvertor
References a bean instance of org.apache.activemq.network.jms.JmsMesageConvertor type, which transforms inbound messages from the third-party JMS provider into a format that is suitable for the ActiveMQ broker.
jndiLocalTemplate
References a bean instance of org.springframework.jndi.JndiTemplate type, which provides access to a JNDI directory instance. Used in combination with the localConnectionFactoryName attribute to locate a JMS QueueConnectionFactory instance in a JNDI directory, where this connection factory instance is then used to connect to the local JMS provider (that is, the ActiveMQ broker).
jndiOutboundTemplate
References a bean instance of org.springframework.jndi.JndiTemplate type, which provides access to a JNDI directory instance. Used in combination with the outboundQueueConnectionFactoryName attribute to locate a JMS QueueConnectionFactory instance in a JNDI directory, where this connection factory instance is then used to connect to the third-party JMS provider.
localClientId
Sets the ID of the local connection (useful for logging and JMX monitoring).
localConnectionFactoryName
Specifies the JNDI name of a QueueConnectionFactory instance. Used in combination with the jndiLocalTemplate attribute to connect to the local JMS provider (that is, the ActiveMQ broker).
localPassword
Specifies the password part of the credentials used to log on to the local JMS provider (ActiveMQ broker). Used in combination with the localUsername attribute.
localQueueConnection
References a bean of javax.jms.QueueConnection type, which is used to connect to the local JMS provider (ActiveMQ broker).
localQueueConnectionFactory
References a bean of javax.jms.QueueConnectionFactory type, which is used to connect to the local JMS provider (ActiveMQ broker).
localUsername
Specifies the username part of the credentials used to log on to the local JMS provider (ActiveMQ broker). Used in combination with the localPassword attribute.
name
Assigns a name to this jmsQueueConnector element (useful for logging and JMX monitoring).
outboundClientId
Sets the ID of the third-party connection (useful for logging and JMX monitoring).
outboundMessageConvertor
References a bean instance of org.apache.activemq.network.jms.JmsMesageConvertor type, which transforms outbound messages from the ActiveMQ broker into a format that is suitable for the third-party JMS provider.
outboundPassword
Specifies the password part of the credentials used to log on to the third-party JMS provider. Used in combination with the outboundUsername attribute.
outboundQueueConnection
References a bean of javax.jms.QueueConnection type, which is used to connect to the third-party JMS provider.
outboundQueueConnectionFactory
References a bean of javax.jms.QueueConnectionFactory type, which is used to connect to the third-party JMS provider.
outboundQueueConnectionFactoryName
Specifies the JNDI name of a QueueConnectionFactory instance. Used in combination with the jndiOutboundTemplate attribute to connect to the third-party JMS provider.
outboundUsername
Specifies the username part of the credentials used to log on to the third-party JMS provider. Used in combination with the outboundPassword attribute.
preferJndiDestinationLookup
Specifies whether the connector should first try to find a destination in JNDI before using JMS semantics to create a Destination. By default, the connector will first use JMS semantics and then fall back to JNDI look-up. Setting this attribute to true reverses that order.

jmsTopicConnector attributes
Copy link

The following attributes can be used to configure the jmsTopicConnector element:
id
Optional bean ID of xs:ID type, which could be used to reference this bean.
inboundMessageConvertor
References a bean instance of org.apache.activemq.network.jms.JmsMesageConvertor type, which transforms inbound messages from the third-party JMS provider into a format that is suitable for the ActiveMQ broker.
jndiLocalTemplate
References a bean instance of org.springframework.jndi.JndiTemplate type, which provides access to a JNDI directory instance. Used in combination with the localConnectionFactoryName attribute to locate a JMS TopicConnectionFactory instance in a JNDI directory, where this connection factory instance is then used to connect to the local JMS provider (that is, the ActiveMQ broker).
jndiOutboundTemplate
References a bean instance of org.springframework.jndi.JndiTemplate type, which provides access to a JNDI directory instance. Used in combination with the outboundTopicConnectionFactoryName attribute to locate a JMS TopicConnectionFactory instance in a JNDI directory, where this connection factory instance is then used to connect to the third-party JMS provider.
localClientId
Sets the ID of the local connection (useful for logging and JMX monitoring).
localConnectionFactoryName
Specifies the JNDI name of a TopicConnectionFactory instance. Used in combination with the jndiLocalTemplate attribute to connect to the local JMS provider (that is, the ActiveMQ broker).
localPassword
Specifies the password part of the credentials used to log on to the local JMS provider (ActiveMQ broker). Used in combination with the localUsername attribute.
localTopicConnection
References a bean of javax.jms.TopicConnection type, which is used to connect to the local JMS provider (ActiveMQ broker).
localTopicConnectionFactory
References a bean of javax.jms.TopicConnectionFactory type, which is used to connect to the local JMS provider (ActiveMQ broker).
localUsername
Specifies the username part of the credentials used to log on to the local JMS provider (ActiveMQ broker). Used in combination with the localPassword attribute.
name
Assigns a name to this jmsTopicConnector element (useful for logging and JMX monitoring).
outboundClientId
Sets the ID of the third-party connection (useful for logging and JMX monitoring).
outboundMessageConvertor
References a bean instance of org.apache.activemq.network.jms.JmsMesageConvertor type, which transforms outbound messages from the ActiveMQ broker into a format that is suitable for the third-party JMS provider.
outboundPassword
Specifies the password part of the credentials used to log on to the third-party JMS provider. Used in combination with the outboundUsername attribute.
outboundTopicConnection
References a bean of javax.jms.TopicConnection type, which is used to connect to the third-party JMS provider.
outboundTopicConnectionFactory
References a bean of javax.jms.TopicConnectionFactory type, which is used to connect to the third-party JMS provider.
outboundTopicConnectionFactoryName
Specifies the JNDI name of a TopicConnectionFactory instance. Used in combination with the jndiOutboundTemplate attribute to connect to the third-party JMS provider.
outboundUsername
Specifies the username part of the credentials used to log on to the third-party JMS provider. Used in combination with the outboundPassword attribute.
preferJndiDestinationLookup
Specifies whether the connector should first try to find a destination in JNDI before using JMS semantics to create a Destination. By default, the connector will first use JMS semantics and then fall back to JNDI look-up. Setting this attribute to true reverses that order.

inboundQueueBridge attributes
Copy link

The following attributes can be used to configure the inboundQueueBridge element:
doHandleReplyTo
A boolean attribute that specifies whether ReplyTo messages should be handled or not. Default is true.
id
Optional bean ID of xs:ID type, which could be used to reference this bean.
inboundQueueName
Specifies the name of the queue in the third-party JMS provider, from which messages are consumed.
localQueueName
Specifies the local queue name (in the ActiveMQ broker), into which messages are pushed. If not specified, defaults to the same value as inboundQueueName.
selector
Optionally, specifies a JMS selector string.

outboundQueueBridge attributes
Copy link

The following attributes can be used to configure the outboundQueueBridge element:
doHandleReplyTo
A boolean attribute that specifies whether ReplyTo messages should be handled or not. Default is true.
id
Optional bean ID of xs:ID type, which could be used to reference this bean.
outboundQueueName
Specifies the name of the queue in the third-party JMS provider, into which messages are pushed.
localQueueName
Specifies the local queue name (in the ActiveMQ broker), from which messages are consumed. If not specified, defaults to the same value as outboundQueueName.
selector
Optionally, specifies a JMS selector string.

inboundTopicBridge attributes
Copy link

The following attributes can be used to configure the inboundTopicBridge element:
consumerName
If this attribute is set, the bridge creates a durable consumer for this topic.
doHandleReplyTo
A boolean attribute that specifies whether ReplyTo messages should be handled or not. Default is true.
id
Optional bean ID of xs:ID type, which could be used to reference this bean.
inboundTopicName
Specifies the name of the topic in the third-party JMS provider, from which messages are consumed.
localTopicName
Specifies the local topic name (in the ActiveMQ broker), into which messages are pushed. If not specified, defaults to the same value as inboundTopicName.
selector
Optionally, specifies a JMS selector string.

outboundTopicBridge attributes
Copy link

The following attributes can be used to configure the outboundTopicBridge element:
consumerName
If this attribute is set, the bridge creates a durable consumer for this topic.
doHandleReplyTo
A boolean attribute that specifies whether ReplyTo messages should be handled or not. Default is true.
id
Optional bean ID of xs:ID type, which could be used to reference this bean.
outboundTopicName
Specifies the name of the topic in the third-party JMS provider, into which messages are pushed.
localTopicName
Specifies the local topic name (in the ActiveMQ broker), from which messages are consumed. If not specified, defaults to the same value as outboundTopicName.
selector
Optionally, specifies a JMS selector string.
Back to top
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. Explore our recent updates.

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.

Theme

© 2025 Red Hat