243 lines
16 KiB
XML
243 lines
16 KiB
XML
<?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>
|
||
org.apache.activemq6.jms.example.HatColourChangeTransformer
|
||
</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
|
||
<literal>org.apache.activemq6.core.server.cluster.Transformer</literal>
|
||
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>
|
||
|
||
<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>
|
||
|
||
</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>
|