[jboss-remoting-commits] JBoss Remoting SVN: r4306 - remoting2/branches/2.2/docs/guide/en.
jboss-remoting-commits at lists.jboss.org
jboss-remoting-commits at lists.jboss.org
Sun Jun 22 01:25:27 EDT 2008
Author: ron.sigal at jboss.com
Date: 2008-06-22 01:25:27 -0400 (Sun, 22 Jun 2008)
New Revision: 4306
Modified:
remoting2/branches/2.2/docs/guide/en/chap5.xml
Log:
JBREM-1001: Updated for 2.2.2.SP8.
Modified: remoting2/branches/2.2/docs/guide/en/chap5.xml
===================================================================
--- remoting2/branches/2.2/docs/guide/en/chap5.xml 2008-06-22 05:24:38 UTC (rev 4305)
+++ remoting2/branches/2.2/docs/guide/en/chap5.xml 2008-06-22 05:25:27 UTC (rev 4306)
@@ -808,13 +808,58 @@
<section>
<title>Transports (Invokers)</title>
-
+
<para>This section covers configuration issues for each of the transports,
beginning with a set of properties that apply to all transports. The
material in a later section in this chapter, <xref
linkend="section-socket-factories" />, also applies to all
transports.</para>
+
+ <section>
+ <title>Features introduced in Remoting version 2.2</title>
+ <para>Subsequent to the release of Remoting 2.2.0.GA, some transport independent features have been introduced.</para>
+
+ <section>
+ <title>Binding to 0.0.0.0</title>
+
+ <para>Before release 2.2.2.SP2, 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 release 2.2.2.SP2, a server
+ started with the address 0.0.0.0 binds to all available
+ interfaces.</para>
+
+ <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>
+
+ </section>
+
+ <section>
+ <title>Support for IPv6 addresses</title>
+
+ <para>As of release 2.2.2.SP4,
+ <classname>org.jboss.remoting.InvokerLocator</classname> will accept
+ IPv6 IP addresses. For example,</para>
+
+ <programlisting>
+ socket://[::1]:3333/?timeout=10000
+ socket://[::]:4444/?timeout=10000
+ socket://[::ffff:127.0.0.1]:5555/?timeout=10000
+ socket://[fe80::205:9aff:fe3c:7800%7]:6666/?timeout=10000
+ </programlisting>
+
+ </section>
+
+ </section>
+
<section>
<title>Server Invokers</title>
@@ -886,12 +931,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
@@ -914,7 +958,7 @@
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>
@@ -928,7 +972,7 @@
<programlisting>
public static final String BIND_BY_HOST = "remoting.bind_by_host";
- </programlisting>
+ </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
@@ -988,7 +1032,13 @@
zero will disable idle timeout checks on pooled server threads, in the
case was previously enabled. The default value for this property is
-1.</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",
+ 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>
@@ -1147,6 +1197,29 @@
data from the client. Inactive server threads are ones that have
finished processing on a particular socket connection and have been
returned to the thread pool for later reuse. </para>
+
+ <para><emphasis role="bold">Note.</emphasis> Prior to release
+ 2.2.2.SP7, if a server thread experienced a
+ <classname>java.net.SocketTimeoutException</classname>, it would return
+ itself to the thread pool and could not be reused until a new socket
+ connection was created for it to use. In principle, it would be more
+ efficient for the server thread simply to try again to read the next
+ invocation, and, in release 2.2.2.SP7, that is what it does.
+ Unfortunately, <classname>java.io.ObjectInputStream</classname> ceases
+ to function once it experiences a
+ <classname>SocketTimeoutException</classname>. The good news is that
+ <classname>org.jboss.serial.io.JBossObjectInputStream</classname>, made
+ available by the JBossSerialization project, does not suffer from that
+ problem. Therefore, as of release 2.2.2.SP8, when it experiences a
+ <classname>SocketTimeoutException</classname>, a server thread will
+ check whether it is using a
+ <classname>JBossObjectInputStream</classname> or not and act
+ accordingly. Just to allow for the possibility that an application is
+ using yet another version of <classname>ObjectInputStream</classname>,
+ the parameter <code>ServerThread.CONTINUE_AFTER_TIMEOUT</code> (actual
+ value "continueAfterTimeout") allows the behavior following a
+ <classname>SocketTimeoutException</classname> to be configured
+ explicitly.</para>
<bridgehead>client</bridgehead>
@@ -1178,6 +1251,20 @@
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><emphasis role="bold">Note. </emphasis> As of release 2.2.2.GA,
+ the server side of the socket transport can capture the IP address of
+ the client side of a TCP connection from client to server and make it
+ available to application code on the client side. The address can be
+ retrieved as follows:</para>
+
+ <programlisting>
+ Client client = new Client(locator);
+ ...
+ InvocationResponse response = (InvocationResponse) client.invoke("$GET_CLIENT_LOCAL_ADDRESS$");
+ InetAddress address = (InetAddress) response.getResult();
+ </programlisting>
+
</section>
</section>
@@ -1641,6 +1728,16 @@
WebServerError and returned as this type. The raw data from the web
server can the be retrieved by getting the WebServerError's
message.</para>
+
+ <para><emphasis role="bold">Note.</emphasis> Prior to Remoting release
+ 2.2.2.SP2, the servlet transport returned a simple error message in the
+ event of an error on the server side. As of release 2.2.2.SP2, the
+ exception handling behavior described above can be requested for the the
+ servlet and sslservlet transports as well by configuring the server with
+ the parameter
+ <code>org.jboss.remoting.transport.http.HTTPMetadataConstants.RETURN_EXCEPTION</code>
+ (actual value "return-exception") set to "true".</para>
+
</section>
<section id="section-multiplex-invoker" xreflabel="Multiplex Invoker">
@@ -3425,7 +3522,7 @@
The main distinction in type of callback setup is whether the callbacks will
be push (asynchronous) or pull (synchronous) callbacks.</para>
- <section>
+ <section id="subsection-pull-callbacks" xreflabel="Pull callbacks">
<title>Pull callbacks.</title>
<para>
@@ -3469,6 +3566,40 @@
together identify a particular callback connection.
</para>
+ <para><emphasis role="bold">Note. </emphasis>As of Remoting release
+ 2.2.2.GA, there are two versions of pull callbacks: non-blocking
+ (original) and blocking (new). In the original, non-blocking mode, a
+ call to <classname>Client.getCallbacks()</classname> will return more or
+ less immediately, whether or not any callbacks are waiting on the server
+ side. In the new, blocking mode, the call will block on the server side
+ until either it times out or a callback becomes available. The blocking
+ mode eliminates the overhead of busy polling. Blocking and non-blocking
+ mode are configured on a per-invocation basis by setting
+ <code>org.jboss.remoting.ServerInvoker.BLOCKING_MODE</code> (actual
+ value "blockingMode") to either
+ <classname>ServerInvoker.BLOCKING</classname> (actual value "blocking")
+ or <classname>ServerInvoker.NONBLOCKING</classname> (actual value
+ "nonblocking") in the metadata map passed to</para>
+
+ <programlisting>
+ public List getCallbacks(InvokerCallbackHandler callbackHandler, Map metadata) throws Throwable;
+ </programlisting>
+
+ <para>in <classname>org.jboss.remoting.Client</classname>. The default
+ value is <code>ServerInvoker.NONBLOCKING</code>. The blocking timeout
+ value may be configured in two ways:</para>
+
+ <orderedlist>
+ <listitem><para>the <classname>Connector</classname> can be
+ configured with a default value; and</para>
+ </listitem>
+ <listitem><para>a per-invocation timeout value can be configured with
+ the key <code>ServerInvoker.BLOCKING_TIMEOUT</code> in the metadata
+ map passed to <methodname>Client.getCallbacks()</methodname>.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>In the absence of any configured timeout, the default value is 5000 ms.</para>
</section>
<section>
@@ -3664,17 +3795,30 @@
with only one callback connection.
</para>
+ <para><emphasis role="bold">Note. </emphasis>As of Remoting release
+ 2.2.2.GA, there are two versions of pull callbacks: non-blocking
+ (original) and blocking (new). For more information, see <xref
+ linkend="subsection-pull-callbacks"/>. Since the
+ <classname>CallbackPoller</classname> uses pull callbacks, this
+ distinction is relevant to polled callbacks as well. The default
+ behavior of <classname>CallbackPoller</classname> is to use non-blocking
+ mode, but blocking mode can be requested by using the key
+ <code>ServerInvoker.BLOCKING_MODE</code> set to
+ <code>ServerInvoker.BLOCKING</code> in the metadata map passed to
+ <methodname>Client.addListener()</methodname>.</para>
+
<para>
- There are six parameters that can be passed to
+ There are nine parameters that can be passed to
<methodname>addListener()</methodname> in the <code>metadata</code>
map which are specific to push callback configuration. The first three
- apply to push callbacks and the latter three apply to polled
+ apply to push callbacks and the latter six apply to polled
callbacks. For convenience, the keys related to push callbacks are
defined as constants in the
<classname>org.jboss.remoting.Client</classname> class, and the keys
related to polled callbacks are defined in the
<classname>org.jboss.remoting.callback.CallbackPoller</classname>
- class.
+ class(with the exception of
+ <code>ServerInvoker.BLOCKING_MODE</code> and <code>ServerInvoker.BLOCKING_TIMEOUT</code>).
</para>
<para>
@@ -3727,12 +3871,52 @@
<classname>CallbackPoller</classname> to print statistics that might
be useful for configuring the other parameters..
</para>
+
+ <para>
+ <emphasis role="bold">MAX_ERROR_COUNT</emphasis> (actual value is
+ "maxErrorCount"): determines the maximum number of errors that may
+ be experienced during polling before
+ <classname>CallbackPoller</classname> will shut itself down. The
+ default value is "5".
+ </para>
+ <para>
+ <emphasis role="bold">SYNCHRONIZED_SHUTDOWN</emphasis> (actual value
+ is "doSynchronizedShutdown"): if set to "true",
+ <methodname>CallbackPoller.stop()</methodname> will wait for
+ <methodname>Client.getCallbacks()</methodname> to return, and if set
+ to "false" it will not wait. For blocking polled callbacks, the
+ default value is "false" and for non-blocking polled callbacks, the
+ default value is "true".
+ </para>
+
+ <para>
+ <emphasis role="bold">BLOCKING_MODE</emphasis> (actual value is
+ "blockingMode"): if set to <code>ServerInvoker.BLOCKING</code>
+ (actual value "blocking"), <classname>CallbackPoller</classname>
+ will do blocking polled callbacks, and if set to
+ <code>ServerInvoker.NONBLOCKING</code> (actual value "nonblocking"),
+ <classname>CallbackPoller</classname> will do non-blocking polled
+ callbacks.
+ </para>
+
<para>
Note that all of the elements in <code>metadata</code> will be passed
to the callback <classname>Connector</classname> and appended to its
<classname>InvokerLocator</classname>.
</para>
+
+ <para><emphasis role="bold">Note. </emphasis> As of Remoting release
+ 2.2.2.GA, it is possible to configure a server side timeout value for
+ sending push callbacks that is distinct from the timeout value used by
+ the server. The parameter is
+ <code>org.jboss.remoting.callback.ServerInvokerCallbackHandler.CALLBACK_TIMEOUT</code>
+ (actual value "callbackTimeout"), and it should be used to configure the
+ <classname>Connector</classname>. In the absence of
+ <code>ServerInvokerCallbackHandler.CALLBACK_TIMEOUT</code>, the timeout
+ value configured for the <classname>Connector</classname> will be
+ used.</para>
+
</section>
</section>
@@ -3940,6 +4124,23 @@
callback listener proxy on the server side. The number of exceptions the
DefaultCallbackErrorHandler will allow before removing the listener can
by configured by the 'callbackErrorsAllowed' attribute.</para>
+
+ <para><emphasis role="bold">Note. </emphasis>As of Remoting release
+ 2.2.2.SP4, an
+ <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>,
+ which manages both push and pull callbacks on the server side, can
+ register to be informed of a failure on the connection to the client that
+ it is servicing. In particular, if there is a lease registered for the
+ connection for that particular client, then the
+ <classname>ServerInvokerCallbackHandler</classname> can be registered as a
+ <classname>org.jboss.remoting.ConnectionListener</classname> for that
+ lease. The default behavior is to do the registration, but the parameter
+ <code>org.jboss.remoting.ServerInvoker.REGISTER_CALLBACK_LISTENER</code>
+ (actual value "registerCallbackListener") may be set to "false" to prevent
+ registration. If leasing is enabled and registration is turned on, a
+ <classname>ServerInvokerCallbackHandler</classname> will shut itself down
+ upon being informed of a connection failure. For more information about
+ leasing, see <xref linkend="chapter-connection-failure"/>.</para>
</section>
</section>
@@ -5957,6 +6158,33 @@
instance of it (which requires it to have a void constructor). The
instance will then be cast to type javax.net.ServerSocketFactory.</para>
+ <para>
+ <emphasis role="bold">BLOCKING_MODE</emphasis> (actual value is
+ "blockingMode"): if set to <code>ServerInvoker.BLOCKING</code> (actual
+ value "blocking"),
+ <methodname>org.jboss.remoting.Client.getCallbacks()</methodname> will do
+ blocking pull callbacks and <classname>CallbackPoller</classname> will do
+ blocking polled callbacks; if set to
+ <code>ServerInvoker.NONBLOCKING</code> (actual value "nonblocking"),
+ <methodname>Client.getCallbacks()</methodname> will do non-blocking pull
+ callbacks and <classname>CallbackPoller</classname> will do non-blocking
+ polled callbacks.
+ </para>
+
+ <para>
+ <emphasis role="bold">BLOCKING_TIMEOUT</emphasis> (actual value is
+ "blockingTimeout"): the timeout value used for blocking callback.
+ </para>
+
+ <para>
+ <emphasis role="bold">REGISTER_CALLBACK_LISTENER</emphasis> (actual value
+ is "registerCallbackListener"): determines if
+ <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>s
+ should register as
+ <classname>org.jboss.remoting.ConnectionListener</classname>s with leases.
+ The default value is "true".
+ </para>
+
<para></para>
<para><emphasis role="bold">Bean properties (meaning have
@@ -6082,6 +6310,63 @@
under which detection messages will be bound and looked up.</para>
<para></para>
+
+ <bridgehead>org.jboss.remoting.transport.bisocket.Bisocket</bridgehead>
+ <para>
+ <emphasis role="bold">IS_CALLBACK_SERVER</emphasis> (actual value is
+ "isCallbackServer"): when a bisocket server invoker receives this
+ parameter with a value of true, it avoids the creation of a
+ <classname>ServerSocket</classname>. Therefore, IS_CALLBACK_SERVER
+ should be used on the client side for the creation of a callback
+ server. The default value is false.
+ </para>
+
+ <para>
+ <emphasis role="bold">PING_FREQUENCY</emphasis> (actual
+ value is "pingFrequency"): The server side uses this value
+ to determine the interval, in milliseconds, between pings that it will
+ send on the control connection. The client side uses this value to
+ calculate the window in which it must receive pings on the control
+ connection. In particular, the window is ping frequency * ping window factor.
+ See also the definition of PING_WINDOW_FACTOR. The default value is 5000.
+ </para>
+
+ <para>
+ <emphasis role="bold">PING_WINDOW_FACTOR</emphasis> (actual
+ value is "pingWindowFactor"): The client side uses this value to
+ calculate the window in which it must receive pings on the control
+ connection. In particular, the window is ping frequency * ping window factor.
+ See also the definition of PING_FREQUENCY. The default value is 2.
+ </para>
+
+ <para>
+ <emphasis role="bold">MAX_RETRIES </emphasis> (actual value is
+ "maxRetries"): This parameter is relevant only on the client side,
+ where the <classname>BisocketClientInvoker</classname> uses it
+ to govern the number of attempts it should make to get the address and
+ port of the secondary <classname>ServerSocket</classname>, and the
+ <classname>BisocketServerInvoker</classname> uses it to govern the
+ number of attempts it should make to create both ordinary and control
+ 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
+ <classname>ServerSocket</classname>.</para>
+
+ <para>
+ <emphasis role="bold">SECONDARY_CONNECT_PORT</emphasis> (actual value
+ is "secondaryConnectPort"): The server side uses this parameter to
+ determine the connect port used by the client side to connect to the
+ secondary <classname>ServerSocket</classname>.</para>
<bridgehead>org.jboss.remoting.transport.http.HTTPMetadataConstants</bridgehead>
@@ -6186,6 +6471,12 @@
originated on the server (if using remoting server) or throw a
org.jboss.remoting.transport.http.WebServerError, whose message will be
the error html returned from the web server.</para>
+
+ <para><emphasis role="bold">RETURN_EXCEPTION</emphasis> (actual value is
+ 'return-exception') - key indicating if
+ <classname>org.jboss.remoting.transport.servlet.ServletServerInvoker</classname>
+ should throw an exception instead of the orginal error handling behavior of
+ returning an error message.</para>
<para></para>
@@ -6250,6 +6541,15 @@
<para></para>
+ <bridgehead>org.jboss.remoting.transport.socket.ServerThread</bridgehead>
+
+ <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>
+
<bridgehead>org.jboss.remoting.transport.socket.SocketServerInvoker</bridgehead>
<para><emphasis role="bold">CHECK_CONNECTION_KEY</emphasis> (actual value
More information about the jboss-remoting-commits
mailing list