JMS Bridge Extension Swiftlet

The JMS Bridge Swiftlet provides bridging functionality between SwiftMQ and any foreign JMS compliant systems. The Swiftlet installation may be executed within any router of a router network. The Swiftlet supports the bridging to any number of different foreign JMS systems simultaneously. Within a Swiftlet, one can, for example, define bridges to different Weblogic JMS and MQSeries JMS servers simultaneously and so implement a central "JMS Exchange" by a SwiftMQ router.

On breakdown or unavailability of a foreign JMS server, an automatic reconnect in a configurable retry interval takes place by the Swiftlet. Undelivered messages are redelivered.

The bridging between SwiftMQ and a foreign JMS server may be defined to queue/queue, topic/topic, queue/topic and topic/queue.

During the message transfer of a bridge, an automatic conversion within the message implementation of the respective target system takes place. The persistence manner of the messages may retain unchanged or it may be defined that messages are always transferred declared as persistent or non persistent. This, independent of the adjusted persistence mode of the source message.

Usage

The bridging to foreign JMS servers is done on the basis of the JMS API, which means, the Swiftlet operates towards the foreign JMS server as a normal JMS client.

Any number of foreign JMS servers may be defined within a Swiftlet. These are bridged in parallel and independently. Various properties are defined per foreign JMS server, which are necessary for the connection setup. These are username/password concerning the creation of Queue/TopicConnections, a retry interval whether the foreign JMS server is not available as well as the class name of an ObjectFactory and the name of a configuration file.

The ObjectFactory has a particular importance as it is used by the Swiftlet to produce the required administered objects, in other words connection factories and destinations. The indicated configuration file contains generic properties, which are used exclusively by the specified ObjectFactory. As the J2EE standard states that JMS administered objects are read out of a JNDI repository, this distribution delivers a JNDIObjectFactory which can be configured with the JNDI properties like the provider URL etc., required to create the InitalContext. With this JNDIObjectFactory it should be possible to bridge most of the foreign JMS systems.

Unfortunately, also such JMS systems exist, in which one need to use their proprietary connection factories. In this case, the ObjectFactory is implemented by yourself and their class name is to be specified at the server configuration.

Click here for the ObjectFactory javadoc.

Any number of JMS bridgings can be defined on any within the Swiftlet defined server. Every bridging configuration contains

  • bridging direction (local-to-remote or remote-to-local),
  • name and type (queue/topic) of the local destination,
  • name of the remote factory (Queue/TopicConnectionFactory),
  • name and type (queue/topic) of the remote destination,
  • transfer persistence which signifies the message persistence to the target. You may choose between "always persistent", "always non persistent" or "as set within the message".

Concerning the local-to-remote bridgings, of which the source is a queue, it is to be taken into account that these need to exist on the local router because no QueueReceiver can be created for a remote queue.

Thereafter, the bridging starts between the defined destinations. If a fault should occur, the entire defined server is marked as invalid, all connections are closed and it is tried within the retry interval to re-establish the bridges.

Example 1: Weblogic Bridge

This example shows how to create bridges between SwiftMQ and Weblogic JMS 8.1.

The first bridge is of type local to remote and connects the SwiftMQ queue toWLS@router1 with Weblogic's queue wlsqueue. If a message is send to toWLS@router1, it will be transfered to wlsqueue on the Weblogic server.

The second bridge is of type remote to local and connects Weblogic's queue wlsqueue with SwiftMQ's queue fromWLS@router1. If a message is send to wlsqueue, it will be transfered to fromWLS@router1 on the SwiftMQ router.

Therefore, if a message is send to toWLS@router1, it will be transfered to wlsqueue on the Weblogic server and immediately transfered back to fromWLS@router1 on the SwiftMQ router. The following pictures illustrates it:

Preparation

On the Weblogic server:

  • Create a JMS connection factory with name QueueConnectionFactory.
  • Create a queue with name wlsqueue.

On the SwiftMQ router (we assume the routername is router1):

  • Create a queue with name toWLS.
  • Create a queue with name fromWLS.
  • Append weblogic.jar to the router's classpath. It's important to append it, because Weblogic uses JMS 1.0.2 and SwiftMQ uses JMS 1.1 so the SwiftMQ jms.jar must be in front of weblogic.jar which contains the JMS 1.0.2 classes.
  • Restart the router.
  • Hot deploy the JMS Bridge Swiftlet.
  • Connect with SwiftMQ Explorer.

Step 1: Enable Tracing

It is highly recommended to enable tracing while you define your bridges. To do so, go to the Trace Swiftlet, change the filename of the first predicate of the trace space swiftlet to console and enable the trace space:

Step 2: Define a Server

Go to the JMS Bridge Swiftlet, click on node Server and do a right click. Choose Create a new Entity. This displays a frame to create a new Server. Just give it a name, e.g. weblogic, leave it disabled (we will enable it later) and hit Create:

Step 3: Define JNDI Properties

Expand the Object Factory node of the newly created bridge, select Object Factory Properties:

Do a right click and select Show Entity Table. A frame is displayed where you can add JNDI properties which is used from the bridge to create a JNDI InitialContext for Weblogic:

Use the Add button on the top left corner to add a JNDI property java.naming.factory.initial and specify the Weblogic factory:

Add another JNDI property with the java.naming.provider.url and specify Weblogic's provider URL:

The frame now lists all JNDI properties you've added; you can close it:

Step 4: Define a bridge from SwiftMQ to Weblogic

Next step is to define a bridge between the local SwiftMQ queue toWLS@router1 and the remote Weblogic queue wlsqueue. Select the node JMS Bridgings, right click and select Create a new Entity:

A frame is displayed to enter the bridging attributes:

The following table explains the above data:

Field Description
Name "toWLS" is just a name of this bridge.
Bridging Direction Goes from here to Weblogic, so it is "local_to_remote".
Durable Name n/a
Local Destination Name Is the local queue name "toWLS@router1".
Local Destination Type Is "queue".
Remote Factory Name Is the name of the remote connection factory. You've defined "QueueConnectionFactory" in Weblogic and this is what you specify here.
Remote Destination Name Is the remote queue name "wlsqueue".
Remote Destination Type Is "queue".
Transfer Persistence Define "as_source" to leave the persistence setting of a message untouched. You could also define "persistent" or "non_persistent" to change the persistence setting of messages on the fly.

Pushing the Create button creates the bridge.

Step 5: Define a bridge from Weblogic to SwiftMQ

Next step is to define a bridge between the remote Weblogic queue wlsqueue and the local SwiftMQ queue fromWLS@router1. Repeat the above procedure to create a new entity:

The following table explains the above data:

Field Description
Name "fromWLS" is just a name of this bridge.
Bridging Direction Goes from Weblogic to here, so it is "remote_to_local".
Durable Name n/a (only required if you connect to a durable subscriber)
Local Destination Name Is the local queue name "fromWLS@router1".
Local Destination Type Is "queue".
Remote Factory Name Is the name of the remote connection factory. You've defined "QueueConnectionFactory" in Weblogic and this is what you specify here.
Remote Destination Name Is the remote queue name "wlsqueue".
Remote Destination Type Is "queue".
Transfer Persistence Define "as_source" to leave the persistence setting of a message untouched. You could also define "persistent" or "non_persistent" to change the persistence setting of messages on the fly.

Pushing the Create button creates the bridge.

Step 6: Enable the Server

Everything is defined. Now you are ready to enable the server with its bridgings. To do so, double click the Enabled attribute of the server:

The server is now activated. Since you've enabled tracing, you should see it in your console window:

2003-11-10 17:15:39.296/swiftlet/xt$bridge/weblogic/creating objectfactory
      'com.swiftmq.extension.bridge.JNDIObjectFactory'
2003-11-10 17:15:39.296/swiftlet/xt$bridge/weblogic/create bridgings ...
2003-11-10 17:15:39.296/swiftlet/xt$bridge/weblogic/create bridging 'fromWLS' ...
2003-11-10 17:15:39.328/swiftlet/xt$bridge/weblogic/created:
      [DestinationBridge, name=fromWLS, source=[RemoteQueueBridgeSource, queue=wlsqueue],
      sink=[LocalQueueBridgeSink, queue=fromWLS@router1]]
2003-11-10 17:15:39.328/swiftlet/xt$bridge/weblogic/create bridging 'toWLS' ...
2003-11-10 17:15:39.328/swiftlet/xt$bridge/weblogic/created:
      [DestinationBridge, name=toWLS, source=[LocalQueueBridgeSource, queue=toWLS@router1],
      sink=[RemoteQueueBridgeSink, queue=wlsqueue]]

An entry is shown below the Usage node as long as the server bridge is active.

Step 7: Send some Test Messages

Send some Messages to toWLS@router1. You should see the transfer to/from Weblogic and the messages you sent should finally arrive at fromWLS@router1.

Step 8: Disable Tracing

If everything is ok, the tracing needs to be disabled because it will slow down your bridges a lot. Double click the Enabled attribute of the Swiftlet trace space:

Step 9: Save your Changes!

Finally and most important you should save your changes now:

The following XML is stored in the routerconfig.xml:

      <swiftlet name="xt$jmsbridge">
        <servers>
          <server name="weblogic" enabled="true">
            <bridgings>
              <bridging name="fromWLS"
                        direction="remote_to_local"
                        localname="fromWLS@router1"
                        remotefactoryname="QueueConnectionFactory"
                        remotename="wlsqueue"
                        remotetype="queue"/>
              <bridging name="toWLS"
                        localname="toWLS@router1"
                        remotefactoryname="QueueConnectionFactory"
                        remotename="wlsqueue"
                        remotetype="queue"/>
            </bridgings>
            <objectfactory>
              <properties>
                <property name="java.naming.factory.initial"
                          value="weblogic.jndi.WLInitialContextFactory"/>
                <property name="java.naming.provider.url"
                          value="t3://localhost:7001"/>
              </properties>
            </objectfactory>
          </server>
        </servers>
      </swiftlet>

Example 2: WebsphereMQ Bridge

This example shows how to create bridges between SwiftMQ and WebsphereMQ 5.3.

The first bridge is of type local to remote and connects the SwiftMQ queue toMQ@router1 with WebsphereMQ's queue queue. If a message is send to toMQ@router1, it will be transfered to queue on the WebsphereMQ server.

The second bridge is of type remote to local and connects WebsphereMQ's queue queue with SwiftMQ's queue fromMQ@router1. If a message is send to queue, it will be transfered to fromMQ@router1 on the SwiftMQ router.

Therefore, if a message is send to toMQ@router1, it will be transfered to queue on the WebsphereMQ server and immediately transfered back to fromMQ@router1 on the SwiftMQ router. The following pictures illustrates it:

Preparation

On the WebsphereMQ server:

  • Create a queue with name queue.
  • Create the JNDI bindings with WebsphereMQ's JMSAdmin tool.

To create the JNDI bindings, you have first to edit JMSAdmin.config which is located in WebsphereMQ's Java/bin directory. Set the following properties (we assume that WebsphereMQ's installation directory is d:/appserver/mq5.3):

      INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory
      PROVIDER_URL=file:/d:/appserver/mq5.3/Java/bin

Then start JMSAdmin.bat from WebsphereMQ's Java/bin directory and issue the following commands:

      DEF QCF(QCF)
      DEF Q(queue) QUEUE(queue)

This will create a QueueConnectionFactory with name QCF and a JNDI binding for the queue queue with JNDI name queue.

On the SwiftMQ router (we assume the routername is router1):

  • Create a queue with name toMQ.
  • Create a queue with name fromMQ.
  • Prepend fscontext.jar, providerutil.jar, com.ibm.mq.jar, com.ibm.mqbind.jar, com.ibm.mqjms.jar and connector.jar from WebsphereMQ's Java/lib directory to the router's classpath.
  • Restart the router.
  • Hot deploy the JMS Bridge Swiftlet.
  • Connect with SwiftMQ Explorer.

Step 1: Enable Tracing

It is highly recommended to enable tracing while you define your bridges. To do so, go to the Trace Swiftlet, change the filename of the first predicate of the trace space swiftlet to console and enable the trace space:

Step 2: Define a Server

Go to the JMS Bridge Swiftlet, click on node Server and do a right click. Choose Create a new Entity. This displays a frame to create a new Server. Just give it a name, e.g. webspheremq, leave it disabled (we will enable it later) and hit Create:

Step 3: Define JNDI Properties

Expand the Object Factory node of the newly created bridge, select Object Factory Properties:

Do a right click and select Show Entity Table. A frame is displayed where you can add JNDI properties which is used from the bridge to create a JNDI InitialContext for Weblogic:

Use the Add button on the top left corner to add a JNDI property java.naming.factory.initial and specify the com.sun.jndi.fscontext.RefFSContextFactory factory:

Add another JNDI property with the java.naming.provider.url and specify the provider URL file:/d:/appserver/mq5.3/Java/bin. This points to a file named .bindings where the JNDI entries are stored (you can store this file wherever you want but you have to change the provider URL accordingly):

The frame now lists all JNDI properties you've added; you can close it:

Step 4: Define a bridge from SwiftMQ to WebsphereMQ

Next step is to define a bridge between the local SwiftMQ queue toMQ@router1 and the remote WebsphereMQ queue queue. Select the node JMS Bridgings, right click and select Create a new Entity:

A frame is displayed to enter the bridging attributes:

The following table explains the above data:

Field Description
Name "toMQ" is just a name of this bridge.
Bridging Direction Goes from here to Weblogic, so it is "local_to_remote".
Durable Name n/a
Local Destination Name Is the local queue name "toMQ@router1".
Local Destination Type Is "queue".
Remote Factory Name Is the name of the remote connection factory. You've defined "QCF" in WebsphereMQ and this is what you specify here.
Remote Destination Name Is the remote queue name "queue".
Remote Destination Type Is "queue".
Transfer Persistence Define "as_source" to leave the persistence setting of a message untouched. You could also define "persistent" or "non_persistent" to change the persistence setting of messages on the fly.

Pushing the Create button creates the bridge.

Step 5: Define a bridge from WebsphereMQ to SwiftMQ

Next step is to define a bridge between the remote WebsphereMQ queue queue and the local SwiftMQ queue fromMQ@router1. Repeat the above procedure to create a new entity:

The following table explains the above data:

Field Description
Name "fromMQ" is just a name of this bridge.
Bridging Direction Goes from WebsphereMQ to here, so it is "remote_to_local".
Durable Name n/a (only required if you connect to a durable subscriber)
Local Destination Name Is the local queue name "fromMQ@router1".
Local Destination Type Is "queue".
Remote Factory Name Is the name of the remote connection factory. You've defined "QCF" in WebsphereMQ and this is what you specify here.
Remote Destination Name Is the remote queue name "queue".
Remote Destination Type Is "queue".
Transfer Persistence Define "as_source" to leave the persistence setting of a message untouched. You could also define "persistent" or "non_persistent" to change the persistence setting of messages on the fly.

Pushing the Create button creates the bridge.

Step 6: Enable the Server

Everything is defined. Now you are ready to enable the server with its bridgings. To do so, double click the Enabled attribute of the server:

The server is now activated. Since you've enabled tracing, you should see it in your console window:

      2005-01-26 10:02:10.765/swiftlet/xt$bridge/webspheremq/creating objectfactory
        'com.swiftmq.extension.bridge.JNDIObjectFactory'
      2005-01-26 10:02:10.765/swiftlet/xt$bridge/webspheremq/create bridgings ...
      2005-01-26 10:02:10.765/swiftlet/xt$bridge/webspheremq/create bridging 'fromMQ' ...
      2005-01-26 10:02:10.781/swiftlet/xt$bridge/webspheremq/created:
        [DestinationBridge, name=fromMQ, source=[RemoteQueueBridgeSource, queue=queue:///queue],
        sink=[LocalQueueBridgeSink, queue=fromMQ@router1]]
      2005-01-26 10:02:10.781/swiftlet/xt$bridge/webspheremq/create bridging 'toMQ' ...
      2005-01-26 10:02:10.781/swiftlet/xt$bridge/webspheremq/created:
        [DestinationBridge, name=toMQ, source=[LocalQueueBridgeSource, queue=toMQ@router1],
        sink=[RemoteQueueBridgeSink, queue=queue:///queue]]

An entry is shown below the Usage node as long as the server bridge is active.

Step 7: Send some Test Messages

Send some Messages to toMQ@router1. You should see the transfer to/from WebsphereMQ and the messages you sent should finally arrive at fromMQ@router1.

Step 8: Disable Tracing

If everything is ok, the tracing needs to be disabled because it will slow down your bridges a lot. Double click the Enabled attribute of the Swiftlet trace space:

Step 9: Save your Changes!

Finally and most important you should save your changes now:

The following XML is stored in the routerconfig.xml:

      <swiftlet name="xt$jmsbridge">
        <servers>
          <server name="webspheremq" enabled="true">
            <bridgings>
              <bridging name="fromMQ"
                        direction="remote_to_local"
                        localname="fromMQ@router1"
                        remotefactoryname="QCF"
                        remotename="queue"
                        remotetype="queue"/>
              <bridging name="toMQ"
                        localname="toMQ@router1"
                        remotefactoryname="QCF"
                        remotename="queue"
                        remotetype="queue"/>
            </bridgings>
            <objectfactory>
              <properties>
                <property name="java.naming.factory.initial"
                          value="com.sun.jndi.fscontext.RefFSContextFactory"/>
                <property name="java.naming.provider.url"
                          value="file:/d:/appserver/mq5.3/Java/bin"/>
              </properties>
            </objectfactory>
          </server>
        </servers>
      </swiftlet>

Jobs

The JMS Bridge Swiftlet registers jobs in job group JMS Bridge at the Scheduler Swiftlet:

These jobs can be scheduled via the Scheduler Swiftlet to run at specific times or in intervals, based on calenders and so on.

Server Bridge

The Server Bridge job activates server bridge on job start and deactivates it on job stop. The name of the bridge must be specified as parameter. The job requires to set a maximum runtime to deactivate the bridge. Otherwise it would be active forever.

The implementation of the Server Bridge job is quite simple. It sets the enabled attribute to true on job start and to false on job stop. Therefore, a server bridge which should run as a job should be initially disabled.

Parameter Mandatory Description
Bridge Name Yes Name of the server bridge.

Accounting

Accounting data is produces from an accounting source factory JMSBridgeSourceFactory which is automatically registered at the Accounting Swiftlet of the router.

Installation

The installation takes place via 'hot deployment'. See the documentation of the Deploy Swiftlet for further information.

Configuration

The configuration of the JMS Bridge Extension Swiftlet is defined within the element

      <swiftlet name="xt$bridge" .../>

of the router's configuration file. One can use the SwiftMQ Exlorer or CLI for configuration as well. They both save into that file.

Attributes of Element "swiftlet"

Definition

Attribute Type Mandatory Description
collect-interval java.lang.Long No Collect Interval (ms) for the Usage Section

Values

Attribute Values
collect-interval Default: 10000

Element List "servers", Parent Element: "swiftlet"

Server Definitions. This element list contains zero or more "server" elements with this template definition:

Definition

Attribute Type Mandatory Description
name java.lang.String Yes Name of this Server
enabled java.lang.Boolean No Enables/Disables this Server
clientid java.lang.String No Client Id for durable Subscribers
username java.lang.String No Username
password java.lang.String No Password
retryinterval java.lang.Long No Retry Interval (ms) for Re-Connect

Values

Attribute Values
enabled Default: false
clientid
username
password
retryinterval Default: 60000

Element "objectfactory", Parent Element: "server"

Object Factory Definition.

Definition

Attribute Type Mandatory Description
class java.lang.String Yes Object Factory Class

Values

Attribute Values
class Default: com.swiftmq.extension.bridge.JNDIObjectFactory

Element List "properties", Parent Element: "objectfactory"

Object Factory Properties. This element list contains zero or more "property" elements with this template definition:

Definition

Attribute Type Mandatory Description
name java.lang.String Yes Name of this Object Factory Property
value java.lang.String Yes Property Value

Values

Attribute Values
value

Element List "bridgings", Parent Element: "server"

JMS Bridging Definitions. This element list contains zero or more "bridging" elements with this template definition:

Definition

Attribute Type Mandatory Description
name java.lang.String Yes Name of this JMS Bridging
direction java.lang.String Yes Bridging Direction
localname java.lang.String Yes Name of the local Destination
localtype java.lang.String Yes Type of the local Destination
remotefactoryname java.lang.String Yes Name of the remote Queue/TopicConnectionFactory
remotename java.lang.String Yes Name of the remote Destination
remotetype java.lang.String Yes Type of the remote Destination
durablename java.lang.String No Name of the durable Subscriber
transferpersistence java.lang.String Yes Persistence Mode for Message Transfer

Values

Attribute Values
direction Choice: local_to_remote remote_to_local
Default: local_to_remote
localname
localtype Choice: queue topic
Default: queue
remotefactoryname
remotename
remotetype Choice: queue topic
durablename
transferpersistence Choice: persistent nonpersistent as_source
Default: as_source

CLI Commands During Deployment

This Swiftlet performs the following CLI commands during deployment:

      cc /sys$threadpool/pools
      new bridge.server
      cc /sys$threadpool/pools/bridge.server/threads
      new extension.xt$bridge.server.mgr
      cc /sys$threadpool/pools
      new bridge.source
      cc /sys$threadpool/pools/bridge.source/threads
      new extension.xt$bridge.source.queue
      new extension.xt$bridge.source.topic

CLI Commands During Undeployment

This Swiftlet performs the following CLI commands during undeployment:

      cc /sys$threadpool/pools
      delete bridge.server
      delete bridge.source
← AMQP Bridge Extension SwiftletJavaMail Bridge Extension Swiftlet →