Chapter 34. Core Bridges

The function of a bridge is to consume messages from a source queue, and forward them to a target address, typically on a different HornetQ server.
The source and target servers do not have to be in the same cluster which makes bridging suitable for reliably sending messages from one cluster to another, for instance across a WAN, or Internet and where the connection may be unreliable.
The bridge has built in resilience to failure so if the target server connection is lost due to network failure, the bridge will retry connecting to the target until it comes back on line. When it comes back on line it will resume operation as normal.
In summary, bridges are a way to reliably connect two separate HornetQ servers together. With a core bridge both source and target servers must be HornetQ servers.
Bridges can be configured to provide once and only once delivery guarantees even in the event of the failure of the source or the target server. They do this by using duplicate detection (described in Chapter 35, Duplicate Message Detection).

Note

Although they have similar function, do not confuse core bridges with JMS bridges!
Core bridges are for linking a HornetQ node with another HornetQ node and do not use the JMS API. A JMS Bridge is used for linking any two JMS 1.1 compliant JMS providers. So, a JMS Bridge could be used for bridging to or from different JMS compliant messaging system. it is always preferable to use a core bridge where possible. Core bridges use duplicate detection to provide once and only once guarantees. To provide the same guarantee using a JMS bridge, an XA which has a higher overhead and is more complex to configure would need to be used.

34.1. Configuring Bridges

Bridges are configured in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml. An example follows (this is actually from the bridge example): 
<bridge name="my-bridge">
   <queue-name>jms.queue.sausage-factory</queue-name>
   <forwarding-address>jms.queue.mincing-machine</forwarding-address>
   <filter string="name='aardvark'"/>
   <transformer-class-name>
        org.hornetq.jms.example.HatColourChangeTransformer
   </transformer-class-name>
   <retry-interval>1000</retry-interval>
   <retry-interval-multiplier>1.0</retry-interval-multiplier>
   <reconnect-attempts>-1</reconnect-attempts>
   <failover-on-server-shutdown>false</failover-on-server-shutdown>
   <use-duplicate-detection>true</use-duplicate-detection>
   <confirmation-window-size>10000000</confirmation-window-size>
   <connector-ref connector-name="remote-connector" 
        backup-connector-name="backup-remote-connector"/>     
   <user>foouser</user>
   <password>foopassword</password>
</bridge>
In the above example we have shown all the parameters its possible to configure for a bridge. In practice, many of the defaults may be used, therefore it will not be necessary to specify them all explicitly.
The parameters are described in the following list.

Core Bridge Parameters

name
All bridges must have a unique name in the server.
queue-name
This is the unique name of the local queue that the bridge consumes from, it is a mandatory parameter.
The queue must already exist by the time the bridge is instantiated at start-up.

Note

If using JMS then normally the JMS configuration (JBOSS_DIST/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-jms.xml) is loaded after the core configuration file <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml is loaded. If the bridge is consuming from a JMS queue then ensure that the JMS queue is also deployed as a core queue in the core configuration. Refer to the bridge example for an example of this.
forwarding-address
This is the address on the target server that the message will be forwarded to. If a forwarding address is not specified, then the original address of the message will be retained.
filter-string
An optional filter string can be supplied. If specified, only messages which match the filter expression specified in the filter string will be forwarded. The filter string follows the HornetQ filter expression syntax described in Chapter 12, Filter Expressions.
transformer-class-name
An optional transformer-class-name can be specified. This is the name of a user-defined class which implements the org.hornetq.core.server.cluster.Transformer interface.
If this is specified then the transformer's transform() method will be invoked with the message before it is forwarded. This allows the opportunity to transform the message header or body before forwarding
retry-interval
This optional parameter determines the period in milliseconds between subsequent reconnection attempts, if the connection to the target server has failed. The default value is 2000 milliseconds.
retry-interval-multiplier
This optional parameter determines a multiplier to apply to the time since the last retry in order to compute the time to the next retry.
This allows an exponential backoff between retry attempts to be implemented.
For example:
If retry-interval is set to 1000 ms and retry-interval-multiplier is set to 2.0, then, if the first reconnect attempt fails, there will be a wait of 1000 ms, then 2000 ms and then 4000 ms between subsequent reconnection attempts.
The default value is 1.0 meaning each reconnect attempt is spaced at equal intervals.
reconnect-attempts
This optional parameter determines the total number of reconnect attempts the bridge will make before giving up and shutting down. A value of -1 signifies an unlimited number of attempts. The default value is -1.
failover-on-server-shutdown
This optional parameter determines whether the bridge will attempt to fail-over onto a backup server (if specified) when the target server is cleanly shutdown rather than crashed.
The bridge connector can specify both a live and a backup server. If it specifies a backup server and this parameter is set to true, then if the target server is cleanly shutdown the bridge connection will attempt to fail-over onto its backup. If the bridge connector has no backup server configured, this parameter has no effect.
This parameter is useful when occasionally a bridge configured with a live and a backup target server is required, but fail-over to the backup is not required if the live server is taken down temporarily for maintenance.
The default value for this parameter is false.
use-duplicate-detection
This optional parameter determines whether the bridge will automatically insert a duplicate id property into each message that it forwards.
Doing so, allows the target server to perform duplicate detection on messages it receives from the source server. If the connection fails or the server crashes, when the bridge resumes it will resend unacknowledged messages. This might result in duplicate messages being sent to the target server. Enabling duplicate detection allows these duplicates to be screened out and ignored.
This allows the bridge to provide a once and only once delivery guarantee without using heavyweight methods such as XA (Refer to Chapter 35, Duplicate Message Detection for more information).
The default value for this parameter is true.
confirmation-window-size
This optional parameter determines the confirmation-window-size to use for the connection used to forward messages to the target node. This attribute is described in section Chapter 32, Client Reconnection and Session Reattachment.

Warning

When using the bridge to forward messages from a queue which has a max-size-bytes set it is important that confirmation-window-size is less than or equal to max-size-bytes to prevent the flow of messages from ceasing.
connector-ref
This mandatory parameter determines which connector pair the bridge will use to actually make the connection to the target server.
A connector encapsulates knowledge of what transport to use (TCP, SSL, HTTP etc) as well as the server connection parameters (host, port etc). For more information on connectors and their configuration, refer to Chapter 14, Configuring the Transport.
The connector-ref element can be configured with two attributes:
  • connector-name. This references the name of a connector defined in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml. The bridge will use this connector to make its connection to the target server. This attribute is mandatory.
  • backup-connector-name. This optional parameter also references the name of a connector defined in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml. It represents the connector that the bridge will fail-over to if it detects that the live server connection has failed. If this is specified and failover-on-server-shutdown is set to true then it will also attempt fail-over onto this connector if the live target server is cleanly shut-down.
user
This optional parameter determines the user name to use when creating the bridge connection to the remote server. If it is not specified the default cluster user specified by cluster-user in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml is used.
password
This optional parameter determines the password to use when creating the bridge connection to the remote server. If it is not specified, the default cluster password specified by cluster-password in <JBOSS_HOME>/jboss-as/server/<PROFILE>/deploy/hornetq/hornetq-configuration.xml is used.