Author: buildbot Date: Fri Dec 18 16:22:03 2015 New Revision: 975882 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 16:22:03 2015 @@ -35,7 +35,7 @@ <link href='http://activemq.apache.org/styles/highlighter/styles/shCore.css' rel='stylesheet' type='text/css' /> <link href='http://activemq.apache.org/styles/highlighter/styles/shThemeEclipse.css' rel='stylesheet' type='text/css' /> <script src='http://activemq.apache.org/styles/highlighter/scripts/shCore.js' type='text/javascript'></script> - <script src='http://activemq.apache.org/styles/highlighter/scripts/shBrushJava.js' type='text/javascript'></script> + <script src='http://activemq.apache.org/styles/highlighter/scripts/shBrushXml.js' type='text/javascript'></script> <script type="text/javascript"> SyntaxHighlighter.defaults['toolbar'] = false; @@ -81,39 +81,36 @@ <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. (We used to call this transport the Reliable transport in ActiveMQ 3).</p><p>The Failover configuration syntax allows you to specify any number of composite uris. The Failover transport randomly chooses one of the composite URI and attempts to establish a connection to it. If it does not succeed or if it subsequently fails, a new connection is established to one of the other uris in the list.</p><h4 id="FailoverTransportReference-ConfigurationSyntax">Configuration Syntax</h4><p><strong>failover:(uri1,...,uriN)?transportOptions</strong><br clear="none"> or<br clear="none"> <strong>failover:uri1,...,uriN</strong></p><p>The failover transport uses random by default which lets you to load balance clients over a number of brokers.</p><p>If you would rather connect to a primary firs t and only connect to a secondary backup broker if the primary is unavailable, turn off randomizing using something like</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&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"> <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>initialReconnectDelay</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>10</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>How long to wait before the first reconnect attempt (in ms)</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>maxReconnectDelay</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>30000</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The maximum amount of time we ever wait between reconnect attempts (in ms)</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>use ExponentialBackOff</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>true</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Should an exponential backoff be used btween reconnect attempts</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>reconnectDelayExponent</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>2.0</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The exponent used in the exponential backoff attempts</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>maxReconnectAttempts</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>-1 | 0</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>From version 5.6 onwards: -1 is default and means retry forever, 0 means don't retry (only try connection once but no retry). <br clear="none" class="atl-forced-newline"> Prior to version 5.6: 0 is default and means retry forever. <br clear="none" class="atl-forced-newline"> All versions: If set to &g t;0, then this is 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>startupMaxReconnectAttempts</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>-1</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>If not 0, 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 the <strong>maxReconnectAttempts</strong> option takes precedence.  A value of -1 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>randomize</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>true</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>use a random algorithm to choose the the URI to use for reconnect from the list provided</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>backup</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>false</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>timeout</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>-1</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Enables timeout on send operations (in miliseconds) without interruption of reconnection process</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>trackMessages</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>false</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>maxCacheSize</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>131072</p></t d><td colspan="1" rowspan="1" class="confluenceTd"><p>size in bytes for the cache, if trackMessages is enabled</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>updateURIsSupported</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>true</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Determines whether the client should accept updates to its list of known URIs from the connected broker. <strong>Added in ActiveMQ 5.4</strong></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>updateURIsURL</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>null</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>Added in ActiveMQ 5.4</strong></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>nested.*</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>null</p>< /td><td colspan="1" rowspan="1" class="confluenceTd"><p>Extra options to add to the nested URLs. <strong>Added in ActiveMQ 5.9</strong></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>warnAfterReconnectAttempts</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>10</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After every N reconnect attempts log a warning to indicate there is no connection but that we are still trying, set to <= 0 to disable. <strong>Added in ActiveMQ 5.10</strong></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd">reconnectSupported</td><td colspan="1" rowspan="1" class="confluenceTd">true</td><td colspan="1" rowspan="1" class="confluenceTd">Determines whether the client should respond to broker ConnectionControl events with a reconnect (see: <span>rebalanceClusterClients)</span></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><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"> <pre>failover:(tcp://localhost:61616,tcp://remotehost:61616)?initialReconnectDelay=100 </pre> -</div></div><p>If the above gives errors try it this way (this way works in ActiveMQ 4.1.1 the one above does not)</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>If you use failover, and a broker dies at some point, your sends will block by default. Using <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> can help with this regard. It is best to set the Listener 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 an network hop.<br clear="none"> Additionally you can use <em>timeout</em> option which will cause your current send to fail after specified timeout. The following URL, for example</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformatt edContent 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><d iv class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> <pre>failover:(tcp://primary:61616)?timeout=3000 </pre> -</div></div><p>will cause send to fail after 3 seconds if the connection isn't established. The connection will not be killed, so you can try sending messages later at some point using the same connection (presumably some of your brokers will be available again). Timeouts on the failover transport are available since 5.3 version.</p><h5 id="FailoverTransportReference-Transactions">Transactions</h5><p>The Failover transport tracks transactions by default. The inflight transactions are replayed on reconnection. For simple scenarios this works ok. However there is an assumption for acknowledged (or consumer) transactions, that the previously received messages will get relayed after a reconnect. This is not always true when there are many connections and consumers, as redelivery order is not guaranteed. It is possible to have stale outstanding acknowledgements that can interfere with newly delivered messages, potentially leading to unacknowledged messages.<br clear="none"> Starting in v ersion 5.3.1, redelivery order is tracked and a transaction will fail to commit (throw a TransactionRolledBackException) if outstanding messages are not redelivered after failover. In addition, in doubt transaction will now result in a rollback such that they can be replayed by the application. In doubt transactions occur when failover happens with a commit message inflight. It is not possible to know the exact point of failure. Did the transaction commit message get delivered or was it just the commit reply that is lost? In this case, it is necessary to rollback so that the application can get an indication of the failure and deal with any potential problem.</p><h5 id="FailoverTransportReference-BrokersideOptionsforFailover">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>There are some options that are available on a TransportConnector that is used by the broker that can be used to update clients automatically with information about new brokers to failover to. These 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>updateClusterClients</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>false</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>if true, 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>rebalanceClusterClients</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>false</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>if true, connected clients will be asked to rebalance across a cluster of brokers when a new broker joins th e network of brokers (note: priorityBackup=true can override)</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>updateClusterClientsOnRemove</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>false</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>if true, 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 not when brokers leave.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>updateClusterFilter</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>null</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>An example as defined within the broker's XML configuration file:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><broker> +</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"> +<pre class="brush: xml; gutter: false; theme: Confluence" style="font-size:12px;"><broker> ... <transportConnectors> - <transportConnector name="openwire" uri="tcp://0.0.0.0:61616" updateClusterClients="true" updateClusterFilter=".*A.*,.*B.*" /> + <transportConnector name="openwire" uri="tcp://0.0.0.0:61616" updateClusterClients="true" updateClusterFilter=".*A.*,.*B.*"/> </<transportConnectors> ... </broker> </pre> -</div></div><p>If updateClusterClients is enabled, then your clients will only need to know about the first broker to connect to in a cluster of brokers - e.g.:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent"> -<pre>failover://tcp://primary:61616 +</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"> +<pre>failover:(tcp://primary:61616) </pre> -</div></div><p>If new brokers join, the client will automatically be updated with the additional URI of that broker to connect to in the event of a network or broker failure.</p><h6 id="FailoverTransportReference-MoreInformation">More Information</h6><p>Also check out the following blog entry about using the cluster client updates and rebalancing 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 your setup have brokers in both local and remote networks, you probably want your clients connected to the local ones if those are available. As of version 5.6, ActiveMQ supports priority backup feature, so you can have your clients automatically reconnect to so called priority (or local) urls. Consider the following url</p><div clas s="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">failover:(tcp://local:61616,tcp://remote:61616)?randomize=false&priorityBackup=true</pre> -</div></div><p>If this url is used for the client, the client will try to connect and stay connected to the <code>local</code> broker. If local broker fails, it will of course fail over to the remote one. But as <code>priorityBackup</code> parameter is used, it will constantly try to reconnect to the local broker. Once it can do so, the client will get back to it without any need for manual intervention.</p><p>By default, only the first url in the list is considered prioritized (local). In most cases this will suffice, but in some cases you can have multiple "local" urls. You can configure which urls are considered prioritized, by using <code>priorityURIs</code> parameter, like</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">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 <code>local1</code> or <code>local2</code> brokers and (re)connect to them if they are available.</p><h5 id="FailoverTransportReference-PassingextraoptionstothenestedURLs.">Passing extra options to the nested URLs.</h5><p><span style="color: red;"><strong><em>This is new in version 5.9:</em></strong></span><br clear="none"> You can now add options the nested URLs via options on the failover URL. Previously, if you wanted to detect dead connections faster you had to add the wireFormat.maxInactivityDuration=1000 option to all the nested URLs in the failover list. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">failover:(tcp://host01:61616?wireFormat.maxInactivityDuration=1000,tcp://host02:61616?wireFormat.maxInactivityDuration=1000,tcp://host03:61616?wireFormat.maxInactivityDuration=1000)</pre> -</div></div><p>As of ActiveMQ 5.9, you can now do the same thing using the following URL:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">failover:(tcp://host01:61616,tcp://host02:61616,tcp://host03:61616)?nested.wireFormat.maxInactivityDuration=1000</pre> -</div></div></div> +</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"> +<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"> +<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"> +<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"> +<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> <td valign="top"> <div class="navigation">