Configuring a JMS Bridge (Oracle GlassFish Message Queue 4.4.2 Administration Guide)

Oracle GlassFish Message Queue 4.4.2 Administration Guide

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.

Table 12–2 Broker Properties for a JMS Bridge


Property	Type	Default Value	Description
`imq.bridge.name.type`	String	None	The bridge type of the bridge named `name`. For JMS bridges, specify a value of `JMS` or `jms`.
`imq.bridge.name.xmlurl`	String	None	The URL where the XML configuration file for the JMS bridge `name` is stored. Examples: `http://webserver/imq/jmsbridge1.config.xml` (for a file on a Web server) `file:/net/fileserver/imq/jmsbridge1.config.xml` (for a file on a shared drive)
`imq.bridge.name.autostart`	Boolean	`true`	Should the JMS bridge `name` be automatically started when the broker is started?
`imq.bridge.name.logfile.limit`	Integer	`0`	The approximate maximum number of bytes the JMS bridge `name` writes to any one log file. A value of `0` (zero) indicates that there is no maximum limit.
`imq.bridge.name.logfile.count`	Integer	`1`	The number of log files the JMS bridge `name` cycles through.
`imq.bridge.tm.props` `imq.bridge.name.tm.props`	String	None	Each of these properties specifies a list of key-value pairs for the built-in transaction coordinator for the JMS bridge `name`. The list consists of one or more `key=value` pairs separated by commas. When the `imq.persist.store` is `file`, the built-in transaction coordinator supports these keys: `txlogSize`, `txlogSync`, and `txlogMmap`. If the same key appears in both properties, the value specified in `imq.bridge.name.tm.props` takes precedence.

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.

Table 12–3 jmsbridge Attributes


Attribute	Type	Description
`name`	String	Unique name for this JMS bridge. Default value: no default
`log-message-transfer` [First available in Message Queue 4.4.2]	Boolean	Should each successful message transfer generate an INFO level log message? Default value: `true`
`message-transfer-tag-bridge-name`	Boolean	Should the `JMS_SUN_JMSBRIDGE_NAME` property be defined and set to the name of the bridge for each message before transferring to the link target? Default value: `false`

`link` Attributes

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

Table 12–4 link Attributes


Attribute	Type	Description
`enabled`	Boolean	If `false`, the link will not be started Default value: `true`
`name`	String	Unique identifier for this link Default value: no default
`transacted`	Boolean	If `true`, each message transfer from source to target will be done in a XA distributed transaction. The connection factories specified by the source and target must be `javax.jms.XAConnectionFactory` objects. If `false`, `CLIENT_ACKNOWLEDGE` mode will be used on the source The connection factories specified by the source and target must be `javax.jms.ConnectionFactory` objects. Default value: `true`

`source` Attributes

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

Table 12–5 source Attributes


Attribute	Type	Description
`clientid`	String	A JMS client identifier for the message consumer connection Default value: not set
`connection-factory-ref`	String	The `ref-name` attribute value of the `connection-factory` element to associate with this source. Default value: no default
`destination-ref`	String	The `ref-name` attribute value of the `destination` element to associate with this source. Default value: no default
`durable-sub`	String	A JMS durable subscription name. This attribute is ignored if the source's destination is not a `javax.jms.Topic` object. Default value: not set
`selector`	String	A JMS selector for the message consumer Default value: not set

`target` Attributes

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

Table 12–6 target Attributes


Attribute	Type	Description
`clientid`	String	A JMS client identifier for the message producer connection; if set, use a dedicated connection. Default value: not set
`connection-factory-ref`	String	The `ref-name` attribute value of the `connection-factory` element to associate with this target. Default value: no default
`consume-no-transfer-on-transform-error`	Boolean	Controls processing when the message transformer's `MessageTransformer.transform()` method returns a null value or throws `java.lang.Throwable`: If `true`, the message is sent to the DMQ and consumed from the source but not sent to the target. If `false`, the link is stopped, and the message is neither consumed from the source nor transferred to the target. Default value: `false`
`destination-ref`	String	The `ref-name` attribute value of the `destination` element to associate with this target. The value `AS_SOURCE` is also supported. This value causes the target destination name and type to be set to the source message's `javax.jms.Message.getJMSDestination()`, unless overridden by the message transformer's `MessageTransformer.branchTo()`. Default value: no default
`message-transformer-class`	String	A fully qualified class name that extends the Message Queue bridge `MessageTransformer` class. For more information, see Message Transformation During Message Delivery. Place this class under the `IMQ_HOME/lib/ext` directory. Default value: not set
`retain-replyto`	Boolean	Should the value of the source message's `JMSReplyTo` header (if specified) be retained? For more information, see JMSReplyTo Header Processing. Default value: `false`
`stay-connected`	Boolean	If `true`, the message producer connection will stay connected, and be dedicated. Default value: `true`

`dmq` Attributes

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

Table 12–7 dmq Attributes


Attribute	Type	Description
`client-id`	String	JMS client identifier for the DMQ producer connection. If set, the connection will be dedicated. Default value: not set
`connection-factory-ref` [This attribute is ignored for the built-in DMQ, `built-in-dmq`]	String	The `ref-name` attribute value of the `connection-factory` element to associate with this DMQ. This connection factory must be a `javax.jms.ConnectionFactory` object. Default value: no default
`destination-ref`	String	The `ref-name` attribute value of the `destination` element to associate with this DMQ. Default value: no default
`enabled`	Boolean	Is this DMQ is enabled? Default value: `true`
`message-transformer-class`	String	A fully qualified class name that extends the Message Queue bridge `MessageTransformer` class. For more information, see Message Transformation During Message Delivery. Default value: not set
`name`	String	The unique identifier of this DMQ. Default value: no default
`send-attempt-interval-in-seconds`	Integer	How long to wait before attempting to resend an undeliverable message to this DMQ. Default value: `5`
`send-attempts`	Integer	The number of attempts to send (or resend) an undeliverable message to this DMQ. Default value: `3`
`stay-connected`	Boolean	If true, the DMQ producer connection will stay connected and be dedicated. Default value: `true`
`time-to-live-in-millis`	Integer	Time-to-live in milliseconds for messages going to this DMQ. The value `0` means forever. Default value: `0`

`connection-factory` Attributes

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

Table 12–8 connection-factory Attributes


Attribute	Type	Description
`connect-attempt-interval-in-seconds`	Integer	How long to wait before each connect attempt. Default value: `5`
`connect-attempts`	Integer	The number of attempts for connecting. The value `-1` means retry forever Default value: `-1`
`idle-timeout-in-seconds`	Integer	Close a connection if it is idle for more than this long. The value `0` indicates no idle timeout. This attribute is ignored for sources and for targets and DMQs that have their `stay-connected` attribute set to `true`. Default value: `1800`
`lookup-name`	String	JNDI lookup name. If specified, the JNDI environment properties must specified as `property` subelements of this `connection-factory` element. 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 Message Queue broker hosting the bridge is created with the properties in the `property` subelements. Default value: not set
`multi-rm`	Boolean	Set to `true` if this connection factory will potentially create XA connections to more than one XA resource manager (that is, `XAResource.isSame()` is `false` among them). Also, add separate `connection-factory` for each such resource manager so that they will be registered separately to the built-in XA transaction coordinator. Default value: `false`
`password`	String	The password for the user specified in `username`. Default value: not set
`ref-name`	String	Unique name for this connection factory. Default value: no default
`username`	String	The user name to be used to create connections from this connection factory. If this attribute is set, the `password` attribute must also be set. If not set, connections are created using the no-argument `createConnection()` method of the connection factory. Default value: not set

`destination` Attributes

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

Table 12–9 destination Attributes


Attribute	Type	Description
`lookup-name`	String	JNDI lookup name for the destination. If specified, the JNDI environment properties must specified as `property` subelements of this `destination` element. Default value: not set
`name`	String	The JMS destination name of this destination. This attribute is ignored if `lookup-name` is specified. Default value: not set
`ref-name`	String	Unique name for this destination. Default value: no default
`type`	`queue` or `topic`	The JMS destination type of this destination. This attribute is ignored if `lookup-name` is specified Default value: `queue`