Configuring and Managing JMS Bridge Services

Because the JMS specification does not dictate the communication protocol between brokers and clients, each JMS provider (including Message Queue) has defined and uses its own propriety protocol. This situation has led to non-interoperability across JMS providers.

The JMS bridge service in Message Queue 4.4 closes this gap by enabling a Message Queue broker to map its destinations to destinations in external JMS providers. This mapping effectively allows the Message Queue broker to communicate with clients of the external JMS provider.

The JMS bridge service supports mapping destinations to external JMS providers that:

• Are JMS 1.1 compliant

• Support JNDI administrative objects

• Use connection factories of type javax.jms.ConnectionFactory or javax.jms.XAConnectionFactory

• Support the XA interfaces as a resource manager for transacted mapping

As an administrative and management convenience, the JMS bridge service supports the creation of any number of JMS bridges in a broker. Each JMS bridge in the broker is identified by a unique name, has its own configuration, and is managed separately from other JMS bridges in the broker.

The following subsections provide information about JMS bridges and how to configure and manage them:

• JMS Bridge Components

• JMS Bridge Features

• Message Processing Sequence Across a Link in a JMS Bridge

• Configuring a JMS Bridge

• Starting and Stopping JMS Bridges

• Starting and Stopping Links in a JMS Bridge

JMS Bridge Components

A JMS bridge consists of two primary components:

• One or more links, each of which maps between a destination in the Message Queue broker and a destination in an external JMS provider or in another Message Queue broker

• A default Dead Message Queue (DMQ) where undeliverable messages are sent. Additional, special-purpose DMQs can also be specified.

To provide destination mapping, each link consists of:

• A source: the destination from which the JMS bridge receives messages. The source consists of a connection factory for creating connections to a JMS provider and a destination in that provider.

• A target: the destination to which the JMS bridge forwards messages received from the source. The target consists of a connection factory for creating connections to a JMS provider and a destination in that provider. Additionally, a target can optionally specify a message transformer that alters messages from the source before forwarding them to the target destination.

Links are unidirectional. Links that have an external JMS provider or another Message Queue broker as their source are called inbound links, and links that have the Message Queue broker as their source are called outbound links.

To configure these components, you specify several imq.bridge.bridgeName broker properties, and you create an XML configuration file that specifies the links, sources, targets, connection factories, destinations, and DMQs in the bridge. This XML configuration file must conform to the JMS bridge DTD.

JMS Bridge Features

To provide flexible, high-performing message transfer between mapped destinations, a JMS bridge offers these features:

• Pooled, Shared, and Dedicated Connections

• Transactional Message Transfer

• JMS Bridges in High Availability (HA) Broker Clusters

• Message Transformation During Message Delivery

• JMSReplyTo Header Processing

• Dead Message Queue (DMQ) Processing

Pooled, Shared, and Dedicated Connections

A JMS bridge uses the connection factories configured for link sources, link targets, and DMQs to create connections to the Message Queue broker and the external JMS provider. When making connections, the JMS bridge follows these rules to determine whether to use a pooled connection, a shared connection, or a dedicated connection:

• For link source connections, the JMS bridge always uses a dedicated connection.

• For link target and DMQ connections, the JMS bridge uses:

  • A pooled connection if the link target's or DMQ's stay-connected attribute is false and the connection factory has no JMS client identifier configured.

  • A dedicated connection if the link target's or DMQ's stay-connected attribute is true or if the link target's or DMQ's clientid attribute is set

  • A shared connection in all other cases

Transactional Message Transfer

Each JMS bridge includes a built-in XA transaction coordinator that enables its links to be configured as "transacted" such that message transfer from the source to the target is done in a XA distributed transaction.

For a link to be configured as transacted, both the link source and link target must specify connection factories of type javax.jms.XAConnectionFactory.

The built-in XA transaction coordinator logs transaction records using the same type of store as the Message Queue broker in which the JMS bridge resides. For file-based transaction logging, the transaction log for a JMS bridge is located at:

IMQ_VARHOME/instances/brokerInstance/bridges/bridgeName/txlog.bridgeNane

For JDBC-based transaction logging, the built-in XA transaction coordinator uses the same JDBC store as the Message Queue broker in which the JMS bridge resides.

Resource Manager Registration and The Built-In XA Transaction Coordinator

When a JMS bridge is started, it registers all its Resource Managers (RMs) with the built-in XA transaction coordinator so that the coordinator can identify specific RMs during recovery.

For connection factories, the JMS bridge only registers the factory as an RM if the factory's multi-rm attribute value is false. A connection factory with a multi-rm attribute value of true should have each of its RMs identified by a connection factory whose multi-rmattribute value of false in order to participate in transactional message transfer. Additionally, the JMS bridge uses a connection factory's ref-name attribute value as part of its RM name when registering RMs with the built-in XA transaction coordinator, so this attribute should not be changed between restarts of the bridge if transaction recovery is desired between restarts.

JMS Bridges in High Availability (HA) Broker Clusters

Message Queue supports JMS bridges in HA broker clusters, but some special constraints apply due to the inherent nature of HA broker clusters:

• Each JMS bridge must have a name that is unique across all the JMS bridges in all the brokers in the cluster.

• Each JMS bridge must have the same bridge configuration across all the brokers in the cluster.

• The imq.bridge.enabled broker property must have the same value across all brokers in the cluster.

• Before broker startup, the imq.bridge.activelist broker property for each broker lists only those JMS bridges that are to be owned by that broker.

To ensure that bridges in the cluster have the same configuration across all brokers in the cluster, all bridge-related broker properties except for imq.bridge.activelist should be specified in the centralized cluster properties file defined by the imq.cluster.url broker property.

A table in the cluster's HA store is used to maintain a consistent record of JMS bridge ownership by the brokers in the cluster.

During broker startup, the JMS bridge service compares the broker's imq.bridge.activelist property value to this table's entries before starting any JMS bridges, with the following consequences:

• If a JMS bridge named in imq.bridge.activelist does not appear in the table, it is added to the table and associated with the broker.

• If a JMS bridge name in imq.bridge.activelist does appear in the table, and the table entry already associates the bridge with a different broker, the bridge name is removed from imq.bridge.activelist.

• If an entry in the table associates a JMS bridge with the broker, and that bridge's name is not in imq.bridge.activelist, the bridge name is added to imq.bridge.activelist.

Message Transformation During Message Delivery

A link target or a DMQ can specify a message transformer to process the message before it is delivered to the target destination or DMQ destination. This message transformer must be a Java class that extends the Message Queue bridge com.sun.messaging.bridge.service.MessageTransformer abstract class and has javax.jms.Message as its formal type parameters. To specify a message transformer, set the message-transformer-class attribute of a link target or a DMQ to the fully qualified class name of the Java class.

During message transfer processing, the JMS message to be transferred to a target, plus any property subelements of the link's target element or the dmq element, are passed to the message transformer's MessageTransformer.transform() method, and the returned JMS message is sent to the target destination.

JMSReplyTo Header Processing

In a JMS message, the JMSReplyTo header value is provider dependent. Therefore, unless both the source provider and target provider are Message Queue, the JMS bridge sets an existing JMSReplyTo header to a null value before passing the message to a link target or, if specified, the message transformer for the link target.

This default behavior can be overridden by setting the retain-replyto attribute of the link's target element to true. Overriding the default behavior is useful when:

• The message transformer for a link target handles processing of the JMSReplyTo header.

• Both the link source and link target have the same JMS provider, and clients of the target provider instance need to send reply messages back across the JMS bridge to the JMSReplyTo destination in the source provider instance. To successfully implement this case:

  • The JMSReplyTo destination must exist (or be able to be auto-created) in the target provider instance.

  • A JMS bridge link must be defined with its source set to the JMSReplyTo destination in the target provider instance and its target set to the JMSReplyTo destination in the source provider instance.

Dead Message Queue (DMQ) Processing

Each JMS bridge includes a built-in Dead Message Queue (DMQ) named built-in-dmq. This DMQ is a designated Queue destination named imq.bridge.jms.dmq in the broker hosting the JMS bridge. You can also configure additional DMQs for the JMS bridge, in which case the DMQ can use any JMS destination in any configured JMS provider.

In a production environment, the built-in DMQ, imq.bridge.jms.dmq, should be administratively created and have its access controls set appropriately before starting a broker that uses JMS bridge services.

When a DMQ uses Message Queue as the JMS provider, it can be configured such that messages sent to it will automatically be transferred to the Message Queue broker's DMQ. To do so, set physical destination properties of the JMS bridge's DMQ as follows:

useDMQ=true
limitBehavior=REMOVE_OLDEST
maxNumMsgs=0

When a message is sent to the DMQ, the JMS bridge follows this sequence with the built-in DMQ first:

1. The bridge creates a new DMQ javax.jms.ObjectMessage object and sets the properties listed in Table 12–1 to the ObjectMessage.

2. If the DMQ has defined a message transformer, the original message is passed to the transformer's MessageTransformer.transform() method.

3. The body of the javax.jms.ObjectMessage is set to the transformed message (or original message if no message transformer is defined). If this action fails (usually because the message is not serializable), the body of the ObjectMessage is instead set to the toString() value of the original message.

4. The javax.jms.ObjectMessage is sent (up to send-attempts times) to the DMQ's destination with a timeToLive value based on the DMQ's time-to-live-in-millis attribute and with the same JMSDeliveryMode and JMSPriority as the original message.

5. If sending the message fails, the bridge repeats Steps 2 through 4 for each DMQ defined in the bridge's XML configuration file in the order they appear in the file, stopping when a send attempt succeeds, unless it is the built-in DMQ.

6. If the message can't be sent to any DMQ, a log message is generated, containing the properties and headers of the original message and the properties set in Step 1.

Message Processing Sequence Across a Link in a JMS Bridge

A JMS bridge link receives messages in the order sent by the link's source JMS provider and transfer them in the same order to the link's target JMS provider. A link follows this sequence to transfer each message:

1. The link receives a JMS message from its source.

2. The link checks the JMSExpiration header to determine whether the message has expired. If it has, a log message is generated, the JMS message is sent to the DMQ, and no further action is taken.

3. If the message has a JMSReplyTo header and the link target's retain-replyto attribute is false, the JMSReplyTo header value is set to null.

4. If the link target has defined a message transformer, the transformer's MessageTransformer.transform() method is called. If the call fails or if the message transformer returns a null value, a log message is generated and then processing continues as follows:

   • In Message Queue 4.4, the untransformed message is sent to the DMQ and processing continues on the untransformed message.

   • In Message Queue 4.4 Update 1, if the target's consume-no-transfer-on-transform-error XML attribute is true, the untransformed message is sent to the DMQ, consumed from the source, but not sent to the target.

   • In Message Queue 4.4 Update 1, if the target's consume-no-transfer-on-transform-error XML attribute is false, the link is stopped and the message is neither consumed from the source nor sent to the target.

5. Beginning with Message Queue 4.4 Update 1, if the message-transfer-tag-bridge-name attribute of the jmsbridge element is true, the JMS_SUN_JMSBRIDGE_NAME property is added to the message and set to the name of the bridge.

6. The message is sent to the link target's destination with a timeToLive value based on the JMSExpiration header and current GMT time and with the same JMSDeliveryMode and JMSPriority values as the original message. If sending to the link target's destination fails and the link is not transacted, a log message is generated, the JMS message is sent to the DMQ, and processing continues.

7. The source message is acknowledged using JMS CLIENT_ACKNOWLEDGE if the link is not transacted. If the acknowledgement fails, a log message is generated and the JMS message is sent to the DMQ.

8. Beginning in Message Queue 4.4 Update 1, if the message processing was successful, an INFO log message is generated.

Message processing for messages across transacted links follows the same processing sequence, except JTA interfaces are used to coordinate the source and target resource managers to transfer the message in an XA distributed transaction. For transacted links, failure to send the message to the link target's destination does not cause the JMS message to be sent to the DMQ; instead, the transaction is rolled back. However, if the attempt to commit the transaction fails, a log message is generated and the JMS message is sent to the DMQ.

The quality of message transfer under failures depends on whether the link transferring the message is transacted:

• Transacted links: once-only-once

• Non-transacted links: at-least-once

Configuring a JMS Bridge

To configure a JMS bridge, you specify several imq.bridge.bridgeName broker properties, where bridgeName is a name you choose for the JMS bridge. Additionally, you create an XML configuration file that specifies the links, sources, targets, connection factories, destinations, and DMQs in the bridge. The url of this configuration file is provided as the value of the imq.bridge.bridgeName.xml property

Specifying the Broker Properties for a JMS Bridge

Table 12–2 lists the broker properties you can specify for a JMS bridge. In this table, name is the name of the JMS bridge, which must be unique across all bridges in the broker.

Creating the XML Configuration File for a JMS Bridge

As mentioned earlier, the XML configuration file for a JMS bridge specifies the following components of the bridge:

• Links

• Sources

• Targets

• Connection factories

• Destinations

• DMQs

The configuration file must conform to the JMS bridge DTD, which is stored at:

IMQ_HOME/lib/dtd/sun_jmsbridge_Version.dtd

The basic structure of configuration file is:

<jmsbridge name=bridgeName otherAttributes>
    <link name=linkName otherAttributes>
        [ <description>linkDescription</description> ]
        <source connection-factory-ref=connFactoryRef destination-ref=destRef otherAttributes>
            [ <description>sourceDescription</description>
        </source>
        <target connection-factory-ref=connFactoryRef destination-ref=destRef otherAttributes>
            [ <description>targetDescription</description> ]
            [ <property name=propName value=propValue /> ] ...
        </target>
    </link> 
    <dmq name=dmqName otherAttributes> /* use name="built-in-dmq" for the built-in DMQ */
        [ <description>dmqDescription</description> ]
        [ <property name=propName value=propValue /> ] ...
    </dmq> 
    <connection-factory ref-name=connFactoryRef otherAttributes>
        [ <description>connFactoryDescription</description> ]
        [ <property name=propName value=propValue /> ] ...
    </connection-factory> 
    <destination ref-name=destRef otherAttributes>
        [ <description>destDescription</description> ]
        [ <property name=propName value=propValue /> ] ...
    </destination> ...
</jmsbridge>

From this abbreviated structure for the bridge XML configuration file, note that source and target are subelements of link, while connection-factory and destination are peer elements to link, not subelements of source and target. Connection factories and destinations are associated with sources and targets by matching connection-factory ref-name and destination ref-name attributes values to source and target connection-factory-ref and destination-ref attribute values, respectively.

As a result of this association by name-matching instead of by subelement inclusion, you can use the same connection factories and destinations across sources and targets in multiple links, thus streamlining the configuration file and making it more manageable.

The following subsections describe the attributes you can specify for the elements in the JMS bridge XML configuration file.

jmsbridge Attributes

Table 12–3 lists the attributes for the jmsbridge element in the JMS Bridge XML configuration file.

link Attributes

Table 12–4 lists the attributes for the link element in the JMS Bridge XML configuration file.

source Attributes

Table 12–5 lists the attributes for the source element in the JMS Bridge XML configuration file.

target Attributes

Table 12–6 lists the attributes for the target element in the JMS Bridge XML configuration file.

dmq Attributes

Table 12–7 lists the attributes for the dmq element in the JMS Bridge XML configuration file.

connection-factory Attributes

Table 12–8 lists the attributes for the connection-factory element in the JMS Bridge XML configuration file.

destination Attributes

Table 12–9 lists the attributes for the destination element in the JMS Bridge XML configuration file.

Starting and Stopping JMS Bridges

JMS bridges can be started automatically when the broker hosting the bridge starts, or manually using the imqbridgemgr utility. Similarly, JMS bridges are stopped automatically when the broker hosting the bridge is shut down, or manually using the imqbridgemgr utility.

When a JMS bridge is started, the JMS bridge manager performs these tasks:

1. Parse and validate the bridge's XML configuration file.

2. Initialize all links and DMQs that have their enabled attribute set to true.

3. If any enabled links have their transacted attribute set to true:

   1. Initialize the built-in XA transaction coordinator.

   2. Register resource managers (RMs) for all potential XA connection factories.

   3. Perform XA recovery for available RMs.

4. Create connection pools and shared connections as needed.

5. Ensure that all DMQs are ready.

6. Start all enabled links.

When a JMS bridge is stopped, the JMS bridge manager performs these tasks:

1. Stop all started and paused links.

2. Wait until all pooled connections are returned to their respective pools and until all references to shared connections are returned.

3. Close all connection pools and shared connections. This effectively causes all physical connections to JMS providers to close.

To Configure a JMS Bridge to Start at Broker Startup

Follow these steps to configure a JMS bridge so that it starts automatically when the broker hosting it is started.

1. Confirm that the bridge service manager is enabled.

   See To Enable the Bridge Service Manager for instructions.

2. Add the name of the bridge to the imq.bridge.activelist broker property.

3. Confirm that the imq.bridge.bridgeName.autostart broker property is set to true.

To Start a JMS Bridge Manually

1. Enter the imqbridgemgr start bridge command, specifying the bridge name and the broker.

   For example, to start the bridge mq2external hosted by the broker running on myhost:8886, enter this command:

   imqbridgemgr start bridge -bn mq2external -b myhost:8886

To Stop a JMS Bridge Manually

1. Enter the imqbridgemgr stop bridge command, specifying the bridge name and the broker.

   For example, to stop the bridge mq2external hosted by the broker running on myhost:8886, enter this command:

   imqbridgemgr stop bridge -bn mq2external -b myhost:8886

Starting and Stopping Links in a JMS Bridge

Links in a JMS bridge are started automatically when the bridge starts. Similarly, links are stopped automatically when the bridge is stopped. Additionally, once a JMS bridge is started, any of its links can be paused, resumed, stopped or restarted manually using the imqbridgemgr utility.

To Stop a Link Manually

1. Enter the imqbridgemgr stop link command, specifying the link name, the bridge name, and the broker.

   For example, to stop the link link1 in the bridge mq2external hosted by the broker running on myhost:8886, enter this command:

   imqbridgemgr stop link -ln link1 -bn mq2external -b myhost:8886

To Start a Link Manually

A link cannot be started manually unless it is enabled; that is, the enabled attribute of its link element in the bridge's XML configuration file is set to true.

1. Enter the imqbridgemgr start link command, specifying the link name, the bridge name, and the broker.

   For example, to start the link link1 in the bridge mq2external hosted by the broker running on myhost:8886, enter this command:

   imqbridgemgr start link -ln link1 -bn mq2external -b myhost:8886