Author: ron.sigal(a)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
Show replies by date