Author: ron.sigal(a)jboss.com Date: 2008-05-28 04:40:36 -0400 (Wed, 28 May 2008) New Revision: 4252 Modified: remoting2/branches/2.x/docs/guide/en/chap5.xml Log: JBREM-840: Updated discussion of MicroSocketClientInvoker.transport(). Modified: remoting2/branches/2.x/docs/guide/en/chap5.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap5.xml 2008-05-28 07:37:45 UTC (rev 4251) +++ remoting2/branches/2.x/docs/guide/en/chap5.xml 2008-05-28 08:40:36 UTC (rev 4252) @@ -1490,23 +1490,30 @@ connection to the pool. As more client invocations are made, is possible for the number of socket connections to reach the maximum allowed (which is controlled by 'clientMaxPoolSize' property). At this point, when the - next client invocation is made, it will wait up to 30 seconds, at which - point it will throw an - <classname>org.jboss.remoting.InvocationFailureException</classname>.</para> + next client invocation is made, it will wait up to some configured + number of milliseconds, at which point it will throw an + <classname>org.jboss.remoting.CannotConnectException</classname>. The + number of milliseconds is given by the parameter + <code>MicroSocketClientInvoker.CONNECTION_WAIT</code> (actual value + "connectionWait"), with a default of 30000 milliseconds. Note that if + more than one call retry is configured (see next paragraph), the + <classname>CannotConnectException</classname> will be swallowed.</para> - <para>Once the socket client invoker goes get an available socket - connection from the pool, are not out of the woods yet. There is still - a possibility that the socket connection returned, while still - appearing to be valid, has timed out while sitting in the pool. So if - discover this while trying to make invocation, will throw it away and - retry the whole process again. Will do this up to the number set by - the numberOfCallRetries before throwing an exception. The trick here - is that when get to numberOfCallRetries -2, will assume that any - socket connection gotten from the pool will have timed out and will - flush the pool all together so that the next retry will cause a new - socket connection to be recreated. A typical scenario when this might - occur is when have had a burst of client invocations and then a long - period of inactivity.</para> + <para>Once the socket client invoker get an available socket connection + from the pool, are not out of the woods yet. For example, a network + problem could cause a <classname>java.net.SocketException</classname>. + There is also a possibility that the socket connection, while + still appearing to be valid, has "gone stale" while sitting in the pool. + For example, a <classname>ServerThread</classname> on the other side of + the connection could time out and close its socket. If the attempt to + complete an invocation fails, then + <classname>MicroSocketClientInvoker</classname> will make a number of + attempts, according to the parameter "numberOfCallRetries", with a + default value of 3. Once the configured number of retries has been + exhausted, an + <classname>org.jboss.remoting.InvocationFailureException</classname> + will be thrown.</para> + </section> <section> @@ -1592,18 +1599,13 @@ the socket client invoker. The default is 50.</para> <para><emphasis role="bold">numberOfCallRetries</emphasis> - number of - retries for making invocation. This is unrelated to numberOfRetries in - that when this comes into play is after it has already received a client - socket connection from the pool. However, is possible that the socket - connection timed out while waiting within the pool. Since not doing a - connection check by default, will throw away the connection and try to - get a new one. Will do this for whatever the numberOfCallRetries (which - defaults to 3) is. However, when reaches numberOfCallsRetries - 2, will - flush the entire connection pool under the assumption that all - connections in the pool have timed out and are invalid and will start - over by creating a new connection. If still fails, will throw - MarshalException with the cause being the original - SocketException.</para> + retries for making invocation. It is possible that a socket connection + timed out while waiting within the pool. Since not doing a connection + check by default, will throw away the connection and try to get a new + one. Will do this for numberOfCallRetries times (which defaults to 3). + If still fails, will throw an + <classname>org.jboss.remoting.InvocationFailureException</classname>, + with the cause being the original exception.</para> <para><emphasis role="bold">clientSocketClass</emphasis> - specifies the fully qualified class name for the custom SocketWrapper implementation