Author: buildbot
Date: Fri Dec 18 17:21:46 2015
New Revision: 975885
Log:
Production update by buildbot for activemq
Modified:
websites/production/activemq/content/cache/main.pageCache
websites/production/activemq/content/failover-transport-reference.html
Modified: websites/production/activemq/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/activemq/content/failover-transport-reference.html
==============================================================================
--- websites/production/activemq/content/failover-transport-reference.html
(original)
+++ websites/production/activemq/content/failover-transport-reference.html Fri
Dec 18 17:21:46 2015
@@ -81,16 +81,16 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><h3
id="FailoverTransportReference-TheFailoverTransport">The Failover
Transport</h3><p>The Failover transport layers reconnect logic on top of any of
the other transports. The configuration syntax allows you to specify any number
of composite URIs. The Failover transport randomly chooses one of the composite
URIs and attempts to establish a connection to it. If it does not succeed, or
if it subsequently fails, a new connection is established choosing one of the
other URIs randomly from the list.</p><h4
id="FailoverTransportReference-ConfigurationSyntax">Configuration
Syntax</h4><p><code><strong>failover:(uri1,...,uriN)?transportOptions&nestedOptions</strong></code></p><p>or</p><p><code><strong>failover:uri1,...,uriN</strong></code></p><h5
id="FailoverTransportReference-UsingRandomize">Using Randomize</h5><p>The
Failover transport chooses a URI at <code>random</code> by default. This
effectively load-balances clients over multiple brokers. Ho
wever, to have a client connect to a primary first and only connect to a
secondary backup broker when the primary is unavailable, set
<strong><code>randomize=false</code></strong>. For example:</p><div
class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+<div class="wiki-content maincontent"><h3
id="FailoverTransportReference-TheFailoverTransport">The Failover
Transport</h3><p>The Failover transport layers reconnect logic on top of any of
the other transports. The configuration syntax allows you to specify any number
of composite URIs. The Failover transport randomly chooses one of the composite
URIs and attempts to establish a connection to it. If it does not succeed, or
if it subsequently fails, a new connection is established choosing one of the
other URIs randomly from the list.</p><h4
id="FailoverTransportReference-ConfigurationSyntax">Configuration
Syntax</h4><p><code><strong>failover:(uri1,...,uriN)?transportOptions&nestedURIOptions</strong></code></p><p>or</p><p><code><strong>failover:uri1,...,uriN</strong></code></p><h5
id="FailoverTransportReference-UsingRandomize">Using Randomize</h5><p>The
Failover transport chooses a URI at <code>random</code> by default. This
effectively load-balances clients over multiple brokers.
However, to have a client connect to a primary first and only connect to a
secondary backup broker when the primary is unavailable, set
<strong><code>randomize=false</code></strong>. For
example:</p><p> </p><div class="preformatted panel" style="border-width:
1px;"><div class="preformattedContent panelContent">
<pre>failover:(tcp://primary:61616,tcp://secondary:61616)?randomize=false
</pre>
-</div></div><h5 id="FailoverTransportReference-TransportOptions">Transport
Options</h5><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Option Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default Value</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>initialReconnectDelay</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>10</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The delay (in ms) before the
<em>first</em> reconnect attempt.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>maxReconnectDelay</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>30000</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The maximum delay (in ms) between the
<em>second and subsequent</em> reconnect attempts.</p>
</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>useExponentialBackOff</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>If
<strong><code>true</code></strong> an exponential back-off is used between
reconnect attempts.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>reconnectDelayExponent</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>2.0</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The exponent used during
exponential back-off attempts.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>maxReconnectAttempts</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>-1 | 0</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><em>From</em> ActiveMQ 5.6:
default is <strong><code>-1</code></strong>, retry forever.
<strong><code>0</code></strong>
means disables re-connection, e.g: just try to connect once.<br clear="none"
class="atl-forced-newline"> <em>Before</em> ActiveMQ 5.6: default is
<strong><code>0</code></strong>, retry forever. <br clear="none"
class="atl-forced-newline"> <em>All versions</em>: a value
<strong><code>>0</code></strong> denotes the maximum number of reconnect
attempts before an error is sent back to the client.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>startupMaxReconnectAttempts</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>-1</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>If not
<strong><code>0</code></strong>, then this is the maximum number of reconnect
attempts before an error is sent back to the client on the first attempt by the
client to start a connection. Once connected, however, the
<code><strong>maxReconnectAttempts</strong></code> option then
applies. </p><p>A value of <strong><code>-1</code></strong>
signifies that the transport will have no limit to the number of initial
connection attempts.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>randomize</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>If <strong><code>true</code></strong>,
choose a URI at random from the list to use for reconnect.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>backup</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Initialize and hold a second
transport connection - to enable fast failover.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>timeout</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>-1</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Set the timeout on send operations (in ms)
without interruption of re-connection process. <strong>Since ActiveMQ
5.3</strong>.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>trackMessages</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Keep a cache of in-flight messages that
will flushed to a broker on reconnect.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>maxCacheSize</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>131072</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Size in bytes for the cache of
tracked messages. Applicable only if
<strong><code>trackMessages</code></strong> is
<strong><code>true</code></strong>.</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>updateURIsSupported</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td
colspan="1" rowspan="
1" class="confluenceTd"><p>Determines whether the client should accept updates
from the broker to its list of known URIs. <strong>Since</strong><strong>
ActiveMQ 5.4.</strong></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>updateURIsURL</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A URL (or path to a local file) to a text
file containing a comma separated list of URIs to use for reconnect in the case
of failure. <strong>Since ActiveMQ 5.4.</strong></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>nested.*</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Extra options to add to the nested URLs.
<strong>Since ActiveMQ 5.9.</strong></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>warnAfterReconnectAttempts</c
ode></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>10</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Log a warning after every N reconnect attempts. This
indicates that there is no current connection but re-connection is being
attempted. Set to <strong><code><= 0</code></strong> to disable.
<strong>Since ActiveMQ 5.10.</strong></p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><code>reconnectSupported</code></td><td
colspan="1" rowspan="1" class="confluenceTd"><code>true</code></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Determines whether the client
should respond to broker <strong><code>ConnectionControl</code></strong> events
with a reconnect (see:
<strong><code>rebalanceClusterClients</code>).</strong></p></td></tr></tbody></table></div><h5
id="FailoverTransportReference-ExampleURI">Example URI</h5><div
class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+</div></div><h5 id="FailoverTransportReference-TransportOptions">Transport
Options</h5><p> </p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Option Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default Value</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>initialReconnectDelay</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>10</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The delay (in ms) before the
<em>first</em> reconnect attempt.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>maxReconnectDelay</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>30000</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The maximum delay (in ms) between the
<em>second and subsequent</em> reconnect
attempts.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>useExponentialBackOff</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>If
<strong><code>true</code></strong> an exponential back-off is used between
reconnect attempts.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>reconnectDelayExponent</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>2.0</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The exponent used during
exponential back-off attempts.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>maxReconnectAttempts</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>-1 | 0</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><em>From</em> ActiveMQ 5.6:
default is <strong><code>-1</code></strong>, retry forever. <strong><code>0</c
ode></strong> means disables re-connection, e.g: just try to connect once.<br
clear="none" class="atl-forced-newline"> <em>Before</em> ActiveMQ 5.6: default
is <strong><code>0</code></strong>, retry forever. <br clear="none"
class="atl-forced-newline"> <em>All versions</em>: a value
<strong><code>>0</code></strong> denotes the maximum number of reconnect
attempts before an error is sent back to the client.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>startupMaxReconnectAttempts</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>-1</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>A value of
<strong><code>-1</code></strong> denotes that the number of connection attempts
at startup should be unlimited.</p><p>A value of  <strong><code>>=0
</code></strong>denotes the number of reconnect attempts at startup that will
be made after which an error is sent back to the client when the client makes a
subsequent re
connect attempt.</p><p><strong>Note</strong>: once successfully connected the
<code><strong>maxReconnectAttempts</strong></code> option take precedence over
this option.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>randomize</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>If <strong><code>true</code></strong>,
choose a URI at random from the list to use for reconnect.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>backup</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Initialize and hold a second
transport connection - to enable fast failover.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>timeout</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>-1</code></p></td><td colspan="1" rows
pan="1" class="confluenceTd"><p>Set the timeout on send operations (in ms)
without interruption of re-connection process. <strong>Since ActiveMQ
5.3</strong>.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>trackMessages</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Keep a cache of in-flight messages that
will flushed to a broker on reconnect.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>maxCacheSize</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>131072</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Size in bytes for the cache of
tracked messages. Applicable only if
<strong><code>trackMessages</code></strong> is
<strong><code>true</code></strong>.</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>updateURIsSupported</code></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>true</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Determines whether the client should accept updates
from the broker to its list of known URIs. <strong>Since</strong><strong>
ActiveMQ 5.4.</strong></p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>updateURIsURL</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>A URL (or path to a local file) to a text
file containing a comma separated list of URIs to use for reconnect in the case
of failure. <strong>Since ActiveMQ 5.4.</strong></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>nested.*</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Extra options to add to the nested URLs.
<strong>Since ActiveMQ 5.9.</strong></p></td></tr><tr><td colspan=
"1" rowspan="1"
class="confluenceTd"><p><code>warnAfterReconnectAttempts</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>10</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>A value
<strong><code>>0</code></strong> specifies the number of reconnect attempts
before a warning is logged. A logged warning indicates that there is no current
connection but re-connection is being attempted.</p><p>A value of
<strong><code><=0</code></strong> disables the logging of warnings about
reconnect attempts. <strong>Since ActiveMQ 5.10.</strong></p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>reconnectSupported</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Determines whether the client should
respond to broker <strong><code>ConnectionControl</code></strong> events with a
reconnect (see: <strong><code>rebalanceClusterClients</cod
e>).</strong></p></td></tr></tbody></table></div><h5
id="FailoverTransportReference-ExampleURI">Example URI</h5><p> </p><div
class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
<pre>failover:(tcp://localhost:61616,tcp://remotehost:61616)?initialReconnectDelay=100
</pre>
-</div></div><h5 id="FailoverTransportReference-Notes">Notes</h5><p>Under the
Failover transport send operations will, by default, block indefinitely when
the broker becomes unavailable. There are two options available for handling
this scenario. First, either set a <a shape="rect" class="external-link"
href="http://activemq.apache.org/maven/5.5.0/activemq-core/apidocs/org/apache/activemq/transport/TransportListener.html";>TransportListener</a>
directly on the <a shape="rect" class="external-link"
href="http://activemq.apache.org/maven/5.5.0/activemq-core/apidocs/org/apache/activemq/ActiveMQConnectionFactory.html#setTransportListener(org.apache.activemq.transport.TransportListener)">ActiveMQConnectionFactory</a>,
so that it is in place before any request that may require a network hop or
second, set the <strong><code>timeout</code></strong> option. The
<strong><code>timeout</code></strong> option causes the current send operation
to fail after the specified timeout. For example:</p><d
iv class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+</div></div><h5 id="FailoverTransportReference-Notes">Notes</h5><p>Under the
Failover transport send operations will, by default, block indefinitely when
the broker becomes unavailable. There are two options available for handling
this scenario. First, either set a <a shape="rect" class="external-link"
href="http://activemq.apache.org/maven/5.5.0/activemq-core/apidocs/org/apache/activemq/transport/TransportListener.html";>TransportListener</a>
directly on the <a shape="rect" class="external-link"
href="http://activemq.apache.org/maven/5.5.0/activemq-core/apidocs/org/apache/activemq/ActiveMQConnectionFactory.html#setTransportListener(org.apache.activemq.transport.TransportListener)">ActiveMQConnectionFactory</a>,
so that it is in place before any request that may require a network hop or
second, set the <strong><code>timeout</code></strong> option. The
<strong><code>timeout</code></strong> option causes the current send operation
to fail after the specified timeout. For example:</p><p
> </p><div class="preformatted panel" style="border-width: 1px;"><div
>class="preformattedContent panelContent">
<pre>failover:(tcp://primary:61616)?timeout=3000
</pre>
-</div></div><p>In this example if the connection isn't established the send
operation will timeout after 3 seconds. It is important to note that the
connection <em>is not killed</em> when a timeout occurs. It is possible,
therefore, to resend the affected message(s) later using the <em>same</em>
connection once a broker becomes available.</p><h5
id="FailoverTransportReference-Transactions">Transactions</h5><p>The Failover
transport tracks transactions by default. In-flight transactions are replayed
upon re-connection. For simple scenarios this works as expected. However, there
is an assumption regarding acknowledged (or consumer) transactions in that the
previously received messages will automatically be replayed upon re-connection.
This, however, is not always true when there are many connections and
consumers, as re-delivery order is not guaranteed as stale outstanding
acknowledgements can interfere with newly delivered messages. This can lead to
unacknowledged messages.</p><p>Sta
rting in version 5.3.1, however, re-delivery order <em>is</em> tracked and a
transaction will fail to commit if outstanding messages are not redelivered
after failover. A
<strong><code>javax.jms.</code><code>TransactionRolledBackException</code></strong>
is thrown if the commit fails. In doubt transactions will result in a rollback
such that they can be replayed by the application. In doubt transactions occur
when failover happens when a commit message is in-flight. It is not possible to
know the exact point of failure. Did failure happen because the transaction
commit message was not delivered or was the commit reply lost? In either case,
it becomes necessary to rollback the transaction so that the application can
get an indication of the failure and deal with any potential problem.</p><h5
id="FailoverTransportReference-Broker-sideOptionsforFailover">Broker-side
Options for Failover</h5><p><span style="color: red;"><strong><em>This is new
in version 5.4:</em></strong></span></p><p>
The TransportConnector has options available so that the broker can update
clients automatically regarding information of about the presence new brokers
available for failover. The options are:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Option Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default Value</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>updateClusterClients</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>If <strong><code>true</code></strong>, pass
information to connected clients about changes in the topology of the broker
cluster.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>rebalanceClusterClients</code></p></td><td
colspan="1" rowspan="1" class
="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>If <strong><code>true</code></strong>, connected
clients will be asked to re-balance across a cluster of brokers when a new
broker joins the network of brokers
(note: <strong><code>priorityBackup=true</code></strong> can
override).</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>updateClusterClientsOnRemove</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>false</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>If <strong><code>true</code></strong>, will
update clients when a cluster is removed from the network. Having this as
separate option enables clients to be updated when new brokers join, but
<em>not</em> when brokers leave.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>updateClusterFilter</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td
colspan="
1" rowspan="1" class="confluenceTd"><p>Comma separated list of regular
expression filters used to match broker names of brokers to designate as being
part of the failover cluster for the
clients.</p></td></tr></tbody></table></div><p>For example:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>In this example if the connection isn't established the send
operation will timeout after 3 seconds. It is important to note that the
connection <em>is not killed</em> when a timeout occurs. It is possible,
therefore, to resend the affected message(s) later using the <em>same</em>
connection once a broker becomes available.</p><h5
id="FailoverTransportReference-Transactions">Transactions</h5><p>The Failover
transport tracks transactions by default. In-flight transactions are replayed
upon re-connection. For simple scenarios this works as expected. However, there
is an assumption regarding acknowledged (or consumer) transactions in that the
previously received messages will automatically be replayed upon re-connection.
This, however, is not always true when there are many connections and
consumers, as re-delivery order is not guaranteed as stale outstanding
acknowledgements can interfere with newly delivered messages. This can lead to
unacknowledged messages.</p><p>Sta
rting in version 5.3.1, however, re-delivery order <em>is</em> tracked and a
transaction will fail to commit if outstanding messages are not redelivered
after failover. A
<strong><code>javax.jms.</code><code>TransactionRolledBackException</code></strong>
is thrown if the commit fails. In doubt transactions will result in a rollback
such that they can be replayed by the application. In doubt transactions occur
when failover happens when a commit message is in-flight. It is not possible to
know the exact point of failure. Did failure happen because the transaction
commit message was not delivered or was the commit reply lost? In either case,
it becomes necessary to rollback the transaction so that the application can
get an indication of the failure and deal with any potential problem.</p><h5
id="FailoverTransportReference-Broker-sideOptionsforFailover">Broker-side
Options for Failover</h5><p><span style="color: red;"><strong><em>This is new
in version 5.4:</em></strong></span></p><p>
The TransportConnector has options available so that the broker can update
clients automatically regarding information of about the presence new brokers
available for failover. The options are:</p><p> </p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Option Name</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Default Value</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>updateClusterClients</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>If <strong><code>true</code></strong>, pass
information to connected clients about changes in the topology of the broker
cluster.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>rebalanceClusterClients</code></p></td><td
colspan="1" rows
pan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>If <strong><code>true</code></strong>,
connected clients will be asked to re-balance across a cluster of brokers when
a new broker joins the network of brokers
(note: <strong><code>priorityBackup=true</code></strong> can
override).</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>updateClusterClientsOnRemove</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>If
<strong><code>true</code></strong>, will update clients when a cluster is
removed from the network. Having this as separate option enables clients to be
updated when new brokers join, but <em>not</em> when brokers
leave.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>updateClusterFilter</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>null</c
ode></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Comma
separated list of regular expression filters used to match broker names of
brokers to designate as being part of the failover cluster for the
clients.</p></td></tr></tbody></table></div><p>For
example:</p><p> </p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Confluence"
style="font-size:12px;"><broker>
...
<transportConnectors>
@@ -99,16 +99,16 @@
...
</broker>
</pre>
-</div></div><p>If <strong><code>updateClusterClients=true</code></strong>,
then clients only need to be configured with the details of one broker within a
cluster to connect to. For example:</p><div class="preformatted panel"
style="border-width: 1px;"><div class="preformattedContent panelContent">
+</div></div><p>If <strong><code>updateClusterClients=true</code></strong>,
then clients only need to be configured with the details of one broker within a
cluster to connect to. For example:</p><p> </p><div class="preformatted
panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>failover:(tcp://primary:61616)
</pre>
-</div></div><p>when new brokers join the cluster the client is automatically
informed of the new broker's URI. The new URI is then available for failover
when one of the other known brokers becomes unavailable.</p><h6
id="FailoverTransportReference-MoreInformation">More Information</h6><p>Also
check out the following blog entry about using the cluster client updates and
re-balancing features titled <a shape="rect" class="external-link"
href="http://bsnyderblog.blogspot.com/2010/10/new-features-in-activemq-54-automatic.html";
rel="nofollow">New Features in ActiveMQ 5.4: Automatic Cluster Update and
Rebalance</a>.</p><h5 id="FailoverTransportReference-PriorityBackup">Priority
Backup</h5><p>If brokers are available in both local and remote networks, it's
possible to specify a preference for local brokers over remote brokers using
the <strong><code>priorityBackup</code></strong> and
<strong><code>priorityURIs</code></strong> options (since ActiveMQ 5.6).
Consider the following URL:</p><d
iv class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+</div></div><p>when new brokers join the cluster the client is automatically
informed of the new broker's URI. The new URI is then available for failover
when one of the other known brokers becomes unavailable.</p><h6
id="FailoverTransportReference-MoreInformation">More Information</h6><p>Also
check out the following blog entry about using the cluster client updates and
re-balancing features titled <a shape="rect" class="external-link"
href="http://bsnyderblog.blogspot.com/2010/10/new-features-in-activemq-54-automatic.html";
rel="nofollow">New Features in ActiveMQ 5.4: Automatic Cluster Update and
Rebalance</a>.</p><h5 id="FailoverTransportReference-PriorityBackup">Priority
Backup</h5><p>If brokers are available in both local and remote networks, it's
possible to specify a preference for local brokers over remote brokers using
the <strong><code>priorityBackup</code></strong> and
<strong><code>priorityURIs</code></strong> options (since ActiveMQ 5.6).
Consider the following URL:</p><p
> </p><div class="preformatted panel" style="border-width: 1px;"><div
>class="preformattedContent panelContent">
<pre>failover:(tcp://local:61616,tcp://remote:61616)?randomize=false&priorityBackup=true</pre>
-</div></div><p>Given this URL the client will try to connect and stay
connected to the <strong><code>local</code></strong> broker. If
<strong><code>local</code></strong> broker fails, it will of course fail over
to <strong><code>remote</code></strong>. However, as
<strong><code>priorityBackup</code></strong> parameter is used, the client will
constantly try to reconnect to <strong><code> local</code></strong>. Once the
client can do so, the client will re-connect to it without any need for manual
intervention.</p><p>By default, only the first URI in the list is considered
prioritized (local). In most cases this will suffice, but in some cases you can
have multiple "local" URIs. The <strong><code>priorityURIs</code></strong>
option can be used to specify which URIs are considered prioritized. For
example:</p><div class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+</div></div><p>Given this URL the client will try to connect and stay
connected to the <strong><code>local</code></strong> broker. If
<strong><code>local</code></strong> broker fails, it will of course fail over
to <strong><code>remote</code></strong>. However, as
<strong><code>priorityBackup</code></strong> parameter is used, the client will
constantly try to reconnect to <strong><code> local</code></strong>. Once the
client can do so, the client will re-connect to it without any need for manual
intervention.</p><p>By default, only the first URI in the list is considered
prioritized (local). In most cases this will suffice, but in some cases you can
have multiple "local" URIs. The <strong><code>priorityURIs</code></strong>
option can be used to specify which URIs are considered prioritized. For
example:</p><p> </p><div class="preformatted panel" style="border-width:
1px;"><div class="preformattedContent panelContent">
<pre>failover:(tcp://local1:61616,tcp://local2:61616,tcp://remote:61616)?randomize=false&priorityBackup=true&priorityURIs=tcp://local1:61616,tcp://local2:61616</pre>
-</div></div><p>In this case the client will prioritize either
<strong><code>local1</code></strong> or <strong><code>local2</code></strong>
brokers and (re-)connect to them if they are available.</p><h5
id="FailoverTransportReference-ConfiguringNestedURIOptions.">Configuring Nested
URI Options.</h5><p><span style="color: rgb(255,0,0);">As of ActiveMQ
5.9</span> it's possible to specify common URI options by appending them to the
query string of failover URI itself. Common URI options must be prefixed with
<strong><code>'nested.'</code></strong>.  Note that if the same option is
specified as both an individual URI option <em>and</em> a nested option, the
nested option definition takes precedence.</p><p>For example, instead of doing
this:</p><div class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+</div></div><p>In this case the client will prioritize either
<strong><code>local1</code></strong> or <strong><code>local2</code></strong>
brokers and (re-)connect to them if they are available.</p><h5
id="FailoverTransportReference-ConfiguringNestedURIOptions.">Configuring Nested
URI Options.</h5><p><span style="color: rgb(255,0,0);">As of ActiveMQ
5.9</span> it's possible to specify common URI options by appending them to the
query string of failover URI itself. Common URI options must be prefixed with
<strong><code>'nested.'</code></strong>.  Note that if the same option is
specified as both an individual URI option <em>and</em> a nested option, the
nested option definition takes precedence.</p><p>For example, instead of doing
this:</p><p> </p><div class="preformatted panel" style="border-width:
1px;"><div class="preformattedContent panelContent">
<pre>failover:(tcp://broker1:61616?wireFormat.maxInactivityDuration=1000,tcp://broker2:61616?wireFormat.maxInactivityDuration=1000,tcp://broker3:61616?wireFormat.maxInactivityDuration=1000)
</pre>
-</div></div><p>do this:</p><div class="preformatted panel"
style="border-width: 1px;"><div class="preformattedContent panelContent">
+</div></div><p>do this:</p><p> </p><div class="preformatted panel"
style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>failover:(tcp://broker1:61616,tcp://broker2:61616,tcp://broker3:61616)?nested.wireFormat.maxInactivityDuration=1000</pre>
</div></div><p>Any option that can applied to the query string of the
individual URIs is a candidate for use with the
<strong><code>nested</code></strong> option.</p><p> </p><p> </p></div>
</td>
