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 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 as 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 remain unchanged or it may be defined that messages are always transferred declared as persistent or non-persistent. This is 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, that Swiftlet operates toward 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 is 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 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 needs 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.

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.

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 calendars and so on.

Server Bridge

The Server Bridge job activates the server bridge on the job start and deactivates it on the job stop. The name of the bridge must be specified as a parameter. The job requires setting 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 that should run as a job should be initially disabled.

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

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

XML

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

of the router's configuration 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:

CODE

      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:

CODE

      cc /sys$threadpool/pools
      delete bridge.server
      delete bridge.source