[hornetq-commits] JBoss hornetq SVN: r8560 - in trunk/docs/user-manual: en and 1 other directory.
do-not-reply at jboss.org
do-not-reply at jboss.org
Fri Dec 4 11:53:46 EST 2009
Author: timfox
Date: 2009-12-04 11:53:46 -0500 (Fri, 04 Dec 2009)
New Revision: 8560
Removed:
trunk/docs/user-manual/en/command-buffering.xml
Modified:
trunk/docs/user-manual/en/client-reconnection.xml
trunk/docs/user-manual/en/configuration-index.xml
trunk/docs/user-manual/en/master.xml
trunk/docs/user-manual/user-manual.xpr
Log:
more docs changes
Modified: trunk/docs/user-manual/en/client-reconnection.xml
===================================================================
--- trunk/docs/user-manual/en/client-reconnection.xml 2009-12-04 16:33:18 UTC (rev 8559)
+++ trunk/docs/user-manual/en/client-reconnection.xml 2009-12-04 16:53:46 UTC (rev 8560)
@@ -17,69 +17,105 @@
<!-- permitted by applicable law. -->
<!-- ============================================================================= -->
<chapter id="client-reconnection">
- <title>Client Reconnection</title>
+ <title>Client Reconnection and Session Reattachment</title>
<para>HornetQ clients can be configured to automatically reconnect or re-attach to the server in
the event that a failure is detected in the connection between the client and the server. </para>
- <para>If the failure was due to some transient failure such as a temporary network failure, and
- the target server was not restarted, then the sessions will still be existent on the server,
- asssuming the client hasn't been disconnected for more than connection-ttl.</para>
- <para>In this scenario, HornetQ will automatically re-attach the client sessions to the server
- sessions when the connection reconnects. This is done 100% transparently and the client can
- continue exactly as if nothing had happened.</para>
- <para>Alternatively, the server might have actually been restarted after crashing or being
- stopped. In this case any sessions will no longer be existent on the server and it won't be
- possible to automatically re-attach to them.</para>
- <para>In this case, HornetQ will automatically reconnect the connection and recreate any
- sessions and consumers on the server corresponding to the sessions and consumers on the
- client. This process is exactly the same as what happens during failover onto a backup
- server.</para>
- <para>Please see the section on failover <xref linkend="ha.automatic.failover"/> to get a full
- understanding of how transacted and non-transacted sessions are reconnected during
- failover/reconnect.</para>
- <para>Client reconnection is also used internally by components such as core bridges to allow
- them to reconnect to their target servers.</para>
- <para>Client reconnection is configured using the following parameters:</para>
- <itemizedlist>
- <listitem>
- <para><literal>retry-interval</literal>. 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 <literal>2000</literal>
- milliseconds.</para>
- </listitem>
- <listitem>
- <para><literal>retry-interval-multiplier</literal>. This optional parameter determines
- determines a multiplier to apply to the time since the last retry to compute the
- time to the next retry.</para>
- <para>This allows you to implement an <emphasis>exponential backoff</emphasis> between
- retry attempts.</para>
- <para>Let's take an example:</para>
- <para>If we set <literal>retry-interval</literal> to <literal>1000</literal> ms and we
- set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>, then, if
- the first reconnect attempt fails, we will wait <literal>1000</literal> ms then
- <literal>2000</literal> ms then <literal>4000</literal> ms between subsequent
- reconnection attempts.</para>
- <para>The default value is <literal>1.0</literal> meaning each reconnect attempt is
- spaced at equal intervals.</para>
- </listitem>
- <listitem>
- <para><literal>max-retry-interval</literal>. This optional parameter determines the
- maximum retry interval that will be used. When setting <literal
- >retry-interval-multiplier</literal> 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
- <literal>2000</literal> milliseconds.</para>
- </listitem>
- <listitem>
- <para><literal>reconnect-attempts</literal>. This optional parameter determines the
- total number of reconnect attempts to make before giving up and shutting down. A
- value of <literal>-1</literal> signifies an unlimited number of attempts. The
- default value is <literal>0</literal>.</para>
- </listitem>
- </itemizedlist>
- <para>If you're using JMS, and you're using the JMS Service on the server to load your JMS
- connection factory instances directly into JNDI, then you can specify these parameters in
- the xml configuration in <literal>hornetq-jms.xml</literal>, for example:</para>
- <programlisting>
+ <section>
+ <title>100% Transparent session re-attachment</title>
+ <para>If the failure was due to some transient failure such as a temporary network failure,
+ and the target server was not restarted, then the sessions will still be existent on the
+ server, asssuming the client hasn't been disconnected for more than connection-ttl <xref
+ linkend="connection-ttl"/>.</para>
+ <para>In this scenario, HornetQ will automatically re-attach the client sessions to the
+ server sessions when the connection reconnects. This is done 100% transparently and the
+ client can continue exactly as if nothing had happened.</para>
+ <para>The way this works is as follows:</para>
+ <para>As HornetQ 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.</para>
+ <para>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.</para>
+ <para>The size of this buffer is configured by the <literal>ConfirmationWindowSize</literal>
+ parameter, when the server has received <literal>ConfirmationWindowSize</literal> 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.</para>
+ <para>If you are using JMS and you're using the JMS service on the server to load your JMS
+ connection factory instances into JNDI then this parameter can be configured in <literal
+ >hornetq-jms.xml</literal> using the element <literal
+ >confirmation-window-size</literal> a. If you're using JMS but not using JNDI then
+ you can set these values directly on the <literal>HornetQConnectionFactory</literal>
+ instance using the appropriate setter method.</para>
+ <para>If you're using core you can set these values directly on the <literal
+ >ClientSessionFactory</literal> instance using the appropriate setter method.</para>
+ <para>The window is specified in bytes, and has a default value of <literal
+ >1MiB</literal>.</para>
+ <para>Setting this parameter to <literal>-1</literal> disables any buffering and prevents
+ any re-attachment from occurring, forcing reconnect instead. The default value for this
+ parameter is <literal>-1</literal>.</para>
+ </section>
+ <section>
+ <title>Session reconnection</title>
+ <para>Alternatively, the server might have actually been restarted after crashing or being
+ stopped. In this case any sessions will no longer be existent on the server and it won't
+ be possible to 100% transparently re-attach to them.</para>
+ <para>In this case, HornetQ will automatically reconnect the connection and <emphasis
+ role="italic">recreate</emphasis> any sessions and consumers on the server
+ corresponding to the sessions and consumers on the client. This process is exactly the
+ same as what happens during failover onto a backup server.</para>
+ <para>Client reconnection is also used internally by components such as core bridges to
+ allow them to reconnect to their target servers.</para>
+ <para>Please see the section on failover <xref linkend="ha.automatic.failover"/> to get a
+ full understanding of how transacted and non-transacted sessions are reconnected during
+ failover/reconnect and what you need to do to maintain <emphasis role="italic">once and
+ only once </emphasis>delivery guarantees.</para>
+ </section>
+ <section>
+ <title>Configuring reconnection/reattachment attributes</title>
+ <para>Client reconnection is configured using the following parameters:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>retry-interval</literal>. 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 <literal
+ >2000</literal> milliseconds.</para>
+ </listitem>
+ <listitem>
+ <para><literal>retry-interval-multiplier</literal>. This optional parameter
+ determines determines a multiplier to apply to the time since the last retry to
+ compute the time to the next retry.</para>
+ <para>This allows you to implement an <emphasis>exponential backoff</emphasis>
+ between retry attempts.</para>
+ <para>Let's take an example:</para>
+ <para>If we set <literal>retry-interval</literal> to <literal>1000</literal> ms and
+ we set <literal>retry-interval-multiplier</literal> to <literal>2.0</literal>,
+ then, if the first reconnect attempt fails, we will wait <literal>1000</literal>
+ ms then <literal>2000</literal> ms then <literal>4000</literal> ms between
+ subsequent reconnection attempts.</para>
+ <para>The default value is <literal>1.0</literal> meaning each reconnect attempt is
+ spaced at equal intervals.</para>
+ </listitem>
+ <listitem>
+ <para><literal>max-retry-interval</literal>. This optional parameter determines the
+ maximum retry interval that will be used. When setting <literal
+ >retry-interval-multiplier</literal> 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 <literal>2000</literal> milliseconds.</para>
+ </listitem>
+ <listitem>
+ <para><literal>reconnect-attempts</literal>. This optional parameter determines the
+ total number of reconnect attempts to make before giving up and shutting down. A
+ value of <literal>-1</literal> signifies an unlimited number of attempts. The
+ default value is <literal>0</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ <para>If you're using JMS, and you're using the JMS Service on the server to load your JMS
+ connection factory instances directly into JNDI, then you can specify these parameters
+ in the xml configuration in <literal>hornetq-jms.xml</literal>, for example:</para>
+ <programlisting>
<connection-factory name="ConnectionFactory">
<connectors>
<connector-ref connector-name="netty"/>
@@ -94,23 +130,23 @@
<reconnect-attempts>1000</reconnect-attempts>
</connection-factory>
</programlisting>
- <para>If you're using JMS, but instantiating your JMS connection factory directly, you can
- specify the parameters using the appropriate setter methods on the <literal
- >HornetQConnectionFactory</literal> immediately after creating it.</para>
- <para>If you're using the core API and instantiating the <literal>ClientSessionFactory</literal>
- instance directly you can also specify the parameters using the appropriate setter methods
- on the <literal>ClientSessionFactory</literal> immediately after creating it.</para>
- <para>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 <literal>ExceptionListener</literal> or <literal
- >FailureListener</literal> instances registered on the connection or session will be
- called.</para>
+ <para>If you're using JMS, but instantiating your JMS connection factory directly, you can
+ specify the parameters using the appropriate setter methods on the <literal
+ >HornetQConnectionFactory</literal> immediately after creating it.</para>
+ <para>If you're using the core API and instantiating the <literal
+ >ClientSessionFactory</literal> instance directly you can also specify the
+ parameters using the appropriate setter methods on the <literal
+ >ClientSessionFactory</literal> immediately after creating it.</para>
+ <para>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 <literal>ExceptionListener</literal> or
+ <literal>FailureListener</literal> instances registered on the connection or session
+ will be called.</para>
+ </section>
<section id="client-reconnection.exceptionlistener">
<title>ExceptionListeners and SessionFailureListeners</title>
-
-
- <para>Please note, that when a client reconnects or re-attaches, any registered JMS <literal
- >ExceptionListener</literal> or core API <literal>SessionFailureListener</literal> will
- be called.</para>
+ <para>Please note, that when a client reconnects or re-attaches, any registered JMS <literal
+ >ExceptionListener</literal> or core API <literal>SessionFailureListener</literal>
+ will be called.</para>
</section>
</chapter>
Deleted: trunk/docs/user-manual/en/command-buffering.xml
===================================================================
--- trunk/docs/user-manual/en/command-buffering.xml 2009-12-04 16:33:18 UTC (rev 8559)
+++ trunk/docs/user-manual/en/command-buffering.xml 2009-12-04 16:53:46 UTC (rev 8560)
@@ -1,50 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- ============================================================================= -->
-<!-- Copyright © 2009 Red Hat, Inc. and others. -->
-<!-- -->
-<!-- The text of and illustrations in this document are licensed by Red Hat under -->
-<!-- a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). -->
-<!-- -->
-<!-- An explanation of CC-BY-SA is available at -->
-<!-- -->
-<!-- http://creativecommons.org/licenses/by-sa/3.0/. -->
-<!-- -->
-<!-- In accordance with CC-BY-SA, if you distribute this document or an adaptation -->
-<!-- of it, you must provide the URL for the original version. -->
-<!-- -->
-<!-- Red Hat, as the licensor of this document, waives the right to enforce, -->
-<!-- and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent -->
-<!-- permitted by applicable law. -->
-<!-- ============================================================================= -->
-<chapter id="command-buffering">
- <title>Command Buffering</title>
- <para>As HornetQ 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
- reconnects to the same server or fails over onto a backup server, as part of the
- reconnection protocol the server informs the client during reconnection with the id of the
- last command it successfully received from that client.</para>
- <para>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.</para>
- <para>The size of this buffer is configured by the <literal>ProducerWindowSize</literal>
- parameter, when the server has received <literal>ProducerWindowSize</literal> 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.</para>
- <para>If you are using JMS and you're using the JMS service on the server to load your JMS
- connection factory instances into JNDI then this parameter can be configured in <literal
- >hornetq-jms.xml</literal> using the element <literal>confirmation-window-size</literal> a.
- If you're using JMS but not using JNDI then you can set these values directly on the
- <literal>HornetQConnectionFactory</literal> instance using the appropriate setter
- method.</para>
- <para>If you're using core you can set these values directly on the <literal
- >ClientSessionFactory</literal> instance using the appropriate setter method.</para>
- <para>The send window is specified in bytes, and has a default value of <literal
- >1MiB</literal>.</para>
- <para>When the send buffer becomes full, any attempts to send more commands from the client will
- block until the client receives a confirmation from the server and clears out the buffer.
- Because of the blocking, the command buffer performs a type of <literal>flow
- control</literal>, preventing the client from overwhelming the server with
- commands.</para>
- <para>Setting this parameter to <literal>-1</literal> disables any flow control on
- sending.</para>
-</chapter>
Modified: trunk/docs/user-manual/en/configuration-index.xml
===================================================================
--- trunk/docs/user-manual/en/configuration-index.xml 2009-12-04 16:33:18 UTC (rev 8559)
+++ trunk/docs/user-manual/en/configuration-index.xml 2009-12-04 16:53:46 UTC (rev 8560)
@@ -985,10 +985,17 @@
<entry>-1</entry>
</row>
<row>
- <entry><link linkend="command-buffering"
+ <entry><link linkend="client-reconnection"
+ >connection-factory.producer-window-size</link></entry>
+ <entry>Integer</entry>
+ <entry>the window size in bytes for producers sending messages</entry>
+ <entry>1024 * 1024</entry>
+ </row>
+ <row>
+ <entry><link linkend="client-reconnection"
>connection-factory.confirmation-window-size</link></entry>
<entry>Integer</entry>
- <entry>the window size (in bytes) for sending messages</entry>
+ <entry>the window size (in bytes) for reattachment confirmations</entry>
<entry>1024 * 1024</entry>
</row>
<row>
Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml 2009-12-04 16:33:18 UTC (rev 8559)
+++ trunk/docs/user-manual/en/master.xml 2009-12-04 16:53:46 UTC (rev 8560)
@@ -34,8 +34,7 @@
<!ENTITY embedding-hornetq SYSTEM "embedding-hornetq.xml">
<!ENTITY examples SYSTEM "examples.xml">
<!ENTITY filter-expressions SYSTEM "filter-expressions.xml">
- <!ENTITY flow-control SYSTEM "flow-control.xml">
- <!ENTITY command-buffering SYSTEM "command-buffering.xml">
+ <!ENTITY flow-control SYSTEM "flow-control.xml">
<!ENTITY ha SYSTEM "ha.xml">
<!ENTITY transaction-config SYSTEM "transaction-config.xml">
<!ENTITY intercepting-operations SYSTEM "intercepting-operations.xml">
@@ -96,7 +95,6 @@
&connection-ttl;
&transaction-config;
&flow-control;
- &command-buffering;
&send-guarantees;
&undelivered-messages;
&message-expiry;
Modified: trunk/docs/user-manual/user-manual.xpr
===================================================================
--- trunk/docs/user-manual/user-manual.xpr 2009-12-04 16:33:18 UTC (rev 8559)
+++ trunk/docs/user-manual/user-manual.xpr 2009-12-04 16:53:46 UTC (rev 8560)
@@ -18,7 +18,6 @@
<file name="en/client-classpath.xml"/>
<file name="en/client-reconnection.xml"/>
<file name="en/clusters.xml"/>
- <file name="en/command-buffering.xml"/>
<file name="en/configuration-index.xml"/>
<file name="en/configuring-transports.xml"/>
<file name="en/connection-ttl.xml"/>
More information about the hornetq-commits
mailing list