Author: ron.sigal(a)jboss.com Date: 2008-07-31 20:15:50 -0400 (Thu, 31 Jul 2008) New Revision: 4445 Modified: remoting2/branches/2.x/docs/guide/en/chap5.xml Log: JBREM-1015: Described new Remoting.SOCKET_FACTORY_CLASS_NAME parameter; also, some other uncommitted changes. Modified: remoting2/branches/2.x/docs/guide/en/chap5.xml =================================================================== --- remoting2/branches/2.x/docs/guide/en/chap5.xml 2008-07-31 23:32:40 UTC (rev 4444) +++ remoting2/branches/2.x/docs/guide/en/chap5.xml 2008-08-01 00:15:50 UTC (rev 4445) @@ -920,25 +920,40 @@ <para>A number of transport independent features are introduced in Remoting version 2.4.</para> - <section> - <title>Multihome servers</title> + <section> + <title>Binding to 0.0.0.0</title> - <para>Before version 2.4, a Remoting server could bind either to a specific IP address, e.g., - </para> + <para>Before version 2.4, a Remoting server could bind to only one + specific IP address. In particular, the address 0.0.0.0 was translated + to the host returned by <code>java.net.InetAddress.getLocalHost()</code> + (or its equivalent IP address). As of version 2.4 [and later releases in + the 2.2 series], a server started with the address 0.0.0.0 binds to + all available interfaces.</para> - <programlisting>socket://192.168.0.2:6500</programlisting> + <para><emphasis role="bold">Note.</emphasis> If 0.0.0.0 appears in the + <classname>InvokerLocator</classname>, it needs to be translated to an + address that is usable on the client side. If the system property + <code>InvokerLocator.BIND_BY_HOST</code> (actual value + "remoting.bind_by_host") is set to "true", the + <classname>InvokerLocator</classname> host will be transformed to the + value returned by + <code>InetAddress.getLocalHost().getHostName()</code>. + Otherwise, it will be transformed to the value returned by + <code>InetAddress.getLocalHost().getHostAddress()</code>. </para> - <para>or to <emphasis>all</emphasis> IP addresses on a given host, e.g.,</para> + </section> + + <section> + <title>Multihome servers</title> - <programlisting>socket://0.0.0.0:6500</programlisting> + <para>As of release 2.4, besides binding to <emphasis>all</emphasis> + available interfaces, it is also possible to configure a server to + bind to a subset of the interfaces available on a given host. Suppose, + for example, that a host machine has NICs configured with addresses + 10.32.4.2, 192.168.4.2, and 192.168.8.2, and suppose that 192.168.8.2 is + on a LAN from which access is meant to be denied. It is now possible to + create a single server that binds to 10.32.4.2 and 192.168.4.2.</para> - <para>As of release 2.4, it is possible to a configure a server to bind to a - subset of the interfaces available on a given host. Suppose, for example, - that a host machine has NICs configured with addresses 10.32.4.2, - 192.168.4.2, and 192.168.8.2, and suppose that 192.168.8.2 is on a LAN from - which access is meant to be denied. It is now possible to create a single - server that binds to 10.32.4.2 and 192.168.4.2.</para> - <para>It would be convenient to be able to create an <classname>InvokerLocator</classname> that looks something like:</para> @@ -1103,9 +1118,8 @@ }</programlisting> </section> - <section> - <title>Support for IPv6 IP addresses</title> + <title>Support for IPv6 addresses</title> <para><classname>org.jboss.remoting.InvokerLocator</classname> will now accept IPv6 IP addresses. For example,</para> @@ -1225,12 +1239,11 @@ </section> <section> - <title>How the server bind address and port is ultimately - determined</title> + <title>How the server bind address and port is determined</title> <para>If the serverBindAddress property is set, the server invoker will - bind to that address. Otherwise, it will, with two exceptions, use the - address in the InvokerLocator (if there is one). The first exception is the + bind to that address. Otherwise, it will, with one exception, use the + address in the InvokerLocator (if there is one). The exception is the case in which the clientConnectAddress property is set, which indicates that the adddess in the InvokerLocator is not the real address of the server's host. In that case, and in the case that there is no address @@ -1246,8 +1259,8 @@ use host from InvokerLocator else use local host address</programlisting> - - <para>There is one other exception. If the InvokerLocator address is + + <!--para>There is one other exception. If the InvokerLocator address is 0.0.0.0 and the system property called 'remoting.bind_by_host' is set to true, then the local host name will be used, as determined by the call</para> @@ -1257,7 +1270,9 @@ be used. To facilitate setting this property, the following static variable is defined in <classname>InvokerLocator</classname>:</para> - <programlisting>public static final String BIND_BY_HOST = "remoting.bind_by_host";</programlisting> + <programlisting> + public static final String BIND_BY_HOST = "remoting.bind_by_host"; + </programlisting--> <para>If the serverBindPort property is set, it will be used. If this value is 0 or a negative number, then the next available port will be @@ -1511,8 +1526,9 @@ <para><emphasis role="bold">continueAfterTimeout</emphasis> - indicates what a server thread should do after experiencing a <classname>java.net.SocketTimeoutException</classname>. If set to - "true", the server thread will continue to wait for an invocation; - otherwise, it will return itself to the thread pool.</para> + "true", or if JBossSerialization is being used, the server thread will + continue to wait for an invocation; otherwise, it will return itself to + the thread pool.</para> <bridgehead>Configurations affecting the Socket invoker client</bridgehead> @@ -2295,6 +2311,13 @@ sockets. The default value is 10. </para> <para> + <emphasis role="bold">MAX_CONTROL_CONNECTION_RESTARTS</emphasis> + (actual value is "maxControlConnectionRestarts"): The client side uses + this value to limit the number of times it will request a new control + connection after a ping timeout. The default value is 10. + </para> + + <para> <emphasis role="bold">SECONDARY_BIND_PORT</emphasis> (actual value is "secondaryBindPort"): The server side uses this parameter to determine the bind port for the secondary @@ -3971,7 +3994,7 @@ <listitem> <para>Put the class name of a <classname>SocketFactory</classname> in a configuration map, using key - <constant>Remoting.SOCKET_FACTORY_NAME</constant>, and pass the + <constant>Remoting.SOCKET_FACTORY_CLASS_NAME</constant>, and pass the map to one of the <classname>Connector</classname> constructors. The <classname>SocketFactory</classname> class must have a default constructor.</para> @@ -4170,7 +4193,7 @@ <listitem> <para>Put the class name of a <classname>SocketFactory</classname> in a configuration map, using key - <constant>Remoting.SOCKET_FACTORY_NAME</constant>, and pass the + <constant>Remoting.SOCKET_FACTORY_CLASS_NAME</constant>, and pass the map to one of the <classname>Client</classname> constructors. The <classname>SocketFactory</classname> class must have a default constructor, which will be used to create a @@ -5211,8 +5234,8 @@ </para> <para> - Each transport that supports per invocation timeouts handles them a - little differently. More details are given below. + Each transport handles per invocation timeouts a little differently. + More details are given below. </para> </section> @@ -5854,8 +5877,8 @@ Client to indicate the socket factory to be used. Value must be instance of javax.net.SocketFactory.</para> - <para><emphasis role="bold">SOCKET_FACTORY_NAME</emphasis> (actual value - is 'socketFactory') - key for the configuration map passed to a Client to + <para><emphasis role="bold">SOCKET_FACTORY_CLASS_NAME</emphasis> (actual value + is 'socketFactoryClassName') - key for the configuration map passed to a Client to indicate the classname of the socket factory to be used. Value should be fully qualified classname of class that is an instance of javax.net.SocketFactory and has a void constructor. This property will not @@ -6439,16 +6462,19 @@ <section> <title>org.jboss.remoting.transport.socket.ServerThread</title> - <para><emphasis role="bold">evictabilityTimeout</emphasis> - indicates the - number of milliseconds during which a server thread waiting for the next - invocation will not be preemptible.</para> - - <para><emphasis role="bold">continueAfterTimeout</emphasis> - indicates - what a server thread should do after experiencing a - <classname>java.net.SocketTimeoutException</classname>. If set to "true", - the server thread will continue to wait for an invocation; otherwise, it - will return itself to the thread pool.</para> + <para><emphasis role="bold">EVICTABILITY_TIMEOUT</emphasis> (actual value + "evictabilityTimeout") - indicates the number of milliseconds during which + a server thread waiting for the next invocation will not be + preemptible.</para> + <para><emphasis role="bold">CONTINUE_AFTER_TIMEOUT</emphasis> (actual + value "continueAfterTimeout") - indicates what a server thread should do + after experiencing a + <classname>java.net.SocketTimeoutException</classname>. If set to "true", + or if JBossSerialization is being used, the server thread will continue to + wait for an invocation; otherwise, it will return itself to the thread + pool.</para> + </section> <section>