src/components/artemis/documentation/latest/client-failover.html - activemq-website - Git at Google

 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="generator" content="Asciidoctor 2.0.18">
 <link rel="icon" type="image/png" href="images/favicon.png">
 <title>Core Client Failover</title>
 <link rel="stylesheet" href="css/asciidoctor.css">
 <link rel="stylesheet" href="css/font-awesome.css">
 </head>
 <body class="book toc2 toc-left">
 <div id="header">
 <h1>Core Client Failover</h1>
 <div id="toc" class="toc2">
 <div id="toctitle"><a href="index.html">User Manual for 2.33.0</a></div>
 <ul class="sectlevel1">
 <li><a href="#reconnect-to-the-same-server">1. Reconnect to the same server</a></li>
 <li><a href="#reconnect-to-the-backup-server">2. Reconnect to the backup server</a></li>
 <li><a href="#reconnect-to-other-active-servers">3. Reconnect to other active servers</a></li>
 <li><a href="#session-reconnection">4. Session reconnection</a></li>
 <li><a href="#failing-over-on-the-initial-connection">5. Failing over on the initial connection</a></li>
 <li><a href="#reconnection-and-failover-attributes">6. Reconnection and failover attributes</a></li>
 <li><a href="#exceptionlisteners-and-sessionfailurelisteners">7. ExceptionListeners and SessionFailureListeners</a></li>
 </ul>
 </div>
 </div>
 <div id="content">
 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph">
 <p>Apache ActiveMQ Artemis clients can be configured to automatically <a href="#reconnect-to-the-same-server">reconnect to the same server</a>, <a href="#reconnect-to-the-backup-server">reconnect to the backup server</a> or <a href="#reconnect-to-other-active-servers">reconnect to other active servers</a> in the event that a failure is detected in the connection between the client and the server.
 The clients detect connection failure when they have not received any packets from the server within the time given by <code>client-failure-check-period</code> as explained in section <a href="connection-ttl.html#detecting-dead-connections">Detecting Dead Connections</a>.</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="reconnect-to-the-same-server"><a class="anchor" href="#reconnect-to-the-same-server"></a><a class="link" href="#reconnect-to-the-same-server">1. Reconnect to the same server</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Set <code>reconnectAttempts</code> to any non-zero value to reconnect to the same server, for further details see <a href="#reconnection-and-failover-attributes">Reconnection and failover attributes</a>.</p>
 </div>
 <div class="paragraph">
 <p>If the disconnection was due to some transient failure such as a temporary network outage and the target server was not restarted, then the sessions will still exist on the server, assuming the client hasn&#8217;t been disconnected for more than <a href="connection-ttl.html#detecting-dead-connections">connection-ttl</a></p>
 </div>
 <div class="paragraph">
 <p>In this scenario, the client sessions will be automatically re-attached to the server sessions after the reconnection.
 This is done 100% transparently and the client can continue exactly as if nothing had happened.</p>
 </div>
 <div class="paragraph">
 <p>The way this works is as follows:</p>
 </div>
 <div class="paragraph">
 <p>As Apache ActiveMQ Artemis clients send commands to their servers they store each sent command in an in-memory buffer.
 In the case that connection failure occurs and the client subsequently reattaches to the same server, as part of the reattachment protocol the server informs the client during reattachment with the id of the last command it successfully received from that client.</p>
 </div>
 <div class="paragraph">
 <p>If the client has sent more commands than were received before failover it can replay any sent commands from its buffer so that the client and server can reconcile their states.Ac</p>
 </div>
 <div class="paragraph">
 <p>The size of this buffer is configured with the <code>confirmationWindowSize</code> parameter on the connection URL.
 When the server has received <code>confirmationWindowSize</code> bytes of commands and processed them it will send back a command confirmation to the client, and the client can then free up space in the buffer.</p>
 </div>
 <div class="paragraph">
 <p>The window is specified in bytes.</p>
 </div>
 <div class="paragraph">
 <p>Setting this parameter to <code>-1</code> disables any buffering and prevents any re-attachment from occurring, forcing reconnect instead.
 The default value for this parameter is <code>-1</code>.
 (Which means by default no auto re-attachment will occur)</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="reconnect-to-the-backup-server"><a class="anchor" href="#reconnect-to-the-backup-server"></a><a class="link" href="#reconnect-to-the-backup-server">2. Reconnect to the backup server</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Set <code>reconnectAttempts</code> to any non-zero value and <code>ha</code> to <code>true</code> to reconnect to the back server, for further details see <a href="#reconnection-and-failover-attributes">Reconnection and failover attributes</a>.</p>
 </div>
 <div class="paragraph">
 <p>The clients can be configured to discover the list of live-backup server groups in a number of different ways.
 They can be configured explicitly or probably the most common way of doing this is to use <em>server discovery</em> for the client to automatically discover the list.
 For full details on how to configure server discovery, please see <a href="clusters.html#clusters">Clusters</a>.
 Alternatively, the clients can explicitly connect to a specific server and download the current servers and backups see <a href="clusters.html#clusters">Clusters</a>.</p>
 </div>
 <div class="paragraph">
 <p>By default, failover will only occur after at least one connection has been made.
 In other words, by default, failover will not occur if the client fails to make an initial connection - in this case it will simply retry connecting according to the reconnect-attempts property and fail after this number of attempts.</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="reconnect-to-other-active-servers"><a class="anchor" href="#reconnect-to-other-active-servers"></a><a class="link" href="#reconnect-to-other-active-servers">3. Reconnect to other active servers</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Set <code>failoverAttempts</code> to any non-zero value to reconnect to other active servers, for further details see <a href="#reconnection-and-failover-attributes">Reconnection and failover attributes</a>.</p>
 </div>
 <div class="paragraph">
 <p>If <code>reconnectAttempts</code> value is not zero then the client will try to reconnect to other active servers only after all attempts to <a href="#reconnect-to-the-same-server">reconnect to the same server</a> or <a href="#reconnect-to-the-backup-server">reconnect to the backup server</a> fail.</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="session-reconnection"><a class="anchor" href="#session-reconnection"></a><a class="link" href="#session-reconnection">4. Session reconnection</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>When clients <a href="#reconnect-to-the-same-server">reconnect to the same server</a> after a restart, <a href="#reconnect-to-the-backup-server">reconnect to the backup server</a> or <a href="#reconnect-to-other-active-servers">reconnect to other active servers</a> any sessions will no longer exist on the server and it won&#8217;t be possible to 100% transparently re-attach to them.
 In this case, any sessions and consumers on the client will be automatically recreated on the server.</p>
 </div>
 <div class="paragraph">
 <p>Client reconnection is also used internally by components such as core bridges to allow them to reconnect to their target servers.</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="failing-over-on-the-initial-connection"><a class="anchor" href="#failing-over-on-the-initial-connection"></a><a class="link" href="#failing-over-on-the-initial-connection">5. Failing over on the initial connection</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Since the client does not learn about the full topology until after the first connection is made there is a window where it does not know about the backup.
 If a failure happens at this point the client can only try reconnecting to the original server.
 To configure how many attempts the client will make you can set the URL parameter <code>initialConnectAttempts</code>.
 The default for this is <code>0</code>, that is try only once.
 Once the number of attempts has been made an exception will be thrown.</p>
 </div>
 <div class="paragraph">
 <p>For examples of automatic failover with transacted and non-transacted JMS sessions, please see <a href="examples.html#examples">the examples</a> chapter.</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="reconnection-and-failover-attributes"><a class="anchor" href="#reconnection-and-failover-attributes"></a><a class="link" href="#reconnection-and-failover-attributes">6. Reconnection and failover attributes</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Client reconnection and failover is configured using the following parameters:</p>
 </div>
 <div class="dlist">
 <dl>
 <dt class="hdlist1">retryInterval</dt>
 <dd>
 <p>This optional parameter determines the period in milliseconds between subsequent reconnection attempts, if the connection to the target server has failed.
 The default value is <code>2000</code> milliseconds.</p>
 </dd>
 <dt class="hdlist1">retryIntervalMultiplier</dt>
 <dd>
 <p>This optional parameter determines a multiplier to apply to the time since the last retry to compute the time to the next retry.</p>
 <div class="paragraph">
 <p>This allows you to implement an <em>exponential backoff</em> between retry attempts.</p>
 </div>
 <div class="paragraph">
 <p>Let&#8217;s take an example:</p>
 </div>
 <div class="paragraph">
 <p>If we set <code>retryInterval</code> to <code>1000</code> ms and we set <code>retryIntervalMultiplier</code> to <code>2.0</code>, then, if the first reconnect attempt fails, we will wait <code>1000</code> ms then <code>2000</code> ms then <code>4000</code> ms between subsequent reconnection attempts.</p>
 </div>
 <div class="paragraph">
 <p>The default value is <code>1.0</code> meaning each reconnect attempt is spaced at equal intervals.</p>
 </div>
 </dd>
 <dt class="hdlist1">maxRetryInterval</dt>
 <dd>
 <p>This optional parameter determines the maximum retry interval that will be used.
 When setting <code>retryIntervalMultiplier</code> it would otherwise be possible that subsequent retries exponentially increase to ridiculously large values.
 By setting this parameter you can set an upper limit on that value.
 The default value is <code>2000</code> milliseconds.</p>
 </dd>
 <dt class="hdlist1">ha</dt>
 <dd>
 <p>This optional parameter determines whether the client will try to reconnect to the backup node when the primary node is not reachable.
 The default value is <code>false</code>.
 For more information on HA, please see <a href="ha.html#high-availability-and-failover">High Availability and Failover</a>.</p>
 </dd>
 <dt class="hdlist1">reconnectAttempts</dt>
 <dd>
 <p>This optional parameter determines the total number of reconnect attempts to make to the current live/backup pair before giving up.
 A value of <code>-1</code> signifies an unlimited number of attempts.
 The default value is <code>0</code>.</p>
 </dd>
 <dt class="hdlist1">failoverAttempts</dt>
 <dd>
 <p>This optional parameter determines the total number of failover attempts to make after a reconnection failure before giving up and shutting down.
 A value of <code>-1</code> signifies an unlimited number of attempts.
 The default value is <code>0</code>.</p>
 </dd>
 </dl>
 </div>
 <div class="paragraph">
 <p>All of these parameters are set on the URL used to connect to the broker.</p>
 </div>
 <div class="paragraph">
 <p>If your client does manage to reconnect but the session is no longer available on the server, for instance if the server has been restarted or it has timed out, then the client won&#8217;t be able to re-attach, and any <code>ExceptionListener</code> or <code>FailureListener</code> instances registered on the connection or session will be called.</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="exceptionlisteners-and-sessionfailurelisteners"><a class="anchor" href="#exceptionlisteners-and-sessionfailurelisteners"></a><a class="link" href="#exceptionlisteners-and-sessionfailurelisteners">7. ExceptionListeners and SessionFailureListeners</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Please note, that when a client reconnects or re-attaches, any registered JMS <code>ExceptionListener</code> or core API <code>SessionFailureListener</code> will be called.</p>
 </div>
 </div>
 </div>
 </div>
 </body>
 </html>
	<!DOCTYPE html>
	<html lang="en">
	<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<meta name="generator" content="Asciidoctor 2.0.18">
	<link rel="icon" type="image/png" href="images/favicon.png">
	<title>Core Client Failover</title>
	<link rel="stylesheet" href="css/asciidoctor.css">
	<link rel="stylesheet" href="css/font-awesome.css">
	</head>
	<body class="book toc2 toc-left">
	<div id="header">
	<h1>Core Client Failover</h1>
	<div id="toc" class="toc2">
	<div id="toctitle"><a href="index.html">User Manual for 2.33.0</a></div>
	<ul class="sectlevel1">
	<li><a href="#reconnect-to-the-same-server">1. Reconnect to the same server</a></li>
	<li><a href="#reconnect-to-the-backup-server">2. Reconnect to the backup server</a></li>
	<li><a href="#reconnect-to-other-active-servers">3. Reconnect to other active servers</a></li>
	<li><a href="#session-reconnection">4. Session reconnection</a></li>
	<li><a href="#failing-over-on-the-initial-connection">5. Failing over on the initial connection</a></li>
	<li><a href="#reconnection-and-failover-attributes">6. Reconnection and failover attributes</a></li>
	<li><a href="#exceptionlisteners-and-sessionfailurelisteners">7. ExceptionListeners and SessionFailureListeners</a></li>
	</ul>
	</div>
	</div>
	<div id="content">
	<div id="preamble">
	<div class="sectionbody">
	<div class="paragraph">
	<p>Apache ActiveMQ Artemis clients can be configured to automatically <a href="#reconnect-to-the-same-server">reconnect to the same server</a>, <a href="#reconnect-to-the-backup-server">reconnect to the backup server</a> or <a href="#reconnect-to-other-active-servers">reconnect to other active servers</a> in the event that a failure is detected in the connection between the client and the server.
	The clients detect connection failure when they have not received any packets from the server within the time given by <code>client-failure-check-period</code> as explained in section <a href="connection-ttl.html#detecting-dead-connections">Detecting Dead Connections</a>.</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="reconnect-to-the-same-server"><a class="anchor" href="#reconnect-to-the-same-server"></a><a class="link" href="#reconnect-to-the-same-server">1. Reconnect to the same server</a></h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Set <code>reconnectAttempts</code> to any non-zero value to reconnect to the same server, for further details see <a href="#reconnection-and-failover-attributes">Reconnection and failover attributes</a>.</p>
	</div>
	<div class="paragraph">
	<p>If the disconnection was due to some transient failure such as a temporary network outage and the target server was not restarted, then the sessions will still exist on the server, assuming the client hasn’t been disconnected for more than <a href="connection-ttl.html#detecting-dead-connections">connection-ttl</a></p>
	</div>
	<div class="paragraph">
	<p>In this scenario, the client sessions will be automatically re-attached to the server sessions after the reconnection.
	This is done 100% transparently and the client can continue exactly as if nothing had happened.</p>
	</div>
	<div class="paragraph">
	<p>The way this works is as follows:</p>
	</div>
	<div class="paragraph">
	<p>As Apache ActiveMQ Artemis clients send commands to their servers they store each sent command in an in-memory buffer.
	In the case that connection failure occurs and the client subsequently reattaches to the same server, as part of the reattachment protocol the server informs the client during reattachment with the id of the last command it successfully received from that client.</p>
	</div>
	<div class="paragraph">
	<p>If the client has sent more commands than were received before failover it can replay any sent commands from its buffer so that the client and server can reconcile their states.Ac</p>
	</div>
	<div class="paragraph">
	<p>The size of this buffer is configured with the <code>confirmationWindowSize</code> parameter on the connection URL.
	When the server has received <code>confirmationWindowSize</code> bytes of commands and processed them it will send back a command confirmation to the client, and the client can then free up space in the buffer.</p>
	</div>
	<div class="paragraph">
	<p>The window is specified in bytes.</p>
	</div>
	<div class="paragraph">
	<p>Setting this parameter to <code>-1</code> disables any buffering and prevents any re-attachment from occurring, forcing reconnect instead.
	The default value for this parameter is <code>-1</code>.
	(Which means by default no auto re-attachment will occur)</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="reconnect-to-the-backup-server"><a class="anchor" href="#reconnect-to-the-backup-server"></a><a class="link" href="#reconnect-to-the-backup-server">2. Reconnect to the backup server</a></h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Set <code>reconnectAttempts</code> to any non-zero value and <code>ha</code> to <code>true</code> to reconnect to the back server, for further details see <a href="#reconnection-and-failover-attributes">Reconnection and failover attributes</a>.</p>
	</div>
	<div class="paragraph">
	<p>The clients can be configured to discover the list of live-backup server groups in a number of different ways.
	They can be configured explicitly or probably the most common way of doing this is to use <em>server discovery</em> for the client to automatically discover the list.
	For full details on how to configure server discovery, please see <a href="clusters.html#clusters">Clusters</a>.
	Alternatively, the clients can explicitly connect to a specific server and download the current servers and backups see <a href="clusters.html#clusters">Clusters</a>.</p>
	</div>
	<div class="paragraph">
	<p>By default, failover will only occur after at least one connection has been made.
	In other words, by default, failover will not occur if the client fails to make an initial connection - in this case it will simply retry connecting according to the reconnect-attempts property and fail after this number of attempts.</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="reconnect-to-other-active-servers"><a class="anchor" href="#reconnect-to-other-active-servers"></a><a class="link" href="#reconnect-to-other-active-servers">3. Reconnect to other active servers</a></h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Set <code>failoverAttempts</code> to any non-zero value to reconnect to other active servers, for further details see <a href="#reconnection-and-failover-attributes">Reconnection and failover attributes</a>.</p>
	</div>
	<div class="paragraph">
	<p>If <code>reconnectAttempts</code> value is not zero then the client will try to reconnect to other active servers only after all attempts to <a href="#reconnect-to-the-same-server">reconnect to the same server</a> or <a href="#reconnect-to-the-backup-server">reconnect to the backup server</a> fail.</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="session-reconnection"><a class="anchor" href="#session-reconnection"></a><a class="link" href="#session-reconnection">4. Session reconnection</a></h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>When clients <a href="#reconnect-to-the-same-server">reconnect to the same server</a> after a restart, <a href="#reconnect-to-the-backup-server">reconnect to the backup server</a> or <a href="#reconnect-to-other-active-servers">reconnect to other active servers</a> any sessions will no longer exist on the server and it won’t be possible to 100% transparently re-attach to them.
	In this case, any sessions and consumers on the client will be automatically recreated on the server.</p>
	</div>
	<div class="paragraph">
	<p>Client reconnection is also used internally by components such as core bridges to allow them to reconnect to their target servers.</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="failing-over-on-the-initial-connection"><a class="anchor" href="#failing-over-on-the-initial-connection"></a><a class="link" href="#failing-over-on-the-initial-connection">5. Failing over on the initial connection</a></h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Since the client does not learn about the full topology until after the first connection is made there is a window where it does not know about the backup.
	If a failure happens at this point the client can only try reconnecting to the original server.
	To configure how many attempts the client will make you can set the URL parameter <code>initialConnectAttempts</code>.
	The default for this is <code>0</code>, that is try only once.
	Once the number of attempts has been made an exception will be thrown.</p>
	</div>
	<div class="paragraph">
	<p>For examples of automatic failover with transacted and non-transacted JMS sessions, please see <a href="examples.html#examples">the examples</a> chapter.</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="reconnection-and-failover-attributes"><a class="anchor" href="#reconnection-and-failover-attributes"></a><a class="link" href="#reconnection-and-failover-attributes">6. Reconnection and failover attributes</a></h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Client reconnection and failover is configured using the following parameters:</p>
	</div>
	<div class="dlist">
	<dl>
	<dt class="hdlist1">retryInterval</dt>
	<dd>
	<p>This optional parameter determines the period in milliseconds between subsequent reconnection attempts, if the connection to the target server has failed.
	The default value is <code>2000</code> milliseconds.</p>
	</dd>
	<dt class="hdlist1">retryIntervalMultiplier</dt>
	<dd>
	<p>This optional parameter determines a multiplier to apply to the time since the last retry to compute the time to the next retry.</p>
	<div class="paragraph">
	<p>This allows you to implement an <em>exponential backoff</em> between retry attempts.</p>
	</div>
	<div class="paragraph">
	<p>Let’s take an example:</p>
	</div>
	<div class="paragraph">
	<p>If we set <code>retryInterval</code> to <code>1000</code> ms and we set <code>retryIntervalMultiplier</code> to <code>2.0</code>, then, if the first reconnect attempt fails, we will wait <code>1000</code> ms then <code>2000</code> ms then <code>4000</code> ms between subsequent reconnection attempts.</p>
	</div>
	<div class="paragraph">
	<p>The default value is <code>1.0</code> meaning each reconnect attempt is spaced at equal intervals.</p>
	</div>
	</dd>
	<dt class="hdlist1">maxRetryInterval</dt>
	<dd>
	<p>This optional parameter determines the maximum retry interval that will be used.
	When setting <code>retryIntervalMultiplier</code> it would otherwise be possible that subsequent retries exponentially increase to ridiculously large values.
	By setting this parameter you can set an upper limit on that value.
	The default value is <code>2000</code> milliseconds.</p>
	</dd>
	<dt class="hdlist1">ha</dt>
	<dd>
	<p>This optional parameter determines whether the client will try to reconnect to the backup node when the primary node is not reachable.
	The default value is <code>false</code>.
	For more information on HA, please see <a href="ha.html#high-availability-and-failover">High Availability and Failover</a>.</p>
	</dd>
	<dt class="hdlist1">reconnectAttempts</dt>
	<dd>
	<p>This optional parameter determines the total number of reconnect attempts to make to the current live/backup pair before giving up.
	A value of <code>-1</code> signifies an unlimited number of attempts.
	The default value is <code>0</code>.</p>
	</dd>
	<dt class="hdlist1">failoverAttempts</dt>
	<dd>
	<p>This optional parameter determines the total number of failover attempts to make after a reconnection failure before giving up and shutting down.
	A value of <code>-1</code> signifies an unlimited number of attempts.
	The default value is <code>0</code>.</p>
	</dd>
	</dl>
	</div>
	<div class="paragraph">
	<p>All of these parameters are set on the URL used to connect to the broker.</p>
	</div>
	<div class="paragraph">
	<p>If your client does manage to reconnect but the session is no longer available on the server, for instance if the server has been restarted or it has timed out, then the client won’t be able to re-attach, and any <code>ExceptionListener</code> or <code>FailureListener</code> instances registered on the connection or session will be called.</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="exceptionlisteners-and-sessionfailurelisteners"><a class="anchor" href="#exceptionlisteners-and-sessionfailurelisteners"></a><a class="link" href="#exceptionlisteners-and-sessionfailurelisteners">7. ExceptionListeners and SessionFailureListeners</a></h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Please note, that when a client reconnects or re-attaches, any registered JMS <code>ExceptionListener</code> or core API <code>SessionFailureListener</code> will be called.</p>
	</div>
	</div>
	</div>
	</div>
	</body>
	</html>