Functional Specification

1.0 Author/Date:

Amy Kang 12/15/2008 Initial Draft and Updates
Isa & Amy 01/16/2009 updated imqbridgemgr syntax & use cases

2.0 Synopsis:

JMS Bridge and WebSphere MQ Integration

4.1 Overview
4.2 MQ JMS Bridge Features
5.0 Non-feature
6.0 Dependencies
7.0 Interfaces
9.0 Configuration/Administration
12.0 Security 14.0 Installation/packaging 15.0 Use Cases
3.0 PRD Requirement#:
This feature has been required by previous PRD and requested from mq-interest and OpenMQ user alias as well as from MQ forum.

4.0 Description:

MQ JMS Bridge Components
MQ JMS Bridge Connection Management
MQ JMS Bridge Built-in XA Transaction Coordinator
JMS Bridge Running a HA Cluster
MQ JMS Bridge States and State Transitions
MQ JMS Bridge Link States and State Transitions
MQ JMS Bridge Start and Stop
MQ JMS Bridge Message Transfer
MQ JMS Bridge DMQ
MQ JMS Bridge Link
MQ JMS Bridge Message Transformer
JMSReplyTo
MQ JMS Bridge DTD

Overview

A JMS bridge maps destination(s) in MQ to destination(s) in a forein JMS provider, like WebSphere MQ, or in another MQ instance or cluster. The main usage of a JMS bridge can be:

  • Connecting MQ to WebSphere MQ or other foreign JMS providers
  • Bridging geographically dispersed MQ clusters or broker instances over low bandwidth network
  • Bridging a MQ HA-cluster to a MQ non-HA cluster or a standalone MQ broker
  • Can be used by MQ as a way of achieving remote destination store & forwarding

A MQ JMS bridge runs embeded inside a MQ broker by using the MQ Pluggable Bridge Service Framework.

  • Multiple JMS bridges (each can have 0 or more links) can be enabled and run at in parallel in a MQ broker instance.
  • A link in a MQ JMS bridge can be configured to run in either non-transacted mode or XA transacted mode.
  • MQ JMS bridge implements built-in XA transaction coordinator which facilitates XA transaction completion and recovery;
  • MQ JMS bridge provides pluggable interface to allow an external JTA transaction manager to be used to drive XA transactions
    [not officially supported]
  • A link target in a MQ JMS bridge can can be configured in disconnected mode
    so that only when a message comes from the source will a connection to the target be made.
  • MQ JMS bridge implements connection pooling as well as shared connection.
  • MQ JMS bridge handles connection exceptions and auto-reconnect
  • Undeliverable indoubt messages are sent to the bridge's DMQ(s).
    A MQ JMS bridge has a built-in DMQ as well as 0 or more additional DMQs that can be configured.
  • The MQ JMS bridge implements transaction log to facilitate XA recovery for the built-in XA transaction coordinator
    [supports both file and jdbc-based transaction log]

MQ JMS Bridge Components

  • jmsbridge
    A jmsbridge is composed by 0 or more links and 1 or more of DMQs
  • link
    A link specifies a mapping of a destination in one JMS provider to a destination in another, or the same, JMS provider. A link is uni-directional. A link has a source and a target. A link can be disabled or enabled. A enabled link can be started, paused, resumed, stopped.
  • source
    A source is one end of a link that specifies the source JMS provider and the source destination. Messages received by the jmsbridge from the source are forwarded to the target of the link. A source has a destination and a connection factory.
  • target
    A target is the other end of the link that specifies the target JMS provider and the target destination. A target has a destination and connection factory. A target can optionally specify a message transformer to transform a JMS message from the source to a new JMS message.
  • dmq
    A dmq, Dead Message Queue, specifies a JMS provider and a JMS destination where undeliverable indoubt messages can be sent to. It has a destination and a connection factory.
  • connection factory
    A connection factory is used to create connections to a JMS provider. Connection factories must be a JMS 1.1 either javax.jms.ConnectionFactory or javax.jms.XAConnectionFactory type.
  • destination
    A destination represents a JMS provider-specific address where messages can be sent to or received from.

Links and DMQs in a jmsbridge is configured by a XML document file which is validated against the MQ JMS Bridge XML Document DTD. The following is an example of MQ JMS bridge for bridging MQ and Web Sphere MQ.

MQ JMS Bridge Connection Management

The JMS bridge uses connection factories to create connections to the underlining JMS providers. A source in a link needs a connection to the source JMS provider in order to receive messages from it for transfering to the target in the link. A target in a link needs a connection to the target JMS provider in order to send the message that received from the source. Connection factories are created from JNDI lookup except default connection factories which create connections to the MQ broker that the JMS bridge is running in.

There are 3 types of connections in a MQ JMS bridge,

Pooled Connection
Shared Connection
Dedicated Connection

Pooled Connection
MQ JMS bridge implements connection pooling for,
  • connection reuse
    Physical connections to JMS providers can be expensive to create and destroy.
  • idle connection timeout

Connection pools are partitioned per connection factory object and are created automatically on demand.

A practical example of using pooled connection is a jmsbridge that has many links to a target JMS provider and each link has relatively low message flow rate. To avoid too many simutaneous connections to the target JMS provider, the target in each link can be configured to have stay-connected false. When a message comes in from the source of the link, the link gets a pooled connection from the MQ JMS Bridge's pooled connection factory and use it to send the message to the target and then returns the pooled connection back to the pool. A connection factory can be configured with idle-timeout-in-seconds to be used when the connection factory is used for pooled connections.

Pooled connection will be used for a target in a link or for a dmq if

  • The connection factory has no JMS client identifier configured
  • The target or dmq stay-connected attribute is set to false

Shared Connection
A shared connection will be used by targets in multiple links or dmqs concurrently if they are configured to use the same connection factory and the connection factory has JMS client identifier configured.

Dedicated Connection
Dedicated connection is dedicated to a source or a target or a dmq. A source connection in a link is always dedicated. A target in a link will use dedicated connection if the target has attribute stay-connected set to true or has attribute clientid set.

MQ JMS Bridge Built-in XA Transaction Coordinator

A link in a JMS bridge can be configured to be transacted or non-transacted. When a link is transacted, message transfer from the source to the target is done in a XA distributed transaction.

MQ JMS bridge implements a built-in XA transaction coordinator. The built-in XA transaction coordinator uses JTA standard interfaces to coordinate XA transaction completion between the source XA resoure manager and the target XA resource manager in each link and does XA recovery for XA resources in a JMS bridge. Each JMS bridge has its own built-in XA transaction coordinator instance.

XA Recovery and RM Registration

  • Coordinator Transaction Log

    MQ JMS Bridge built-in XA transaction coordinator uses transaction log to facilitate XA recovery and implements both file-based and jdbc-based transaction log, and uses the same persist type (file or jdbc) as the in-process MQ broker uses. When file-based, transaction log for a JMS bridge is created as

    <broker-instance>/bridges/<bridge-name>/txlog.<bridge-name>

  • RM Registration

    At start of a MQ JMS bridge, all RMs of the JMS bridge are registered with its built-in XA coordinator instance. The built-in XA coordinator uses RM registration for two purposes:

    • part of branch XID generation
    • identify a RM during recovery

    A RM is registered for each XA connection-factory that has attribute multi-rm false using the connection-factory element's ref-name as RM name combined with its XAResource class name (obtained at runtime). Therefore the ref-name for a XA connection-factory element in a jmsbridge XML document file should not be changed if recovery is expected between restarts.

    A XA connection-factory that potentially creates connections to more than one RM (ie. XAResoure.isSame() false among them) at runtime should have its attribute multi-rm set to true

    Each RM that will participate in the message-transfer XA transactions in a JMS bridge must have a corresponding XA connection-factory element whose attribute multi-rm is false in the JMS bridge's XML document.

JDBC-based Transaction Log

When a broker that the JMS bridge embeded in is using JDBC store, the JMS bridge's built-in XA transaction coordinator will store its transaction log in the same database as the broker's JDBC store uses. Please see JMS Bridge Table Schema for additional information.

A JMS bridge can run in a HA-broker. When running in a HA-broker, all JMS bridges configured for brokers in the HA-cluster must have unique bridge names. In 4.4 when the broker that a JMS bridge is embeded in is taken over by another broker, the JMS bridge can be restarted when the failed broker restarts. Automatic failover of a JMS bridge to the taken over broker will be supported in future release.

JMS Bridge Running in a HA Cluster

All JMS bridges configured for a broker that will be running in a HA cluster must have cluster-wide unqiue names. A JMS bridge is owned by only 1 broker

imq.bridge.enabled must have the same value in all brokers in a HA-cluster. Therefore it should be placed in the centralized cluster properties file pointed by imq.cluster.url

Each JMS bridge must have the same bridge configuration, for examples,

imq.bridge.<bridge-name>.type
imq.bridge.<bridge-name>.xmlurl

must be same for all brokers in the HA-cluster for a specific bridge-name. Therefore they should be placed in the centralized cluster properties file.

For a HA-broker, imq.bridge.activelist is used to specify a JMS bridge's initial broker ownership (versus ownership after takeover).

JMS bridge names specified in imq.bridge.activelist and JMS bridge names owned by this broker in the HA store JMS bridge names table will sync-up during the bridge service manager initialization as part of broker startup, specifically, JMS bridge names that are in imq.bridge.activelist but not owned by this broker in HA store will attempt to be added into the HA store and if another broker owns the JMS bridge name, it will be removed from imq.bridge.activelist; JMS bridge names that are owned by this broker in the HA store but not in imq.bridge.activelist will be added to imq.bridge.activelist

imqdbmgr

HA cluster backup/restore that is provided by imqdbmgr backup and imqdbmgr restore will also backup and restore the JMS bridge related tables (JMS bridge names table, and JMS bridge transaction coordinators transaction log records)

imqdbmgr remove jmsbridge -n <bridge-name> is added to allow to remove a JMS bridge that is owned by this broker from its HA store. To run this command, first shutdown the broker with -nofailover using imqcmd if the broker is running.

JMS Bridge States and State Transition

A configured JMS bridge is started either at broker startup or on demand by imqbridgemgr. A configured JMS bridge can be started, stopped, paused or resumed by imqbridgemgr and is automatically stopped when broker shuts down.
JMS Bridge States and State Transitions


STOPPED

s1

STARTED

s2

PAUSED

s3

start

s2

[no-op]

s2

pause

[error]

s3

[no-op]

resume

[error]

[no-op]

s2

stop

[no-op]

s1

s1

The Bridge Service Manager, part of the Pluggable Bridge Service Framework, in the broker manages all bridges running in the broker instance. It provides management functionalities, pause/resume, stop/start a bridge. imqbridgemgr is a Java utility program that provides a command line interface for the Bridge Service Manager.

JMS Bridge Link States and State Transition

Link States and State Transitions


UNINITIALIZED

s0

STOPPED

s1

STARTING

s2

STARTED

s3

PAUSING

s4

PAUSED

s5

STOPPING

s6

start

-->s1-->s2-->s3

-->s2-->s3

[no-op]

[no-op]

-->s5-->s2-->s3

-->s2-->s3

-->s1-->s2-->s3

pause

[error]

[error]

-->s3-->s4-->s5

-->s4-->s5

[no-op]

[no-op]

[error]

resume

[error]

[error]

[no-op]

[no-op]

-->s5-->s2-->s3

-->s2-->s3

[error]

stop

[error]

[no-op]

-->s3-->s6-->s1

-->s6-->s1

-->s5-->s6-->s1

-->s6-->s1

[no-op]

JMS Bridge Start and Stop

When a JMS bridge is started either on broker startup or on demand by imqbridgemgr,

  1. It parses and validates the bridge configuration XML document file configured for the JMS bridge
  2. All dmqs and all links are initialized and consistency checked
  3. If any transacted link is enabled,
    1. The built-in XA transaction coordinator is initialized
    2. The JMS bridge registers resource managers for all potential XA connection factories
    3. The built-in XA transaction coordinator does XA recovery for the available resource managers
  4. Connection pools and shared connections are created on demand
  5. All dmqs are ready
  6. All links are started

When a JMS bridge is stopped either due to the broker shuts down or on demand by imqbridgemgr, first all links are closed (source is closed first) and then wait all pooled connections returned to their respective pools, all references to shared connections returned, connection pools and shared connections are closed which causes all physical connections to JMS providers to close.

JMS Bridge Message Transfer

The MQ JMS bridge receives messages in the order sent by the source JMS provider and transfers the messages in the same order to the target JMS provider.

Non-transacted JMS messsage transfer uses JMS CLIENT_ACKNOWLEDGE on the source side,

  1. A link receives a JMS message from its source;
  2. Check the JMSExpiration header to see if the received message has expired
    If yes, log a message and send to DMQ(s), then no further action for the message
  3. If the message's JMSReplyto header presents, and if the target's retain-replyto attribute is false
    set message's JMSReplyTo header null
  4. If the target attribute message-transformer-class set
    The message is passed to the class that extends the MQ Bridge MessageTransfer class.
  5. The message is sent to the target with calculated timeToLive based on the JMSExpiration header and current GMT, and with the same JMSDeliveryMode and JMSPriority as in the original message.
  6. The source message is acknowledged

XA-transacted JMS messsage transfer follows similar sequence except it uses JTA interfaces to coordinate the source and target resource managers to transfer each message in a XA distributed transaction.

The quality of message transfer under failures for non-transacted link is at-least-once and for transacted link is once-only-once.

MQ JMS Bridge DMQ

MQ JMS Bridge DMQ Message Properties
The jmsbridge dmq Attributes

A jmsbridge always has a built-in dmq, and can have 0 or more additional dmq configured. The builtin dmq is a designated Queue in the broker that the jmsbridge is running in. A non-builtin dmq in a jmsbridge can be configured to have any JMS destination to any supported JMS provider. An undeliverable indoubt message is sent to the built-in dmq first, if that fails, it tries the other dmq(s) in the order it appears in the jmsbridge configuration XML document file until a send is successful or the dmq list exhausted. A delivery to a dmq fails if send-attempts exhausted

Before an undeliverable indoubt message is sent to a dmq, it's first logged, then the following MQ JMS Bridge DMQ Message Properties are set to a newly created DMQ ObjectMessage. Then if the message-transformer-class is specified for the dmq, the original message is passed to the MessageTransformer.transform(), then the returned message object is set to the body of the DMQ ObjectMessage; if no message-transformer-class is specified for the dmq, the original message is set to the body of the DMQ ObjectMessage; if that fails (e.g. message is unserializable), the original message's toString() is set to the body of the DMQ ObjectMessage. The DMQ ObjectMessage is then sent to the dmq with the time-to-live-in-millis as specified for the dmq, the same JMSDeliveryMode and the same JMSPriority as in the original message.

If the original message is not serializable, message-transform-class should be specified for the dmq to transform the message to a serilizable object, otherwise only the original message's headers and properties are transferred to the dmq message. When an undeliverable indoubt message is unable to be sent to any dmq, details (properties, headers) about the original message will be logged along with the MQ JMS Bridge DMQ Message Properties.

When a dmq is configured to use MQ, the MQ administrator can optionally configure the destination of the dmq so that the messages sent to the destination will be automatically transferred to the MQ broker's DMQ by setting the destination attributes

useDMQ=true
limitBehavior=REMOVE_OLDEST
maxNumMsgs=0

In a MQ JMS bridge XML configuration document, the dmq element can have a number of dmq attributes specified. To configure the built-in dmq, use dmq name "built-in-dmq". These attributes for the built-in dmq are ignored: enabled, connection-factory-ref, destination-ref, stay-connected.

A message is sent to DMQ on the following message transfer failures:

Transacted Link

Non-Transacted Link

Comments

message expired

message expired

The message expired before sending to the target

N/A

send failure

For transacted link, the transaction will be rolled back

N/A

ack failure

The message acknowledgement to source is failed after sent to target

message transformer failure

message transformer failure

MessageTransforer.transform(message) is failed when message-transfer-class is configured for the target. The non-transformed original message will be sent to the target

commit failure

N/A

MQ JMS Bridge DMQ Message Properties

Property Name

Type

Comments

JMS_SUN_JMSBRIDGE_SOURCE_MESSAGEID

String

orginal message's getJMSMessageID(), null if not available

JMS_SUN_JMSBRIDGE_SOURCE_TIMESTAMP

long

original message's getJMSTimestamp()

JMS_SUN_JMSBRIDGE_SOURCE_CORRELATIONID

String

original message's getJMSCorrelationID()

JMS_SUN_JMSBRIDGE_SOURCE_JMSTYPE

String

original message's getJMSType()

JMS_SUN_JMSBRIDGE_SOURCE_DESTINATION

String

The original message's source destination name

JMS_SUN_JMSBRIDGE_TARGET_DESTINATION

String

The name of the target destination where the original message was intended to send to

JMS_SUN_JMSBRIDGE_SOURCE_PROVIDER

String

The ConnectionMetaData.getJMSProviderName of the connection the original message was received on, if not available, the source connection factory's getClass().getName()

JMS_SUN_JMSBRIDGE_TARGET_PROVIDER

String

The ConnectionMetaData.getJMSProviderName of the connection the original message was intended to send on, if not available, the target connection factory's getClass().getName()

JMS_SUN_JMSBRIDGE_DMQ_REASON

String

one of MESSAGE_EXPIRED, SEND_FAILURE, ACK_FAILURE, MESSAGE_TRANSFORM_FAILURE, COMMIT_FAILURE

JMS_SUN_JMSBRIDGE_DMQ_EXCEPTION

String

The Exception.getMessage() if exception occurred or detailed comments on the failure; null if none

JMS_SUN_JMSBRIDGE_DMQ_TIMESTAMP

String

The timestamp when the JMS bridge sends the message to the DMQ

JMS_SUN_JMSBRIDGE_DMQ_BODY_TRUNCATED

String

If unable to set the original message or the transformed (if the dmq's message-transform-class set) message to the body of the dmq ObjectMessage. In that case the message's toString() is set to the body of the dmq ObjectMessage

The jmsbridge dmq Attributes

Attribute Name

Type

Default

Comments

name

string

no default

unique identifier for this dmq

enabled

"true" or "false"

"true"

whether this dmq is enabled

connection-factory-ref

string

no default

a reference to a non-XA connection-factory element

destination-ref

string

no default

a reference to a destination element

stay-connected

"true" or "false"

"true"

if true, the dmq producer connection will stay connected and be dedicated

client-id

string

not default

JMS client identifier for the dmq producer connection. If set, the connection will be dedicated

time-to-live-in-millis

integer

"0"

Time-to-live in milliseconds (0 means forever) for messages going to this dmq

send-attempts

integer

"3"

The number of attempts in sending an undeliverable indoubt message to a dmq

send-attempt-interval-in-seconds

integer

"5"

how long to wait before next retry in sending an undeliverable indoubt to dmq

message-transformer-class

string

not set

A fully qualified class name that extends the MQ Bridge MessageTransformer class. When it's set, user can optionally specify any number of properties to be used by the MessageTransformer subclass throgh the property element in the dmq element; see MQ JMS Bridge Message Transformer

MQ JMS Bridge Link

link Attributes
source Attributes
target Attributes
connection-factory Attributes
destination Attributes

The following attributes can be specified for a jmsbridge link element.

The jmsbridge link Attributes

Attribute Name

Type

Default

Comments

name

string

no default

unique identifier for this link

enabled

"true" or "false"

"true"

if false, the link will not be started

transacted

"true" or "false"

"true"

If true, each message transfer from source to target will be done in a XA distributed transaction and the source and target connection-factory-ref must reference to a javax.jms.XAConnectionFactory object;

if false, CLIENT_ACKNOWLEDGE mode will be used on the source and the source and target connection-factory-ref must reference to a javax.jms.ConnectionFactory object

The following attributes can be specified for the source in a jmsbridge link element.

The jmsbridge source Attributes

Attribute Name

Type

Default

Comments

connection-factory-ref

string

no default

reference to a connection-factory element

destination-ref

string

no default

reference to a destination element

selector

string

not set

a JMS selector for the message consumer

durable-sub

string

not set

a JMS durable subscription name, ignored if destination-ref does not reference a javax.jms.Topic object

clientid

string

not set

a JMS client identifier for message consumer connection

The following attributes can be specified for the target in a jmsbridge link element.

The jmsbridge target Attributes

Attribute Name

Type

Default

Comments

connection-factory-ref

string

no default

reference to a connection-factory element

destination-ref

string

no default

reference to a destination element

stay-connected

"true" or "false"

"true"

if true, the message producer connection will stay connected, and be dedicated

stay-connected

"true" or "false"

"true"

if true, the message producer connection will stay connected, and be dedicated

clientid

string

not set

a JMS client identifier for message producer connection; if set, use dedicated connection

retain-replyto

"true" or "false"

"true" if MQ to MQ
"false" otherwise

whether retain JMSReplyTo header of source message, see JMSReplyTo

message-transformer-class

string

not set

A fully qualified class name that extends the MQ Bridge MessageTransformer class. When it's set, user can optionally specify any number of properties to be used by the MessageTransfer subclass throgh the property element in the target element; see MQ JMS Bridge Message Transformer

The following attributes can be specified for a jmsbridge connection-factory element.

The jmsbridge connection-factory Attributes

Attribute Name

Type

Default

Comments

ref-name

string

no default

reference name for this connection-factory element

multi-rm

"true" or "false"

false

ignored if javax.jms.ConnectionFactory type

set to true if this connection factory will potentially create XA connections to more than one XA resource managers (ie. XAResource.isSame() false among them) and add separate connection-factory for each those resource managers so that each of them will be registered separately to XA transaction coordiator

lookup-name

string

not set

JNDI lookup name. If specified, the JNDI environment properties must specified in the property elements of this connection-factory, and the object returned by the lookup must be either javax.jms.ConnectionFactory or javax.jms.XAConnectionFactory type; if not specified, a default connection factory to the MQ broker with the properties in the property elements will be created.

connect-attempts

integer

-1

The number of attempts for connecting, -1 means retry forever

connect-attempt-interval-in-seconds

integer

5

how long to wait before each connect attempt

idle-timeout-in-seconds

integer

1800

Close a connection if it is idle for more than this long. 0 means no idle timeout. This attribute will be ignored for a source and ignored if stay-connected is true for a target or a dmq

The following attributes can be specified for a jmsbridge destination element.

The jmsbridge destination Attributes

Attribute Name

Type

Default

Comments

ref-name

string

no default

reference name for this destination element

name

string

not set

The JMS destination name for this destination. ignored if lookup-name is specified

type

"queue" or "topic"

"queue"

JMS destination type. ignored if lookup-name is specified

lookup-name

string

not set

JNDI lookup name for the destination. If specified, the JNDI environment properties must specified in the property elements of the this destination element

MQ JMS Bridge MessageTransformer

A dmq or a target in a link can optionally specify a message-transformer-class attribute which is a fully qualified class name that extends the MQ Bridge MessageTransformer class, and can optionally specify any number of properties to be used by the MessageTransformer subclass throgh the property element in a dmq or target element. The properties will be passed to the MessageTransform.transform() method by the MQ JMS bridge runtime. For JMS bridge, the formal type parameters for a subclass of MessageTransformer must be javax.jms.Message type.

The MessageTranformer.transform() method will be called, for a target after processing retain-replyto attribute on the original message, and for both target and dmq before sending the message.

JMSReplyTo

The JMS message's JMSReplyTo header value is provider dependent. The MQ JMS bridge does not support automatic JMSReplyTo destination mapping. By default, if the original message that is received from a source has JMSReplyTo header set, the MQ JMS bridge will set it to null before passing the message to any message-tranformer-class or sending to a target JMS provider. The JMSReplyTo header handling can be customerized by a message-transformer-class with target attribute retain-replyto set to true so that the JMSReplyTo header will be retained when the message is passed to the MessageTransformer.transform() method.

If there is no message-transformer-class specified for a target or if specified message-tranfomer-class does not handle JMSReplyTo header, setting retain-replyto to true can potentially cause ClassCastException when the message is sent to a target JMS provider that is different from the message's source.

If both target and source has the same JMS provider, in order for the message recipient client of a target JMS provider instance to send a reply message back to the JMSReplyTo destination in the source provider instance over the JMS bridge, the JMSReplyTo destination must exist in the target JMS provider instance (or can be auto-created) and a jmsbridge link must set up in the jmsbridge XML document to link the JMSReplyTo destination in the target provider instance to the one in the source provider instance.

MQ JMS Bridge DTD

The configuration of a MQ JMS bridge is specified by a XML document that is validated against the MQ JMS bridge DTD (Document Type Definition) unpon read by a JMS bridge that is running in a MQ broker instance.

The MQ JMS bridge DTD file is named sun_jmsbridge_1_0.dtd and specifies the syntax of a MQ JMS bridge configuration XML document.

5.0 Non-feature:

  • Bridging 2 foreign JMS providers are not supported.
  • Bridging non-JMS providers are not supported.
  • JMS 1.0.2 providers are not supported
    Connection factories must be JMS 1.1 either javax.jms.ConnectionFactory or javax.jms.XAConnectionFactory type

MQ JMS bridge runs in HA-mode (be able to failover to the takeover broker) when running in a HA-clustered broker will be added in future release.

6.0 Dependencies:

  • JMS 1.1
  • Foreign JMS provider, such as IBM Web Sphere MQ
    • must be JMS 1.1 compliant
    • must support JNDI administrative objects
    • Connection factory must be either javax.jms.ConnectionFactory or javax.jms.XAConnectionFactory type
    • To use transacted link, must support the XA interfaces as a resource manager
  • JNDI and JNDI service provider(s) for lookup foreign JMS provider's or MQ's administrative objects
  • JTA intefaces for transacted links

7.0 Interfaces:

Exported Interfaces

Interface

Classification

Comments/Specification

sun_jmsbridge_1_0.dtd

Evolving

The MQ JMS bridge configuration xml document file DTD

imqbridgemgr

Evolving

The bridge service manager administration command line utility

MQ bridge service configuration
MQ JMS bridge service configuration

Evolving

broker properties for MQ bridge service and jms bridge service

com.sun.messaging.bridge.service.MessageTransformer

Evolving

The abstract class MessageTransformer that can be subclassed by MQ JMS bridge users to be used by MQ JMS bridge runtime to transform messages

Imported Interfaces

Interface

Classification

Comments/Specification

JMS 1.1

Standard

javax.jms

JTA 1.1

Standard

javax.transaction
javax.transaction.xa

8.0 Performance:

The MQ JMS bridge runs embeded in MQ broker which benefits performance.

The MQ JMS bridge implements connection pooling so that connections can be obtained from available connections of the same connectin factory instead of always create new.

The MQ JMS bridge is highly scalable. Multiple jmsbridge can run parallel in the same broker instance and each jmsbridge can have muliple links which only limited by the broker configured resources.

9.0 Configuration/Administration:

MQ Bridge Service Manager Configuration
MQ JMS Bridge Service Configuration
imqbridgemgr

Broker Properties for MQ Bridge Service Manager

Name

Default

Description

imq.bridge.enabled

false

Set true to enable broker to run embeded bridge service(s). When the broker is in HA-mode, this property is added to the match properties of the HA cluster

imq.bridge.activelist

not set

A list of comma separated bridge names that will be loaded on broker startup. All bridge names, regardless type, that are configured for a broker must be unique

imq.bridge.admin.user

not set

A MQ broker administrative user to be used by the bridge service manager and the JMS bridges to create ADMIN connections to the broker and to access the JMS bridge's built-in DMQ Queue destinantion imq.bridge.jms.dmq

imq.bridge.admin.password

not set

The password for the imq.bridge.admin.user. It's recommended to specify this property in a passfile through the "-passfile" option of imqbrokerd

Broker Properties for JMS Bridge Service

Name

Default

Description

imq.bridge.<name>.type

not set

Specifies the type (case insensitive) of the JMS bridge whos name is <name>. For JMS bridge, the type is jms or JMS

imq.bridge.<name>.xmlurl

not set

Specifies a URL that points to the jmsbridge, whos name is <name>, XML configuration document file.

imq.bridge.<name>.autostart

true

Specifies whether this bridge, whos name is <name>, should be auto-started on broker startup.

imq.bridge.tm.class (private)

com.sun.messaging.bridge.jms.tx.TransactionManagerImpl

Specifies the fully qualified class name that implements the MQ JMS bridge TransactionManagerAdapter interface

imq.bridge.tm.props

imq.bridge.<name>.tm.props

not set

Specifies a list of key=value separated by "," for the configured transaction manager (imq.bridge.tm.class).

If the same key specified in both properties, the value specified in imq.bridge.<name>.tm.props takes precedence.

For the MQ JMS bridge built-in transaction coordinator, the following property names are supported when the imq.persist.store=file:
txlogSize
txlogSync
txlogMmap

imqbridgemgr
[Isa, Amy]

imqbrokermgr is the command line interface for the MQ Bridge Service Manager. It has consistent syntax as imqcmd.

imqbridgemgr <subcommand> <argument> [<options>]
imqbridgemgr -h
imqbridgemgr -H
imqbridgemgr -v
imqbridgemgr -version

The valid "subcommand" are start, stop, resume, pause, list

The valid "argument" are bridge, link

The valid "options" are:

    -b                     : Specify the broker host and port (host:port).\n\
    -bn                    : Specify the bridge name.\n\
    -f                     : Perform action without user confirmation.\n\
    -h, -help       : Display usage help.\n\
    -H, -Help       : Display usage help, attribute list, and examples.\n\
    -javahome              : Specify an alternate Java 2 compatible runtime to use.\n\
                                    Default is to use the bundled runtime.\n\
    -ln                    : Specify the link name.\n\
    -passfile              : Specify a file containing the administrator password.\n\
    -rtm                   : Specify the receive timeout in seconds. Default is 10.\n\
    -rtr                   : Specify the number of retries. Default is 5.\n\
    -s                     : Silent mode. No output will be displayed.\n\
    -secure                : Use the SSL/TLS based admin service on the broker\n\
                                    (it needs to be enabled first).\n\
    -t                     : Specify the bridge type.\n\
    -u                     : Specify the administrator username.\n\
    -v, -version    : Display version info.\n
Please note that some bridge types (eg. stomp) does not support link argument.

Please see some examples in imqbridgemgr Use Cases

10.0 Instrumentation/Diagnostics:

imqbridgemgr provides "list" subcommand to show JMS brigde state and its links and link states.

The MQ JMS bridge implementation uses Java logging which can be configured by Java system property java.util.logging.config.file

JMX interfaces will be added for the MQ Bridge Service Manager and JMS bridges in future release.

11.0 Compatibility/Interoperability/Migration:

MQ JMS Bridge interoperates with JMS 1.1 conformant JMS providers. see Dependencies

MQ JMS bridge uses JTA standard interfaces to coordinate XA transactions between source and target resource managers for a transacted link. An external JTA transaction manager can be used instead of the built-in XA transaction coordinator, although this is not officially supported.

12.0 Security:

It's recommended to access control the MQ JMS Bridge's built-in DMQ destination imq.bridge.jms.dmq to only MQ broker administrators.

The security on connections to a JMS provider lies in the configuration that is set in each connection factory administrative object. Therefore administrators using MQ JMS bridge should configure sufficient security in the connection factory administrative objects that to be used by the jmsbridge, and configure sufficient security in the property element of the jmsbridge connection-factory element for lookup those objects

13.0 Standards Conformance:

JMS 1.1
JTA 1.1
JSE 5.0 or later

14.0 Installation/packaging:

  • The MQ JMS bridge implementation classes will be imqjmsbridge.jar to be instanlled under lib/
  • The JTA interface classes jta.jar is a dependency of imqjmsbridge.jar and to be installed under lib/
  • The fscontext.jar, currently already installed with MQ, can be a dependency of imqjmsbridge.jar if the jmsbridge is configured lookup administrative objects through the JNDI File System Service Provider.
  • sun_jmsbridge_1_0.dtd to be installed under lib/ or lib/dtd/

15.0 Use Cases:
Bridging MQ and WebSphere MQ
Bridging MQ and MQ
imqbridgemgr

Bridging MQ and WebSphere MQ using transacted link
  1. Set up and start WebSphere MQ queue manager by following WebSphere MQ instructions
  2. Create administrative objects with lookup name "ivtXACF" for XAConnectionFactory, "ivtQ" for the Queue destination object
  3. Create a JMS bridge xml document file, for example
    mq2series.jmsbridge.html
    the example JMS bridge is named "mq2seriesbridge"

  4. Set following broker properties
    imq.bridge.enabled=true
    imq.bridge.activelist=mq2seriesbridge
    imq.bridge.mq2seriesbridge.type=jms
    imq.bridge.mq2seriesbridge.xmlurl=<url points to the example mq2series.jmsbridge.xml file>
    imq.bridge.admin.password=admin
    imq.bridge.admin.user=admin

  5. Start the broker
  6. Send a message to Queue destination "mqq" in the MQ broker
  7. run "imqcmd list dst" to the MQ broker to confirm the message is gone in Queue "mqq"
  8. You can confirm the message has been transfered to WebSphere MQ's destination configured in the mq2series.jmsbridge.xml by running the reverse JMS bridge of the above example,
    series2mq.jmsbridge.html
    following the above steps only this time, the JMS bridge is named "series2mqbridge". When finished, you should see the message back to MQ broker's Queue "mqq"

Bridging MQ and MQ using transacted link

  1. Start brokerb on port 7678
  2. Create MQ XAConnectionFactory administrative object with lookup name cn=XCF7678 and imqAddressList set to <host-name>:7678
  3. Create JMS bridge xml document file, as
    mq2mq.jmsbridge.xml
    the example JMS bridge is named "mq2mqbridge"
  4. Set following broker properties to brokera imq.bridge.enabled=true
    imq.bridge.activelist=mq2mqbridge
    imq.bridge.mq2mqbridge.type=jms
    imq.bridge.mq2mqbridge.xmlurl=<url points to the example mq2mq.jmsbridge.xml file>
    imq.bridge.admin.password=admin
    imq.bridge.admin.user=admin

  5. Start brokera
  6. Send a message to Queue myqueue1 in brokera
  7. run imqcmd list dst in brokera and brokerb
    You should see the message has transfered from brokera myqueue1 to brokerb's myqueue2

imqbridgemgr

The following examples assume the broker is running on localhost:9555 and there is a configured JMS bridge named "mqtomqbridge".

  1. To list all bridges on the broker
    imqbridgemgr list bridge -b :9555
    Listing all bridges on the broker specified by:
    
    -------------------------
    Host         Primary Port
    -------------------------
    localhost    9555
    
    ----------------------------------------
    Bridge Name      Bridge Type     Bridge State
    ----------------------------------------
    mqtomqbridge    JMS           STOPPED
    
    Successfully listed the bridge(s).
    
  2. To list all bridges of a type JMS on the broker
    imqbridgemgr list bridge -t JMS -b :9555
    Listing all bridges where:
    
    ------------
    Bridge Type
    ------------
    JMS
    
    On the broker specified by:
    
    -------------------------
    Host         Primary Port
    -------------------------
    localhost    9555
    
    ----------------------------------------
    Bridge Name      Bridge Type     Bridge State
    ----------------------------------------
    mqtomqbridge    JMS           STOPPED
    
    Successfully listed the bridge(s).
    
  3. To list a bridge named "mqtomqbridge" on the broker
    imqbridgemgr list bridge -bn mqtomqbridge -b :9555
    Listing the bridge where:
    
    ------------
    Bridge Name
    ------------
    mqtomqbridge
    
    On the broker specified by:
    
    -------------------------
    Host         Primary Port
    -------------------------
    localhost    9555
    
    ---------------------------------------------------
    Bridge Name     Bridge Type    Bridge State    # Links
    ---------------------------------------------------
    mqtomqbridge    JMS            STOPPED         1
    
    --------------------------------------------------------------------------------------
    Link Name    Link State    Source                 Target                 Transacted
    --------------------------------------------------------------------------------------
    9555to9666   STOPPED      CF9555::queue:myqueue1   CF9666::queue:myqueue3   true
    9555to9777   STOPPED      CF9555::queue:myqueue2   CF9777::queue:myqueue4   true
    
    Successfully listed the bridge.
    
  4. To list a link named "9555to9666" in the bridge named "mqtomqbridge"
    imqbridgemgr list link -bn mqtomqbridge -ln 9555to9666 -b :9555
    Listing the link where:
    
    --------------------------
    Bridge Name     Link Name
    --------------------------
    mqtomqbridge    9555to9666
    
    On the broker specified by:
    
    -------------------------
    Host         Primary Port
    -------------------------
    localhost    9555
    
    ---------------------------------------------------
    Bridge Name     Bridge Type    Bridge State    # Links
    ---------------------------------------------------
    mqtomqbridge   JMS          STOPPED      1
    
    --------------------------------------------------------------------------------------
    Link Name    Link State    Source                 Target                 Transacted
    --------------------------------------------------------------------------------------
    9555to9666   STOPPED      CF9555::queue:myqueue1   CF9666::queue:myqueue2   true
    
    Successfully listed the link.
    
  5. To start a bridge named "mqtomqbridge"
    imqbridgemgr start bridge -bn mqtomqbridge -b :9555
    Starting the bridge where:
    
    ------------
    Bridge Name
    ------------
    mqtomqbridge
    
    On the broker specified by:
    
    -------------------------
    Host         Primary Port
    -------------------------
    localhost    9555
    
    Are you sure you want to start this bridge ? (y/n)[n] y
    
    Successfully started the bridge.
    
  6. It's an error to start a link when its bridge is in STOPPED state
    imqbridgemgr start link -bn mqtomqbridge -ln 9555to9666 -b :9555
    Starting the link where:
    
    --------------------------
    Bridge Name     Link Name
    --------------------------
    mqtomqbridge    9555to9666
    
    On the broker specified by:
    
    -------------------------
    Host         Primary Port
    -------------------------
    localhost    9555
    
    Are you sure you want to start this link ? (y/n)[n] y
    
    Error while performing this operation on the broker.
    Link operation can only be operated when the bridge is in STARTED state
    
    Starting the link failed.
    

    16.0 Other:
    [List other useful information about this feature here. If this feature impacts another part of the product make a note of it here.]

    17.0 Documentation:

    The following documentation will be impacted:

    Book

    Comments

    Technical Overview

     

    Administrator Guide and new Book

    How to enable broker bridge service, configure jmsbridge, use imqbridgemgr, link to examples of jmsbridge XML and README

    Installation Guide

     

    18.0 Open Issues:
    [List open issues]

    19.0 Version History

    Date

    Version

    Change

    01/16/2009

    1.0

    updated imqbridgemgr syntax & use cases

    12/14/2008

    0.91

    added JDBC table schema

    12/15/2008

    0.9

    first draft

    Sun Proprietary/Confidential: Internal Use Only
    (FS Version 1.1)



Terms of Use; Privacy Policy; Copyright ©2013-2016 (revision 20160708.bf2ac18)
 
 
Close
loading
Please Confirm
Close