JMS Bridge Extension Swiftlet

Overview

The JMS Bridge Extension Swiftlet enables message bridging between SwiftMQ and external JMS servers. It supports bidirectional transfer of messages between local SwiftMQ queues/topics and remote JMS destinations using configurable bridging definitions. The bridge is highly flexible, supporting custom object factories for remote resource lookup and robust connection management with retry and monitoring capabilities.

Features

JMS Server Bridging

The Swiftlet allows you to define one or more remote JMS servers as servers in the configuration. Each server definition can be enabled or disabled and includes connection credentials, a retry interval for reconnection attempts, and an object factory for obtaining remote JMS resources. The object factory is typically a JNDI-based implementation, but you can supply your own by implementing the ObjectFactory interface. Each server can have multiple bridgings that define the direction and mapping between local and remote destinations.

Object Factory Support

The bridge uses an ObjectFactory to look up remote JMS administered objects such as connection factories and destinations. The default is the JNDIObjectFactory, which performs JNDI lookups using provided properties (e.g., java.naming.factory.initial, java.naming.provider.url). You can implement your own ObjectFactory if the remote JMS provider does not use JNDI. The class must have a public no-argument constructor, and properties can be set via setProperties().

Connection Management and Retry

Each server maintains its own connection cache for queue and topic connections, using the provided username and password if specified. The bridge automatically retries connections at the configured retry interval if a connection fails, and logs errors via the Log Swiftlet.

Configuration Example:

<swiftlet name="xt$jmsbridge">
  <servers>
    <server name="foreignJMS1" enabled="true" retryinterval="30000">
      <objectfactory class="com.swiftmq.extension.jmsbridge.JNDIObjectFactory">
        <properties>
        </properties>
      </objectfactory>
      <bridgings>
        <bridging name="orders-bridge" direction="local_to_remote" localname="orders" localtype="queue" remotefactoryname="ForeignQCF" remotename="foreignOrders" remotetype="queue" transferpersistence="persistent"/>
      </bridgings>
    </server>
  </servers>
</swiftlet>

Flexible Bridging Definitions

Within each server, you can define multiple bridgings that specify how messages are transferred between SwiftMQ and the remote JMS server. Each bridging defines the direction (local_to_remote or remote_to_local), the local and remote destination names and types (queue or topic), the remote connection factory to use, and the persistence mode for message transfer. For topics, you can also specify a durable subscription name and client ID for durable subscriptions.

Direction Control

The direction property determines whether messages are sent from SwiftMQ to the remote server (local_to_remote) or received from the remote server into SwiftMQ (remote_to_local).

Persistence Mode

The transferpersistence property controls the delivery mode for bridged messages: persistent, nonpersistent, or as_source (preserve the original delivery mode).

Durable Subscriptions

For topic bridging, you can specify a durablename and clientid to use durable subscriptions on the remote or local side as appropriate.

Configuration Example:

<swiftlet name="xt$jmsbridge">
  <servers>
    <server name="foreignJMS1" enabled="true">
      <objectfactory class="com.swiftmq.extension.jmsbridge.JNDIObjectFactory"/>
      <bridgings>
        <bridging name="topic-bridge" direction="remote_to_local" localname="mytopic" localtype="topic" remotefactoryname="ForeignTCF" remotename="foreignTopic" remotetype="topic" durablename="myDurable" transferpersistence="as_source"/>
      </bridgings>
    </server>
  </servers>
</swiftlet>

Usage Monitoring and Statistics

The Swiftlet maintains a usage section that tracks active bridge servers and their bridgings. For each active bridging, it records the last transfer time and the number of messages transferred. The collection interval for updating these statistics can be configured via the collect-interval property on the Swiftlet.

Collect Interval

The collect-interval property (default 10000 ms) determines how often the Swiftlet updates usage statistics for active bridges. This helps with monitoring bridge activity and diagnosing issues.

Configuration Example:

<swiftlet name="xt$jmsbridge" collect-interval="5000"/>

Job Integration for Bridge Activation

The Swiftlet integrates with the scheduler/job system, providing a 'Server Bridge' job type. This allows you to activate or deactivate server bridges programmatically or via management tools by specifying the bridge name as a job parameter.

Configuration Guide

Bridging a Local Queue to a Remote JMS Queue

Use this scenario to forward messages from a local SwiftMQ queue to a remote JMS queue using a JNDI-based object factory.

Define a server with the appropriate object factory and JNDI properties for the remote JMS provider.
Add a bridging with direction local_to_remote, specifying the local queue name, remote factory name, and remote queue name.
Enable the server to activate the bridge.

<swiftlet name="xt$jmsbridge">
  <servers>
    <server name="foreignJMS1" enabled="true">
      <objectfactory class="com.swiftmq.extension.jmsbridge.JNDIObjectFactory">
        <properties>
        </properties>
      </objectfactory>
      <bridgings>
        <bridging name="orders-bridge" direction="local_to_remote" localname="orders" localtype="queue" remotefactoryname="ForeignQCF" remotename="foreignOrders" remotetype="queue" transferpersistence="persistent"/>
      </bridgings>
    </server>
  </servers>
</swiftlet>

Bridging from a Remote JMS Topic to a Local SwiftMQ Topic with Durable Subscription

Use this scenario to receive messages from a remote JMS topic into a local SwiftMQ topic, using a durable subscription on the remote side.

Define a server with the object factory and JNDI properties for the remote JMS provider.
Set the clientid property if required for durable subscriptions.
Add a bridging with direction remote_to_local, specifying the local topic, remote factory, remote topic, and a durablename.
Enable the server to start the bridge.

<swiftlet name="xt$jmsbridge">
  <servers>
    <server name="foreignJMS1" enabled="true" clientid="myClientId">
      <objectfactory class="com.swiftmq.extension.jmsbridge.JNDIObjectFactory"/>
      <bridgings>
        <bridging name="topic-bridge" direction="remote_to_local" localname="mytopic" localtype="topic" remotefactoryname="ForeignTCF" remotename="foreignTopic" remotetype="topic" durablename="myDurable" transferpersistence="as_source"/>
      </bridgings>
    </server>
  </servers>
</swiftlet>

Scheduler Jobs

Server Bridge

Description: Activates a Server Bridge

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="xt$jmsbridge">.

`<swiftlet name="xt$jmsbridge">` Properties

These properties are attributes of the <swiftlet name="xt$jmsbridge"> entity.

Parameter	Type	Default	Mandatory	Reboot Required	Description
`collect-interval`	Long	`10000`	No	No	Collect Interval (ms) for the Usage Section

<swiftlet name="xt$jmsbridge" collect-interval="10000"/>

`<servers>` in `<swiftlet name="xt$jmsbridge">`

Server Definitions

Each <server> entry is identified by its name attribute (the Server).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`enabled`	Boolean	`false`	No	No	Enables/Disables this Server
`clientid`	String	—	No	No	Client Id for durable Subscribers
`username`	String	—	No	No	Username
`password`	String	—	No	No	Password
`retryinterval`	Long	`60000`	No	No	Retry Interval (ms) for Re-Connect

<swiftlet name="xt$jmsbridge">
  <servers>
    <server name="..."/>
  </servers>
</swiftlet>

`<bridgings>` in `<servers>`

JMS Bridging Definitions

Each <bridging> entry is identified by its name attribute (the JMS Bridging).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`direction`	String	`local_to_remote`	Yes	No	Bridging Direction (choices: `local_to_remote`, `remote_to_local`)
`localname`	String	—	Yes	No	Name of the local Destination
`localtype`	String	`queue`	Yes	No	Type of the local Destination (choices: `queue`, `topic`)
`remotefactoryname`	String	—	Yes	No	Name of the remote Queue/TopicConnectionFactory
`remotename`	String	—	Yes	No	Name of the remote Destination
`remotetype`	String	—	Yes	No	Type of the remote Destination (choices: `queue`, `topic`)
`durablename`	String	—	No	No	Name of the durable Subscriber
`transferpersistence`	String	`as_source`	Yes	No	Persistence Mode for Message Transfer (choices: `persistent`, `nonpersistent`, `as_source`)

<swiftlet name="xt$jmsbridge">
  <servers>
    <server name="...">
      <bridgings>
        <bridging name="..." direction="..." localname="..." localtype="..." remotefactoryname="..." remotename="..." remotetype="..." transferpersistence="..."/>
      </bridgings>
    </server>
  </servers>
</swiftlet>

`<objectfactory>` in `<servers>`

Object Factory Definition

Parameter	Type	Default	Mandatory	Reboot Required	Description
`class`	String	`com.swiftmq.extension.jmsbridge.JNDIObjectFactory`	Yes	No	Object Factory Class

JMS Bridge Extension Swiftlet

Overview

Features

JMS Server Bridging

Object Factory Support

Connection Management and Retry

Flexible Bridging Definitions

Direction Control

Persistence Mode

Durable Subscriptions

Usage Monitoring and Statistics

Collect Interval

Job Integration for Bridge Activation

Configuration Guide

Bridging a Local Queue to a Remote JMS Queue

Bridging from a Remote JMS Topic to a Local SwiftMQ Topic with Durable Subscription

Scheduler Jobs

Server Bridge

Configuration Reference

<swiftlet name="xt$jmsbridge"> Properties

<servers> in <swiftlet name="xt$jmsbridge">

<bridgings> in <servers>

<objectfactory> in <servers>

`<swiftlet name="xt$jmsbridge">` Properties

`<servers>` in `<swiftlet name="xt$jmsbridge">`

`<bridgings>` in `<servers>`

`<objectfactory>` in `<servers>`