[jboss-remoting-commits] JBoss Remoting SVN: r5228 - remoting2/branches/2.x/docs/guide/en.

[jboss-remoting-commits at lists.jboss.org]

Author: ron.sigal at jboss.com
Date: 2009-05-15 00:38:40 -0400 (Fri, 15 May 2009)
New Revision: 5228

Modified:
   remoting2/branches/2.x/docs/guide/en/chap9.xml
Log:
JBREM-1132: Added discussion about connection identity.

Modified: remoting2/branches/2.x/docs/guide/en/chap9.xml
===================================================================
--- remoting2/branches/2.x/docs/guide/en/chap9.xml	2009-05-15 03:36:50 UTC (rev 5227)
+++ remoting2/branches/2.x/docs/guide/en/chap9.xml	2009-05-15 04:38:40 UTC (rev 5228)
@@ -299,6 +299,49 @@
        
     </orderedlist>
     
+    <para><emphasis role="bold">Note.</emphasis> As of release 2.5.2, an important
+    concept related to connection monitoring, <emphasis>connection identity</emphasis>,
+	is available.  Suppose that leasing is enabled and that a client invoker
+	stops and is replaced by a new client invoker.  If the 
+	replacement occurs quickly, the server side <classname>Lease</classname> may never 
+	miss a ping, in which there is no evidence that anything changed on the client side.
+	That is, the connection is still alive, as far as the server is concerned. That
+	semantics might be perfectly acceptable for some applications, but other 
+	applications might interpret the same events as a connection failure followed by
+	a new connection.  Remoting can be configured to treat a connection as being 
+	defined by a client/server pair, which supports the second category of applications.
+	</para>
+	
+    <para>More specifically, when configured to do so by setting the parameter
+    <code>org.jboss.remoting.Remoting.USE_CLIENT_CONNECTION_IDENTITY</code> (actual value
+    "useClientConnectionIdentity") to "true", Remoting identifies a connection with a
+    <classname>LeasePinger</classname>/<classname>Lease</classname> pair.  A
+    <classname>Client</classname> participates in a connection when it is connected
+    by way of the new method</para>
+    
+    <programlisting>public void connect(ConnectionListener listener, Map metadata) throws Exception;</programlisting>
+    
+    <para>This method serves to connect the <classname>Client</classname> to the server
+    by way of a new or existing client invoker, and it also (1) registers the 
+    <classname>ConnectionListener</classname> with the <classname>Client</classname>'s
+    new or exiting <classname>ConnectionValidator</classname> and (2) registers
+    the <classname>ConnectionValidator</classname> with the client invoker's 
+    <classname>LeasePinger</classname>.  Subsequently, if any
+    <classname>ConnectionValidator</classname> registered with that
+    <classname>LeasePinger</classname> detects a connection failure, it will
+    (if "stopLeaseOnFailure" is "true") stop the <classname>LeasePinger</classname>,
+    and the <classname>LeasePinger</classname> will cause each registered
+    <classname>ConnectionValidator</classname>s to notify each of its
+    registered <classname>ConnectionListener</classname>s of the connection failure.
+    Once the <classname>LeasePinger</classname> has been shut down and all of the
+    notifications have been made, the connection anchored by the 
+    <classname>LeasePinger</classname> is defunct, and the 
+  	associated <classname>Client</classname>'s should be disconnected by a call
+  	to <methodname>Client.disconnect()</methodname>.  If such a <classname>Client</classname>
+  	is reconnected by a call to <methodname>Client.connect()</methodname>, it
+  	will be associated with a new <classname>LeasePinger</classname> and, therefore,
+  	a new connection.</para>
+  	
     <para><emphasis role="bold">TIE_TO_LEASE</emphasis> (actual value
     "tieToLease") - specifies whether <classname>ConnectionValidator</classname>
     should treat the failure of a related lease on the server side as a
@@ -311,5 +354,8 @@
     <classname>org.jboss.remoting.LeasePinger</classname>, if any. The default
     value is "true".</para>
     
+    <para><emphasis role="bold">org.jboss.remoting.Remoting.USE_CLIENT_CONNECTION_IDENTITY</emphasis>
+    (actual value "useClientConnectionIdentity") - tells Remoting to adhere to the
+    new "connection identity" semantics.</para>
   </section>
 </chapter>
\ No newline at end of file