2014-10-31 06:20:28 -04:00
|
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
|
|
|
|
<!-- ============================================================================= -->
|
|
|
|
|
|
<!-- Copyright © 2009 Red Hat, Inc. and others. -->
|
|
|
|
|
|
<!-- -->
|
|
|
|
|
|
<!-- The text of and illustrations in this document are licensed by Red Hat under -->
|
|
|
|
|
|
<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
|
|
|
|
|
|
<!-- -->
|
|
|
|
|
|
<!-- An explanation of CC-BY-SA is available at -->
|
|
|
|
|
|
<!-- -->
|
|
|
|
|
|
<!-- http://creativecommons.org/licenses/by-sa/3.0/. -->
|
|
|
|
|
|
<!-- -->
|
|
|
|
|
|
<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
|
|
|
|
|
|
<!-- of it, you must provide the URL for the original version. -->
|
|
|
|
|
|
<!-- -->
|
|
|
|
|
|
<!-- Red Hat, as the licensor of this document, waives the right to enforce, -->
|
|
|
|
|
|
<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
|
|
|
|
|
|
<!-- permitted by applicable law. -->
|
|
|
|
|
|
<!-- ============================================================================= -->
|
|
|
|
|
|
|
|
|
|
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
|
|
|
|
<!ENTITY % BOOK_ENTITIES SYSTEM "HornetQ_User_Manual.ent">
|
|
|
|
|
|
%BOOK_ENTITIES;
|
|
|
|
|
|
]>
|
|
|
|
|
|
<chapter id="core-bridges">
|
|
|
|
|
|
<title>Core Bridges</title>
|
|
|
|
|
|
<para>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.</para>
|
|
|
|
|
|
<para>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.</para>
|
|
|
|
|
|
<para>The bridge has built in resilience to failure so if the target server connection is lost,
|
|
|
|
|
|
e.g. due to network failure, the bridge will retry connecting to the target until it comes
|
|
|
|
|
|
back online. When it comes back online it will resume operation as normal.</para>
|
|
|
|
|
|
<para>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.</para>
|
|
|
|
|
|
<para>Bridges can be configured to provide <emphasis>once and only once</emphasis> 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 <xref linkend="duplicate-detection"/>).</para>
|
|
|
|
|
|
<note>
|
|
|
|
|
|
<para>Although they have similar function, don't confuse core bridges with JMS
|
|
|
|
|
|
bridges!</para>
|
|
|
|
|
|
<para>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's always preferable to use a core bridge if you can. Core bridges use
|
|
|
|
|
|
duplicate detection to provide <emphasis>once and only once</emphasis> guarantees. To
|
|
|
|
|
|
provide the same guarantee using a JMS bridge you would have to use XA which has a
|
|
|
|
|
|
higher overhead and is more complex to configure.</para>
|
|
|
|
|
|
</note>
|
|
|
|
|
|
<section>
|
|
|
|
|
|
<title>Configuring Bridges</title>
|
|
|
|
|
|
<para>Bridges are configured in <literal>hornetq-configuration.xml</literal>. Let's kick off
|
|
|
|
|
|
with an example (this is actually from the bridge example):</para>
|
|
|
|
|
|
<programlisting>
|
|
|
|
|
|
<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>
|
2014-11-11 10:40:01 -05:00
|
|
|
|
org.apache.activemq6.jms.example.HatColourChangeTransformer
|
2014-10-31 06:20:28 -04:00
|
|
|
|
</transformer-class-name>
|
|
|
|
|
|
<retry-interval>1000</retry-interval>
|
|
|
|
|
|
<ha>true</ha>
|
|
|
|
|
|
<retry-interval-multiplier>1.0</retry-interval-multiplier>
|
|
|
|
|
|
<initial-connect-attempts>-1</initial-connect-attempts>
|
|
|
|
|
|
<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>
|
|
|
|
|
|
<user>foouser</user>
|
|
|
|
|
|
<password>foopassword</password>
|
|
|
|
|
|
<static-connectors>
|
|
|
|
|
|
<connector-ref>remote-connector</connector-ref>
|
|
|
|
|
|
</static-connectors>
|
|
|
|
|
|
<!-- alternative to static-connectors
|
|
|
|
|
|
<discovery-group-ref discovery-group-name="bridge-discovery-group"/>
|
|
|
|
|
|
-->
|
|
|
|
|
|
</bridge></programlisting>
|
|
|
|
|
|
<para>In the above example we have shown all the parameters its possible to configure for a
|
|
|
|
|
|
bridge. In practice you might use many of the defaults so it won't be necessary to
|
|
|
|
|
|
specify them all explicitly.</para>
|
|
|
|
|
|
<para>Let's take a look at all the parameters in turn:</para>
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>name</literal> attribute. All bridges must have a unique name in the
|
|
|
|
|
|
server.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>queue-name</literal>. This is the unique name of the local queue that
|
|
|
|
|
|
the bridge consumes from, it's a mandatory parameter.</para>
|
|
|
|
|
|
<para>The queue must already exist by the time the bridge is instantiated at
|
|
|
|
|
|
start-up.</para>
|
|
|
|
|
|
<note>
|
|
|
|
|
|
<para>If you're using JMS then normally the JMS configuration <literal
|
|
|
|
|
|
>hornetq-jms.xml</literal> is loaded after the core configuration file
|
|
|
|
|
|
<literal>hornetq-configuration.xml</literal> is loaded. If your bridge
|
|
|
|
|
|
is consuming from a JMS queue then you'll need to make sure the JMS queue is
|
|
|
|
|
|
also deployed as a core queue in the core configuration. Take a look at the
|
|
|
|
|
|
bridge example for an example of how this is done.</para>
|
|
|
|
|
|
</note>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>forwarding-address</literal>. 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.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>filter-string</literal>. An optional filter string can be supplied.
|
|
|
|
|
|
If specified then 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 <xref linkend="filter-expressions"
|
|
|
|
|
|
/>.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>transformer-class-name</literal>. An optional transformer-class-name
|
|
|
|
|
|
can be specified. This is the name of a user-defined class which implements the
|
2014-11-11 10:40:01 -05:00
|
|
|
|
<literal>org.apache.activemq6.core.server.cluster.Transformer</literal>
|
2014-10-31 06:20:28 -04:00
|
|
|
|
interface.</para>
|
|
|
|
|
|
<para>If this is specified then the transformer's <literal>transform()</literal>
|
|
|
|
|
|
method will be invoked with the message before it is forwarded. This gives you
|
|
|
|
|
|
the opportunity to transform the message's header or body before forwarding
|
|
|
|
|
|
it.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>ha</literal>. This optional parameter determines whether or not this
|
|
|
|
|
|
bridge should support high availability. True means it will connect to any available
|
|
|
|
|
|
server in a cluster and support failover. The default value is <literal
|
|
|
|
|
|
>false</literal>.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>retry-interval</literal>. 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 <literal
|
|
|
|
|
|
>2000</literal>milliseconds.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>retry-interval-multiplier</literal>. This optional parameter
|
|
|
|
|
|
determines determines a multiplier to apply to the time since the last retry to
|
|
|
|
|
|
compute the time to the next retry.</para>
|
|
|
|
|
|
<para>This allows you to implement an <emphasis>exponential backoff</emphasis>
|
|
|
|
|
|
between retry attempts.</para>
|
|
|
|
|
|
<para>Let's take an example:</para>
|
|
|
|
|
|
<para>If we set <literal>retry-interval</literal>to <literal>1000</literal> ms and
|
|
|
|
|
|
we set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>,
|
|
|
|
|
|
then, if the first reconnect attempt fails, we will wait <literal>1000</literal>
|
|
|
|
|
|
ms then <literal>2000</literal> ms then <literal>4000</literal> ms between
|
|
|
|
|
|
subsequent reconnection attempts.</para>
|
|
|
|
|
|
<para>The default value is <literal>1.0</literal> meaning each reconnect attempt is
|
|
|
|
|
|
spaced at equal intervals.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>initial-connect-attempts</literal>. This optional parameter determines the
|
|
|
|
|
|
total number of initial connect attempts the bridge will make before giving up and
|
|
|
|
|
|
shutting down. A value of <literal>-1</literal> signifies an unlimited number of
|
|
|
|
|
|
attempts. The default value is <literal>-1</literal>.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>reconnect-attempts</literal>. This optional parameter determines the
|
|
|
|
|
|
total number of reconnect attempts the bridge will make before giving up and
|
|
|
|
|
|
shutting down. A value of <literal>-1</literal> signifies an unlimited number of
|
|
|
|
|
|
attempts. The default value is <literal>-1</literal>.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>failover-on-server-shutdown</literal>. This optional parameter
|
|
|
|
|
|
determines whether the bridge will attempt to failover onto a backup server (if
|
|
|
|
|
|
specified) when the target server is cleanly shutdown rather than
|
|
|
|
|
|
crashed.</para>
|
|
|
|
|
|
<para>The bridge connector can specify both a live and a backup server, if it
|
|
|
|
|
|
specifies a backup server and this parameter is set to <literal>true</literal>
|
|
|
|
|
|
then if the target server is <emphasis>cleanly</emphasis> shutdown the bridge
|
|
|
|
|
|
connection will attempt to failover onto its backup. If the bridge connector has
|
|
|
|
|
|
no backup server configured then this parameter has no effect. </para>
|
|
|
|
|
|
<para>Sometimes you want a bridge configured with a live and a backup target server,
|
|
|
|
|
|
but you don't want to failover to the backup if the live server is simply taken
|
|
|
|
|
|
down temporarily for maintenance, this is when this parameter comes in
|
|
|
|
|
|
handy.</para>
|
|
|
|
|
|
<para>The default value for this parameter is <literal>false</literal>.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>use-duplicate-detection</literal>. This optional parameter determines
|
|
|
|
|
|
whether the bridge will automatically insert a duplicate id property into each
|
|
|
|
|
|
message that it forwards.</para>
|
|
|
|
|
|
<para>Doing so, allows the target server to perform duplicate detection on messages
|
|
|
|
|
|
it receives from the source server. If the connection fails or server crashes,
|
|
|
|
|
|
then, when the bridge resumes it will resend unacknowledged messages. This might
|
|
|
|
|
|
result in duplicate messages being sent to the target server. By enabling
|
|
|
|
|
|
duplicate detection allows these duplicates to be screened out and
|
|
|
|
|
|
ignored.</para>
|
|
|
|
|
|
<para>This allows the bridge to provide a <emphasis>once and only once</emphasis>
|
|
|
|
|
|
delivery guarantee without using heavyweight methods such as XA (see <xref
|
|
|
|
|
|
linkend="duplicate-detection"/> for more information).</para>
|
|
|
|
|
|
<para>The default value for this parameter is <literal>true</literal>.</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>confirmation-window-size</literal>. This optional parameter
|
|
|
|
|
|
determines the <literal>confirmation-window-size</literal> to use for the
|
|
|
|
|
|
connection used to forward messages to the target node. This attribute is
|
|
|
|
|
|
described in section <xref linkend="client-reconnection"/></para>
|
|
|
|
|
|
|
2014-11-10 11:14:12 -05:00
|
|
|
|
<warning><para>When using the bridge to forward messages to an address which uses
|
|
|
|
|
|
the <literal>BLOCK</literal> <literal>address-full-policy</literal> from a
|
|
|
|
|
|
queue which has a <literal>max-size-bytes</literal> set it's important that
|
|
|
|
|
|
<literal>confirmation-window-size</literal> is less than or equal to
|
|
|
|
|
|
<literal>max-size-bytes</literal> to prevent the flow of messages from
|
|
|
|
|
|
ceasing.</para>
|
|
|
|
|
|
</warning>
|
2014-10-31 06:20:28 -04:00
|
|
|
|
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>user</literal>. 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 <literal>cluster-user</literal>
|
|
|
|
|
|
in <literal>hornetq-configuration.xml</literal> will be used. </para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>password</literal>. 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 <literal
|
|
|
|
|
|
>cluster-password</literal> in <literal>hornetq-configuration.xml</literal>
|
|
|
|
|
|
will be used. </para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
|
|
|
|
<para><literal>static-connectors</literal> or <literal>discovery-group-ref</literal>.
|
|
|
|
|
|
Pick either of these options to connect the bridge to the target server.
|
|
|
|
|
|
</para>
|
|
|
|
|
|
<para> The <literal>static-connectors</literal> is a list of <literal>connector-ref</literal>
|
|
|
|
|
|
elements pointing to <literal>connector</literal> elements defined elsewhere.
|
|
|
|
|
|
A <emphasis>connector</emphasis> encapsulates knowledge of what transport to
|
|
|
|
|
|
use (TCP, SSL, HTTP etc) as well as the server connection parameters (host, port
|
|
|
|
|
|
etc). For more information about what connectors are and how to configure them,
|
|
|
|
|
|
please see <xref linkend="configuring-transports"/>.
|
|
|
|
|
|
</para>
|
|
|
|
|
|
<para>The <literal>discovery-group-ref</literal> element has one attribute -
|
|
|
|
|
|
<literal>discovery-group-name</literal>. This attribute points to a
|
|
|
|
|
|
<literal>discovery-group</literal> defined elsewhere. For more information about
|
|
|
|
|
|
what discovery-groups are and how to configure them, please see
|
|
|
|
|
|
<xref linkend="clusters.discovery-groups"/>.
|
|
|
|
|
|
</para>
|
|
|
|
|
|
</listitem>
|
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
</section>
|
|
|
|
|
|
</chapter>
|
