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

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

Author: ron.sigal at jboss.com
Date: 2009-04-21 22:55:12 -0400 (Tue, 21 Apr 2009)
New Revision: 5078

Modified:
   remoting2/branches/2.x/docs/guide/en/chap5.xml
Log:
JBREM-1123: Added discussion of SocketServerInvoker's immediateShutdown parameter.

Modified: remoting2/branches/2.x/docs/guide/en/chap5.xml
===================================================================
--- remoting2/branches/2.x/docs/guide/en/chap5.xml	2009-04-21 05:42:20 UTC (rev 5077)
+++ remoting2/branches/2.x/docs/guide/en/chap5.xml	2009-04-22 02:55:12 UTC (rev 5078)
@@ -1474,6 +1474,24 @@
           </listitem>
         </orderedlist>
 
+        <para><emphasis role="bold">Note.</emphasis> When a
+        <classname>ServerThread</classname> receives an invocation, it enters a
+        synchronized method to prevent itself from being interrupted while it is
+        processing the invocation.  When <methodname>SocketServerInvoker.stop()</methodname>
+        is called, it calls the synchronized method <methodname>ServerThread.shutdown()</methodname>
+        for each <classname>ServerThread</classname>, which insures that the server
+        does not shut down until all currently invocations are complete.
+        </para>
+        
+        <para>However, if it happens that an invocation gets hung up for some reason, the
+        server would be prevented from shutting down.  For example, the 
+        <classname>ServerInvocationHandler</classname> could have a bug, or an attempt
+        to write to a disconnected network could get hung up.  As of Release 2.5.2, there
+        is an option to shut down a <classname>SocketServerInvoker</classname> immediately
+        without waiting for current invocations to complete.  This option can be enabled
+        by setting the property "immediateShutdown" to "true".
+        </para>
+
         <bridgehead><emphasis role="bold">Client</emphasis></bridgehead>
 
         <para>When the socket client invoker makes its first invocation, it will
@@ -1513,9 +1531,9 @@
       <section>
          <title>Configuration</title>
          
-        <para>The following configuration properties can be set at any time, but
-        will not take effect until the socket invoker, on the server side, is
-        stopped and restarted.</para>
+        <para>The following configuration properties can be set at any time. If
+        the <classname>SocketServerInvoker</classname> has already started, they
+        will not take effect until it is stopped and restarted.</para>
   
         <para><emphasis role="bold">timeout</emphasis> - The socket timeout
         value passed to the Socket.setSoTimeout() method. The default on the
@@ -1567,6 +1585,12 @@
         continue to wait for an invocation; otherwise, it will return itself to
         the thread pool.</para>
         
+        <para><emphasis role="bold">immediateShutdown</emphasis> - indicates, when
+        set to "true", that, when <methodname>Connector.stop()</methodname> is
+        called and it calls <methodname>SocketServerInvoker.stop()</methodname>,
+        all <classname>ServerThread</classname>s are shut down immediately,
+        even if they are processing an invocation.</para>
+        
         <bridgehead>Configurations affecting the Socket invoker
         client</bridgehead>
   
@@ -6592,6 +6616,13 @@
     value is 'serverSocketClass') - specifies the fully qualified class name
     for the custom SocketWrapper implementation to use on the server.</para>
         
+    <para><emphasis role="bold">Bean properties (meaning have getter/setter):</emphasis></para>
+
+    <para><emphasis role="bold">ImmediateShutdown</emphasis> - a flag for indicating
+    that <classname>SocketServerInvoker</classname> should shut down all of its
+    <classname>ServerThreads</classname> immediately instead of waiting for any
+    current invocations to finish.</para>
+    
     </section>
     
   </section>