The Failover Transport

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).

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.

Configuration Syntax

failover:(uri1,...,uriN)?transportOptions
or
failover:uri1,...,uriN

The failover transport uses random by default which lets you to load balance clients over a number of brokers.

If you would rather connect to a primary first and only connect to a secondary backup broker if the primary is unavailable, turn off randomizing using something like

failover:(tcp://primary:61616,tcp://secondary:61616)?randomize=false
Transport Options

Option Name

Default Value

Description

initialReconnectDelay

10

How long to wait before the first reconnect attempt (in ms)

maxReconnectDelay

30000

The maximum amount of time we ever wait between reconnect attempts (in ms)

useExponentialBackOff

true

Should an exponential backoff be used btween reconnect attempts

reconnectDelayExponent

2.0

The exponent used in the exponential backoff attempts

maxReconnectAttempts

-1 | 0

From version 5.6 onwards: -1 is default and means retry forever, 0 means don't retry (only try connection once but no retry).
Prior to version 5.6: 0 is default and means retry forever.
All versions: If set to >0, then this is the maximum number of reconnect attempts before an error is sent back to the client.

startupMaxReconnectAttempts

0

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 maxReconnectAttempts option takes precedence.

randomize

true

use a random algorithm to choose the the URI to use for reconnect from the list provided

backup

false

initialize and hold a second transport connection - to enable fast failover

timeout

-1

Enables timeout on send operations (in miliseconds) without interruption of reconnection process

trackMessages

false

keep a cache of in-flight messages that will flushed to a broker on reconnect

maxCacheSize

131072

size in bytes for the cache, if trackMessages is enabled

updateURIsSupported

true

Determines whether the client should accept updates to its list of known URIs from the connected broker. Added in ActiveMQ 5.4

updateURIsURL

null

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. Added in ActiveMQ 5.4

nested.*

null

Extra options to add to the nested URLs. Added in ActiveMQ 5.9

warnAfterReconnectAttempts.*

10

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. Added in ActiveMQ 5.10

reconnectSupportedtrueDetermines whether the client should respond to broker ConnectionControl events with a reconnect (see: rebalanceClusterClients)
Example URI
failover:(tcp://localhost:61616,tcp://remotehost:61616)?initialReconnectDelay=100

If the above gives errors try it this way (this way works in ActiveMQ 4.1.1 the one above does not)

failover://(tcp://localhost:61616,tcp://remotehost:61616)?initialReconnectDelay=100
Notes

If you use failover, and a broker dies at some point, your sends will block by default. Using TransportListener can help with this regard. It is best to set the Listener directly on the ActiveMQConnectionFactory so that it is in place before any request that may require an network hop.
Additionally you can use timeout option which will cause your current send to fail after specified timeout. The following URL, for example

failover:(tcp://primary:61616)?timeout=3000

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.

Transactions

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.
Starting in version 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.

Broker side Options for Failover

This is new in version 5.4:

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:

Option Name

Default Value

Description

updateClusterClients

false

if true, pass information to connected clients about changes in the topology of the broker cluster

rebalanceClusterClients

false

if true, connected clients will be asked to rebalance across a cluster of brokers when a new broker joins the network of brokers (note: priorityBackup=true can override)

updateClusterClientsOnRemove

false

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.

updateClusterFilter

null

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

An example as defined within the broker's XML configuration file:

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.:

failover://tcp://primary:61616

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.

More Information

Also check out the following blog entry about using the cluster client updates and rebalancing features titled New Features in ActiveMQ 5.4: Automatic Cluster Update and Rebalance.

Priority Backup

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

If this url is used for the client, the client will try to connect and stay connected to the local broker. If local broker fails, it will of course fail over to the remote one. But as priorityBackup 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.

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 priorityURIs parameter, like

In this case the client will prioritize either local1 or local2 brokers and (re)connect to them if they are available.

Passing extra options to the nested URLs.

This is new in version 5.9:
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:

As of ActiveMQ 5.9, you can now do the same thing using the following URL:

© 2004-2011 The Apache Software Foundation.
Apache ActiveMQ, ActiveMQ, Apache, the Apache feather logo, and the Apache ActiveMQ project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.
Graphic Design By Hiram