In static failover a client is configured to use a failover IRU that lists the URIs of the broker connections the client can use. When establishing a connection, the client randomly chooses a URI from the list and attempts to establish a connection to it. If the connection does not succeed, the client chooses a new URI from the list and tries again. The client will continue cycling through the list until a connection attempt succeeds.
If a client's connection to a broker fails after it has been established, the client will attempt to reconnect to a different broker in the list. Once a connection to a new broker is established, the client will continue to use the new broker until the connection to the new broker is severed.
A failover URI is a composite URI that uses one of the following syntaxes:
failover://
uri1
,...,uriN
failover://(
uri1
,...,uriN
)?TransportOptions
The URI list(
)
is a comma-separated list containing the list of broker endpoint URIs to which the client can
connect. The transport options(uri1
,...,uriN
?
)
specified in the form of a query list, allow you to configure some of the failoiver
behaviors.TransportOptions
The failover protocol supports the transport options described in Table 6.1.
Table 6.1. Failover Transport Options
Option | Default | Description |
---|---|---|
initialReconnectDelay
| 10 | Specifies the number of milliseconds to wait before the first reconnect attempt. |
maxReconnectDelay
| 30000 | Specifies the maximum amount of time, in milliseconds, to wait between reconnect attempts. |
useExponentialBackOff
| true | Specifies whether to use an exponential back-off between reconnect attempts. |
backOffMultiplier
| 2 | Specifies the exponent used in the exponential back-off algorithm. |
maxReconnectAttempts
| -1 | Specifies the maximum number of reconnect attempts before an error is returned to the client. -1 specifies unlimited attempts. 0 specifies that an initial connection attempt is made at start-up, but no attempts to failover over to a secondary broker will be made. |
startupMaxReconnectAttempts
| 0 | Specifies the maximum number of reconnect attempts before an error is returned to the client on the first attempt by the client to start a connection. 0 specifies unlimited attempts. |
randomize
| true | Specifies if a URI is chosen at random from the list. Otherwise, the list is traversed from left to right. |
backup
| false | Specifies if the protocol initializes and holds a second transport connection to enable fast failover. |
timeout
| -1 | Specifies the amount of time, in milliseconds, to wait before sending an error if a new connection is not established. -1 specifies an infinite timeout value. |
trackMessages
| false | Specifies if the protocol keeps a cache of in-flight messages that are flushed to a broker on reconnect. |
maxCacheSize
| 131072 | Specifies the size, in bytes, used for the cache used to track messages. |
updateURIsSupported
| true | Specifies whether the client accepts updates to its list of known URIs from the connected broker. Setting this to false inhibits the client's ability to use dynamic failover. See Dynamic Failover. |
Example 6.1 shows a failover URI that can connect to one of two message brokers.
Example 6.1. Simple Failover URI
failover://(tcp://localhost:61616,tcp://remotehost:61616)?initialReconnectDelay=100