<div class="wiki-content maincontent"><h3>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><p>&#160;</p><structured-macro ac:macro-id="d39731b4-a16a-40b6-929b-c69f97aec3f2" ac:name="info" ac:schema-version="1"><parameter ac:name="title">Configuration Syntax</parameter><rich-text-body><p><code><strong>failover:(uri1,...,uriN)?transportOptions&amp;nestedURIOptions</strong></code></p><p>or</p><p><code><strong>failover:uri1,...,uriN</strong></code></p></rich-text-body></structured-macro><p>&#160;</p><p>Example:<strong><br clear="none"></strong></p><structured-macro ac:macro-id="bc1fc833-6442-4c03-99ba-18b2e895565f" ac:name="noformat" ac:schema-version="1"><plain-text-body>failover:(tcp://localhost:61616,tcp://remotehost:61616)?initialReconnectDelay=100
</plain-text-body></structured-macro><h4>Transport Options</h4><table><tbody><tr><th colspan="1" rowspan="1"><p>Option Name</p></th><th colspan="1" rowspan="1"><p>Default Value</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>backup</code></p></td><td colspan="1" rowspan="1"><p><code>false</code></p></td><td colspan="1" rowspan="1"><p>Initialize and hold a second transport connection - to enable fast failover.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>initialReconnectDelay</code></p></td><td colspan="1" rowspan="1"><p><code>10</code></p></td><td colspan="1" rowspan="1"><p>The delay (in ms) before the <em>first</em> reconnect attempt.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>maxCacheSize</code></p></td><td colspan="1" rowspan="1"><p><code>131072</code></p></td><td colspan="1" rowspan="1"><p>Size in bytes for the cache of tracked messages.</p><p>Applicable only if <strong><code>trackMessages</code></strong> is <strong><code>true</code></strong>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>maxReconnectAttempts</code></p></td><td colspan="1" rowspan="1"><p><code>-1 | 0</code></p></td><td colspan="1" rowspan="1"><p><strong>From ActiveMQ 5.6</strong>: 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"> <strong>Before ActiveMQ 5.6</strong>: default is <strong><code>0</code></strong>, retry forever. <br clear="none" class="atl-forced-newline"> <strong>All ActiveMQ versions</strong>: 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"><p><code>maxReconnectDelay</code></p></td><td colspan="1" rowspan="1"><p><code>30000</code></p></td><td colspan="1" rowspan="1"><p>The maximum delay (in ms) between the <em>second and subsequent</em> reconnect attempts.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>nested.*</code></p></td><td colspan="1" rowspan="1"><p><code>null</code></p></td><td colspan="1" rowspan="1"><p><strong>From ActiveMQ 5.9:</strong> common URI options that will be applied to each URI in the list<strong>.</strong> </p></td></tr><tr><td colspan="1" rowspan="1"><p><code>randomize</code></p></td><td colspan="1" rowspan="1"><p><code>true</code></p></td><td colspan="1" rowspan="1"><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"><p><code>reconnectDelayExponent</code></p></td><td colspan="1" rowspan="1"><p><code>2.0</code></p></td><td colspan="1" rowspan="1"><p>The exponent used during exponential back-off attempts.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>reconnectSupported</code></p></td><td colspan="1" rowspan="1"><p><code>true</code></p></td><td colspan="1" rowspan="1"><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><tr><td colspan="1" rowspan="1"><p><code>startupMaxReconnectAttempts</code></p></td><td colspan="1" rowspan="1"><p><code>-1</code></p></td><td colspan="1" rowspan="1"><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 reconnect attempt.</p><p><strong>Note</strong>: once successfully connected the <code><strong>maxReconnectAttempts</strong></code> option prevails.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>timeout</code></p></td><td colspan="1" rowspan="1"><p><code>-1</code></p></td><td colspan="1" rowspan="1"><p><strong>From ActiveMQ 5.3</strong>: set the timeout on send operations (in ms) without interruption of re-connection process.&#160;</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>trackMessages</code></p></td><td colspan="1" rowspan="1"><p><code>false</code></p></td><td colspan="1" rowspan="1"><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"><p><code>updateURIsSupported</code></p></td><td colspan="1" rowspan="1"><p><code>true</code></p></td><td colspan="1" rowspan="1"><p><strong>From</strong><strong> ActiveMQ 5.4:</strong> determines whether the client should accept updates from the broker to its list of known URIs.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>updateURIsURL</code></p></td><td colspan="1" rowspan="1"><p><code>null</code></p></td><td colspan="1" rowspan="1"><p><strong>From ActiveMQ 5.4:</strong> 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. </p></td></tr><tr><td colspan="1" rowspan="1"><p><code>useExponentialBackOff</code></p></td><td colspan="1" rowspan="1"><p><code>true</code></p></td><td colspan="1" rowspan="1"><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"><p><code>warnAfterReconnectAttempts</code></p></td><td colspan="1" rowspan="1"><p><code>10</code></p></td><td colspan="1" rowspan="1"><p><strong>From ActiveMQ 5.10:</strong> 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.&#160;</p></td></tr></tbody></table><p>&#160;</p><h4>Using Randomize</h4><p>The Failover transport chooses a URI at random 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>.</p><p>Example:</p><structured-macro ac:macro-id="c9a3b254-4e38-4aff-b023-15778e60ef4b" ac:name="noformat" ac:schema-version="1"><plain-text-body>failover:(tcp://primary:61616,tcp://secondary:61616)?randomize=false
</plain-text-body></structured-macro><h5>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" href="http://activemq.apache.org/maven/apidocs/org/apache/activemq/transport/TransportListener.html">TransportListener</a> directly on the <a shape="rect" href="http://activemq.apache.org/maven/apidocs/org/apache/activemq/ActiveMQConnectionFactory.html">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.</p><p>Example:</p><structured-macro ac:macro-id="54687531-328b-49c5-802c-658731fa1711" ac:name="noformat" ac:schema-version="1"><plain-text-body>failover:(tcp://primary:61616)?timeout=3000
</plain-text-body></structured-macro><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>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><strong>From ActiveMQ 5.3.1</strong>: re-delivery order <strong><em>is</em></strong> 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>Broker-side Options for Failover</h5><p><strong>From ActiveMQ 5.4</strong>: the&#160;<strong><code>TransportConnector</code></strong> has options available so that the broker can update clients automatically with information regarding the presence of new brokers that are available (or are no longer available) for failover.</p><p>The options are:</p><table><tbody><tr><th colspan="1" rowspan="1"><p>Option Name</p></th><th colspan="1" rowspan="1"><p>Default Value</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>updateClusterClients</code></p></td><td colspan="1" rowspan="1"><p><code>false</code></p></td><td colspan="1" rowspan="1"><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"><p><code>rebalanceClusterClients</code></p></td><td colspan="1" rowspan="1"><p><code>false</code></p></td><td colspan="1" rowspan="1"><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"><p><code>updateClusterClientsOnRemove</code></p></td><td colspan="1" rowspan="1"><p><code>false</code></p></td><td colspan="1" rowspan="1"><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"><p><code>updateClusterFilter</code></p></td><td colspan="1" rowspan="1"><p><code>null</code></p></td><td colspan="1" rowspan="1"><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><p>Example:</p><structured-macro ac:macro-id="591e8d97-f040-4870-8ac8-9f0577e9b0a2" ac:name="code" ac:schema-version="1"><parameter ac:name="language">xml</parameter><parameter ac:name="theme">Confluence</parameter><plain-text-body>&lt;broker&gt;
  ...
  &lt;transportConnectors&gt;
    &lt;transportConnector name="openwire" uri="tcp://0.0.0.0:61616" updateClusterClients="true" updateClusterFilter=".*A.*,.*B.*"/&gt;
  &lt;/&lt;transportConnectors&gt;
  ...
&lt;/broker&gt;
</plain-text-body></structured-macro><p>When <strong><code>updateClusterClients=true</code></strong> clients need only be configured with the details of one broker in a cluster in order to connect.</p><p>Example:</p><structured-macro ac:macro-id="99da95ca-95f9-4ecc-827e-61a16fab74e9" ac:name="noformat" ac:schema-version="1"><plain-text-body>failover:(tcp://primary:61616)
</plain-text-body></structured-macro><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><structured-macro ac:macro-id="0462312a-5b88-4989-aeb3-50ea736dce4e" ac:name="info" ac:schema-version="1"><parameter ac:name="title">Additional Information</parameter><rich-text-body>See the following blog entry about using the cluster client updates and re-balancing features titled <a shape="rect" href="http://bsnyderblog.blogspot.com/2010/10/new-features-in-activemq-54-automatic.html">New Features in ActiveMQ 5.4: Automatic Cluster Update and Rebalance</a>.</rich-text-body></structured-macro><h5>Priority Backup</h5><p><strong>From ActiveMQ 5.6</strong>: 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.</p><p>Consider the following URL:</p><structured-macro ac:macro-id="90acedcc-f375-42b7-9768-744527d3cd9b" ac:name="noformat" ac:schema-version="1"><plain-text-body>failover:(tcp://local:61616,tcp://remote:61616)?randomize=false&amp;priorityBackup=true</plain-text-body></structured-macro><p>Given this URL a 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 (<strong><code>local</code></strong>). In most cases this will suffice. However, in some cases it may be necessary to have multiple "local" URIs. The <strong><code>priorityURIs</code></strong> option can be used to specify which URIs are considered prioritized.</p><p>Example:</p><structured-macro ac:macro-id="e7114c68-8a0d-467e-af8f-f0cd720513ed" ac:name="noformat" ac:schema-version="1"><plain-text-body>failover:(tcp://local1:61616,tcp://local2:61616,tcp://remote:61616)?randomize=false&amp;priorityBackup=true&amp;priorityURIs=tcp://local1:61616,tcp://local2:61616</plain-text-body></structured-macro><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>Configuring Nested URI Options.</h5><p><span style="color: rgb(255,0,0);"><span style="color: rgb(0,0,0);"><strong>From ActiveMQ 5.9</strong></span></span>: common URI options can be configured by appending them to the query string of the failover URI where each common URI option has the prefix: <strong><code>nested.</code></strong>&#160;</p><p>Example - instead of doing this:</p><structured-macro ac:macro-id="bb73f89c-526b-4c8b-8c13-740e6921273c" ac:name="noformat" ac:schema-version="1"><plain-text-body>failover:(tcp://broker1:61616?wireFormat.maxInactivityDuration=1000,tcp://broker2:61616?wireFormat.maxInactivityDuration=1000,tcp://broker3:61616?wireFormat.maxInactivityDuration=1000) </plain-text-body></structured-macro><p>do this:</p><structured-macro ac:macro-id="e4f99a01-55da-44f7-8af7-743e32eb9107" ac:name="noformat" ac:schema-version="1"><plain-text-body>failover:(tcp://broker1:61616,tcp://broker2:61616,tcp://broker3:61616)?nested.wireFormat.maxInactivityDuration=1000</plain-text-body></structured-macro><structured-macro ac:macro-id="9c23d901-5052-481c-aeac-02971ab370cf" ac:name="info" ac:schema-version="1"><rich-text-body>Any option that can applied to the query string of an individual URI is a candidate for use with the <strong><code>nested</code></strong> option.</rich-text-body></structured-macro><structured-macro ac:macro-id="49f2ce50-8238-4833-a982-e54504803684" ac:name="warning" ac:schema-version="1"><parameter ac:name="title">Option Precedence</parameter><rich-text-body>If the same option is specified as both an individual URI option <em>and</em> as a nested option, the nested option definition will take precedence.</rich-text-body></structured-macro><p>&#160;</p><p>&#160;</p><p>&#160;</p><p>&#160;</p></div>