[jboss-remoting-commits] JBoss Remoting SVN: r5207 - remoting2/branches/2.2/docs/guide/en.
jboss-remoting-commits at lists.jboss.org
jboss-remoting-commits at lists.jboss.org
Wed May 13 00:13:00 EDT 2009
Author: ron.sigal at jboss.com
Date: 2009-05-13 00:13:00 -0400 (Wed, 13 May 2009)
New Revision: 5207
Modified:
remoting2/branches/2.2/docs/guide/en/chap8.xml
Log:
JBREM-1128: Added discussion of "connection identity".
Modified: remoting2/branches/2.2/docs/guide/en/chap8.xml
===================================================================
--- remoting2/branches/2.2/docs/guide/en/chap8.xml 2009-05-13 04:05:31 UTC (rev 5206)
+++ remoting2/branches/2.2/docs/guide/en/chap8.xml 2009-05-13 04:13:00 UTC (rev 5207)
@@ -295,6 +295,51 @@
</orderedlist>
+ <para><emphasis role="bold">Note.</emphasis> As of release 2.2.3, 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>Relevant parameters:</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
@@ -307,5 +352,9 @@
<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
More information about the jboss-remoting-commits
mailing list