activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r975885 - in /websites/production/activemq/content: cache/main.pageCache failover-transport-reference.html
Date Fri, 18 Dec 2015 17:21:46 GMT
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&amp;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&amp;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>&#160;</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>&gt;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.&#160;</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.&#160;<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>&lt;= 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>&#160;</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>&gt;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&#160; <strong><code>&gt;=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.&#160;<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>&gt;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>&lt;=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>&#160;</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
 >&#160;</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&#160;<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:&#160;<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>&#160;</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&#160;<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:&#160;<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>&#160;</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;">&lt;broker&gt;
   ...
   &lt;transportConnectors&gt;
@@ -99,16 +99,16 @@
   ...
 &lt;/broker&gt;
 </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>&#160;</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
 >&#160;</p><div class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
 <pre>failover:(tcp://local:61616,tcp://remote:61616)?randomize=false&amp;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&#160;<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&#160;<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>&#160;</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&amp;priorityBackup=true&amp;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>.&#160;
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>.&#160;
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>&#160;</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>&#160;</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>&#160;</p><p>&#160;</p></div>
         </td>



Mime
View raw message