[jboss-cvs] JBossRemoting/docs/guide/en ...
Tom Elrod
tom.elrod at jboss.com
Thu Sep 21 23:31:39 EDT 2006
User: telrod
Date: 06/09/21 23:31:39
Modified: docs/guide/en chap8.xml
Log:
JBREM-602 - updated leasing doc for how to disable leasing.
Revision Changes Path
1.4 +126 -112 JBossRemoting/docs/guide/en/chap8.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap8.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap8.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- chap8.xml 2 Aug 2006 07:17:34 -0000 1.3
+++ chap8.xml 22 Sep 2006 03:31:39 -0000 1.4
@@ -1,4 +1,5 @@
- <chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
<title>Connection Exception Listeners and Leasing</title>
<bridgehead>Client side</bridgehead>
@@ -8,16 +9,16 @@
detected, even when the client is idle.</para>
<para>The only requirement is to implement the
- <code>org.jboss.remoting.ConnectionListener</code> interface, which has
- only one method:</para>
+ <code>org.jboss.remoting.ConnectionListener</code> interface, which has only
+ one method:</para>
<programlisting>public void handleConnectionException(Throwable throwable, Client client)</programlisting>
<para>Then call the <code>addConnectionListener(ConnectionListener
- listener)</code> method on the Client class and pass your listener
- instance. Can also call <code>addConnectionListener(ConnectionListener
- listener, int pingPeriod)</code> if want to specify how frequently wish to
- ping server.</para>
+ listener)</code> method on the Client class and pass your listener instance.
+ Can also call <code>addConnectionListener(ConnectionListener listener, int
+ pingPeriod)</code> if want to specify how frequently wish to ping
+ server.</para>
<para>Currently, the Client will use the
<code>org.jboss.remoting.ConnectionValidator</code> class to handle the
@@ -29,28 +30,28 @@
<bridgehead>Server side</bridgehead>
<para>A remoting server also has the capability to detect when a client is
- no longer available. This is done by estabilishing a lease with the
- remoting clients that connect to a server.</para>
+ no longer available. This is done by estabilishing a lease with the remoting
+ clients that connect to a server.</para>
<para>To turn on server side connection failure detection of remoting
clients, will need to satisfy two criteria. The first is that the client
- lease period is set and is a value greater than 0. The value is
- represented in milliseconds. The client lease period can be set by either
- the 'clientLeasePeriod' attribute within the Connector configuration or by
+ lease period is set and is a value greater than 0. The value is represented
+ in milliseconds. The client lease period can be set by either the
+ 'clientLeasePeriod' attribute within the Connector configuration or by
calling the:<programlisting>public void setLeasePeriod(long leasePeriodValue)</programlisting>method
within Connector. The second criterion is that an implementation of the
<code>org.jboss.remoting.ConnectionListener</code> interface is added as a
connection listener to the Connector, via the method:<programlisting>public void addConnectionListener(ConnectionListener listener)</programlisting>Note,
there is no way to set the connection listener via xml based configuration
- for the Connector. Once both criteria are met, the remoting server will
- turn on client leasing.</para>
+ for the Connector. Once both criteria are met, the remoting server will turn
+ on client leasing.</para>
<para>The ConnectionListener will be notified of both client failures and
- client disconnects via the handleConnectionException() method. If the
- client failed, meaning its lease was not renewed within configured time
- period, the first parameter to the handleConnectionException() method will
- be null. If the client disconnected in a regular manner, the first
- parameter to the handleConnectionException() method will be of type
+ client disconnects via the handleConnectionException() method. If the client
+ failed, meaning its lease was not renewed within configured time period, the
+ first parameter to the handleConnectionException() method will be null. If
+ the client disconnected in a regular manner, the first parameter to the
+ handleConnectionException() method will be of type
ClientDisconnectedException (which indicates a normal termination). Note,
the client's lease will be renewed on the server with any and every
invocation made on the server from the client, whether it be a normal
@@ -58,55 +59,68 @@
<para>The actual lease window established on the server side is dynamic
based the rate at which the client updates its lease. In particular, the
- lease window will always be set to lease period * 2 for any lease that
- does not have a lease update duration that is longer than 75% of the lease
- window (meaning if set lease period to 10 seconds and always update that
- lease in less then 7.5 seconds, the lease period will always remain 10
- seconds). If the update duration is greater than 75% of the lease window,
- the lease window will be reset to the lease duration X 2 (meaning if set
- lease period to 10 seconds and update that lease in 8 seconds, the new
- lease window will be set to 16 seconds). Also, the lease will not
- immediately expire on the first lease timeout (meaning did not get an
- update within the lease window). It takes two consecutive timeouts before
- a lease will expire and a notification for client connection failure is
- fired. This essentially means that the time it will take before a
- connection listener is notified of a client connection failure will be at
- least 4 X lease period (no exceptions).</para>
+ lease window will always be set to lease period * 2 for any lease that does
+ not have a lease update duration that is longer than 75% of the lease window
+ (meaning if set lease period to 10 seconds and always update that lease in
+ less then 7.5 seconds, the lease period will always remain 10 seconds). If
+ the update duration is greater than 75% of the lease window, the lease
+ window will be reset to the lease duration X 2 (meaning if set lease period
+ to 10 seconds and update that lease in 8 seconds, the new lease window will
+ be set to 16 seconds). Also, the lease will not immediately expire on the
+ first lease timeout (meaning did not get an update within the lease window).
+ It takes two consecutive timeouts before a lease will expire and a
+ notification for client connection failure is fired. This essentially means
+ that the time it will take before a connection listener is notified of a
+ client connection failure will be at least 4 X lease period (no
+ exceptions).</para>
<para>By default, the client is not configured to do client leasing. This
- means if want to allow client to do leasing, will need to either
- set invoker locator parameter of 'leasing' to true or include
- configuration entry with key of 'enableLease' and value of true to the map
- passed when creating a Client instance. This does not mean that client
- will lease for sure, but will indicate the client should call on the
- server to see if the server has activated leasing and get the leasing
- period desired by the server. If leasing turned on within the client can
- also override the lease period it will use, ignoring the one sent by the
- server, by setting 'lease_period' parameter in the invoker locator
- parameters to millisecond value. Also worth noting is that if the client
- and server are local, meaning running within the jvm, leasing (and thus
- connection notification) will not be activated, even if is configured to
- do so.</para>
+ means if want to allow client to do leasing, will need to either set invoker
+ locator parameter of 'leasing' to true or include configuration entry with
+ key of 'enableLease' and value of true to the map passed when creating a
+ Client instance. This does not mean that client will lease for sure, but
+ will indicate the client should call on the server to see if the server has
+ activated leasing and get the leasing period desired by the server. If
+ leasing turned on within the client can also override the lease period it
+ will use, ignoring the one sent by the server, by setting 'lease_period'
+ parameter in the invoker locator parameters to millisecond value. Also worth
+ noting is that if the client and server are local, meaning running within
+ the jvm, leasing (and thus connection notification) will not be activated,
+ even if is configured to do so.</para>
<para>If leasing is turned on within the client side, there is no API or
configuration changes needed, unless want to override as mentioned
- previously. When the client initially connects to the server, it will
- check to see if client leasing is turned on by the server. If it is, it
- will internally start pinging periodically to the server to maintain the
- lease. When the client disconnects, it will internally send message to the
- server to stop monitoring lease for this client. Therefore, it is
- <emphasis role="bold">IMPORTANT</emphasis> that disconnect is called on
- the client when done using it. Otherwise, the client will continue to make
- its ping call on the server to keep its lease current. </para>
-
- <para>The client can also provide extra metadata the will be communicated
- to the connection listener in case of failure by supplying a metadata Map
- to the Client constructor. This map will be included in the Client
- instance passed to the connection listener (via the
- handleConnectionException() method) via the Client's getConfiguration()
- method.</para>
+ previously. When the client initially connects to the server, it will check
+ to see if client leasing is turned on by the server. If it is, it will
+ internally start pinging periodically to the server to maintain the lease.
+ When the client disconnects, it will internally send message to the server
+ to stop monitoring lease for this client. Therefore, it is <emphasis
+ role="bold">IMPORTANT</emphasis> that disconnect is called on the client
+ when done using it. Otherwise, the client will continue to make its ping
+ call on the server to keep its lease current.</para>
+
+ <para>The client can also provide extra metadata the will be communicated to
+ the connection listener in case of failure by supplying a metadata Map to
+ the Client constructor. This map will be included in the Client instance
+ passed to the connection listener (via the handleConnectionException()
+ method) via the Client's getConfiguration() method.</para>
+
+ <para>From the server side, there are two ways in which to disable leasing
+ (i.e. turn leasing off). The first is to call:</para>
+
+ <programlisting>public void removeConnectionListener(ConnectionListener listener)</programlisting>
+
+ <para>and remove all the registered ConnectionListeners. Once the last one
+ has been removed, leasing will be disabled and all the current leasing
+ sessions will be terminated. The other way is to call:</para>
+
+ <programlisting>public void setLeasePeriod(long leasePeriodValue)</programlisting>
+
+ <para>and pass a value less than zero. This will disable leasing, preventing
+ any new leases to be established but will allow current leasing sessions to
+ continue.</para>
- <para>For examples of how to use server side connection listeners,
- reference org.jboss.test.remoting.lease.LeaseTestServer and
+ <para>For examples of how to use server side connection listeners, reference
+ org.jboss.test.remoting.lease.LeaseTestServer and
org.jboss.test.remoting.lease.LeaseTestClient.</para>
- </chapter>
\ No newline at end of file
+</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list