[jboss-cvs] JBossRemoting/docs/guide/en ...
Ron Sigal
ron_sigal at yahoo.com
Wed Mar 7 03:09:50 EST 2007
User: rsigal
Date: 07/03/07 03:09:50
Modified: docs/guide/en chap5.xml
Log:
JBREM-525, JBREM-634: (1) Updated discussion of HostnameVerifier; (2) added to callback section and wrapped long lines.
Revision Changes Path
1.15 +359 -80 JBossRemoting/docs/guide/en/chap5.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: chap5.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/guide/en/chap5.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -b -r1.14 -r1.15
--- chap5.xml 7 Mar 2007 05:23:34 -0000 1.14
+++ chap5.xml 7 Mar 2007 08:09:50 -0000 1.15
@@ -1379,12 +1379,37 @@
transport, if the URL's hostname and the server's identification
hostname mismatch, a javax.net.ssl.HostnameVerifier implementation will
be called to determine if this connection should be allowed. The default
- implementation will not allow this. To override this behavior to allow
- this by changing the HostnameVerifier implementation, can use the
- 'org.jboss.security.ignoreHttpsHost' property'. This property can either
- be set using a system property or within the metadata Map passed to the
- Client's invoke() method (which will override both the default value and
- the setting from the system property).</para>
+ implementation will not allow this, but it is possible to override the default
+ behavior</para>
+
+ <para>One option is to use the key <code>HTTPSClientInvoker.HOSTNAME_VERIFIER</code>
+ (actual value "hostnameVerifier") to supply the name of a class that implements
+ the <classname>javax.net.ssl.HostnameVerifier</classname> interface, passing it
+ either in the metadata map supplied with an invocation or in the configuration map
+ supplied when the <classname>HTTPSClientInvoker</classname> was created. If the key
+ appears in both maps, the value in the metadata map takes precedence.
+ </para>
+
+ <para>In the absence of an explicitly declared <classname>HostnameVerifier</classname>,
+ another way to configure the hostname verification behavior is to declare that all host
+ names are acceptable, which can be accomplished by setting the
+ <code>HTTPSClientInvoker.IGNORE_HTTPS_HOST</code> property (actual value
+ "org.jboss.security.ignoreHttpsHost") to true. In order of increasing precedence,
+ the property may be set (1) as a system property, (2) in the configuration map supplied
+ when the <classname>HTTPSClientInvoker</classname> was created, or in the metadata map
+ supplied with an invocation.</para>
+
+ <para>Finally, in the absence of both an explicitly declared
+ <classname>HostnameVerifier</classname> and an explicit directive to ignore host
+ names, an <classname>HTTPSClientInvoker</classname> will check to see if its
+ <classname>SocketFactory</classname> is an instance of
+ <classname>org.jboss.remoting.security.CustomSSLSocketFactory</classname> and, if so,
+ if authentication has been turned off. If that is the case, host names will be ignored.
+ See Section <xref linkend="section-socket-factories" /> for more information about
+ <classname>SocketFactory</classname> configuration.
+
+ </para>
+
</section>
<section>
@@ -2631,22 +2656,34 @@
<section>
<title>Callback overview</title>
- <para>Although this section covers callback configuration, it will be useful to begin with a little general information about callbacks within
- Remoting. In addition to the ordinary remote method invocation model, in which invocation results are returned synchronously, Remoting also supports an invocation model in which the server asynchronously generates information to be returned to the client.
+ <para>
+ Although this section covers callback configuration, it will be useful to begin
+ with a little general information about callbacks within Remoting. In addition
+ to the ordinary remote method invocation model, in which invocation results are
+ returned synchronously, Remoting also supports an invocation model in which the
+ server asynchronously generates information to be returned to the client.
</para>
<para>
- There are two models for callbacks, <emphasis role="bold">push callbacks</emphasis> and <emphasis role="bold">pull callbacks</emphasis>. In the push model, the client registers a client side callback server
- with the target server. When the target server has a callback to
- deliver, it will call on the callback server directly and send the
- callback message. The other model, pull callbacks, allows the client to call on the target server to collect the callback messages waiting for it.
+ There are two models for callbacks, <emphasis role="bold">push
+ callbacks</emphasis> and <emphasis role="bold">pull callbacks</emphasis>.
+ In the push model, the client registers a client side callback server with
+ the target server. When the target server has a callback to deliver, it
+ will call on the callback server directly and send the callback message.
+ The other model, pull callbacks, allows the client to call on the target
+ server to collect the callback messages waiting for it.
</para>
<section>
<title>Callback connections</title>
<para>
- A <emphasis role="bold">callback connection</emphasis> is initiated by the invocation of one of the overloaded <methodname>addListener()</methodname> methods in the <classname>org.jboss.remoting.Client</classname> class, as described below in Section <xref linkend="section-callback-handlers"/>. The creation of a callback connection results in a server side call to the
+ A <emphasis role="bold">callback connection</emphasis> is initiated by
+ the invocation of one of the overloaded
+ <methodname>addListener()</methodname> methods in the
+ <classname>org.jboss.remoting.Client</classname> class, as described
+ below in Section <xref linkend="section-callback-handlers"/>. The
+ creation of a callback connection results in a server side call to the
</para>
<programlisting>
@@ -2654,15 +2691,60 @@
</programlisting>
<para>
- method of the application's <classname>org.jboss.remoting.ServerInvocationHandler</classname>. The <classname>org.jboss.remoting.callback.InvokerCallbackHandler</classname> parameter (actual type <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname> is the server side representation of the callback connection, essentially a proxy for the client side <classname>InvokerCallbackHandler</classname> passed to the <methodname>addListener()</methodname> method. The <classname>ServerInvocationHandler</classname> is free to do whatever it wants with the <classname>InvokerCallbackHandler</classname>, but a typical practice would be to keep a list of them and transmit each generated callback to some or all of them.
+ method of the application's
+ <classname>org.jboss.remoting.ServerInvocationHandler</classname>. The
+ <classname>org.jboss.remoting.callback.InvokerCallbackHandler</classname>
+ parameter (actual type
+ <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>)
+ is the server side representation of the callback connection,
+ essentially a proxy for the client side
+ <classname>InvokerCallbackHandler</classname> passed to the
+ <methodname>addListener()</methodname> method. The
+ <classname>ServerInvocationHandler</classname> is free to do whatever
+ it wants with the <classname>InvokerCallbackHandler</classname>, but a
+ typical practice would be to keep a list of them and transmit each
+ generated callback to some or all of them.
</para>
<para>
- The client side of a callback connection is identified in one of two ways, according to whether there is a callback <classname>Connector</classname> associated with the connection. If the connection has a callback <classname>Connector</classname>, then it is identifed by the combination of the <classname>Connector</classname> and the <classname>InvokerCallbackHandler</classname>. It follows that if an <classname>InvokerCallbackHandler</classname> is registered twice with the same <classname>Connector</classname> (through a call to <methodname>Client.addListener()</methodname>), only a single callback connection is created. That is, the second call has no effect. If there is no callback <classname>Connector</classname>, which is the case for pull callbacks and simulated push callbacks (see Section <xref linkend="section-callback-handlers"/>), then the callback connection is identified by the combination of the <classname>Client</classname> on which <methodnam!
e>addListener()</methodname> was invoked and the <classname>InvokerCallbackHandler</classname>. It follows that if an <classname>InvokerCallbackHandler</classname> is registered twice with the same <classname>Client</classname> for pull or simulated push callbacks, only a single callback connection is created. That is, the second call has no effect.
+ The client side of a callback connection is identified in one of two
+ ways, according to whether there is a callback
+ <classname>Connector</classname> associated with the connection. If
+ the connection has a callback <classname>Connector</classname>, then
+ it is identifed by the combination of the
+ <classname>Connector</classname> and the
+ <classname>InvokerCallbackHandler</classname>. It follows that if an
+ <classname>InvokerCallbackHandler</classname> is registered twice with
+ the same <classname>Connector</classname> (through a call to
+ <methodname>Client.addListener()</methodname>), only a single callback
+ connection is created. That is, the second call has no effect. If
+ there is no callback <classname>Connector</classname>, which is the
+ case for pull callbacks and simulated push callbacks (see Section
+ <xref linkend="section-callback-handlers"/>), then the callback
+ connection is identified by the combination of the
+ <classname>Client</classname> on which
+ <methodname>addListener()</methodname> was invoked and the
+ <classname>InvokerCallbackHandler</classname>. It follows that if an
+ <classname>InvokerCallbackHandler</classname> is registered twice with
+ the same <classname>Client</classname> for pull or simulated push
+ callbacks, only a single callback connection is created. That is, the
+ second call has no effect.
</para>
<para>
- Each callback connection is tagged with a unique identifier, which can be retrieved from the <classname>InvokerCallbackHandler</classname> passed to <methodname>ServerInvocationHandler.addListener()</methodname> by casting it to type <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname> and calling <methodname>getCallbackSessionId()</methodname>. It is also possible to retrieve the unique identifier of the <classname>Client</classname> upon which <methodname>addListener()</methodname> was invoked by casting the <classname>InvokerCallbackHandler</classname> to type <classname>ServerInvokerCallbackHandler</classname> and calling <methodname>getClientSessionId()</methodname>.
+ Each callback connection is tagged with a unique identifier, which can
+ be retrieved from the <classname>InvokerCallbackHandler</classname>
+ passed to
+ <methodname>ServerInvocationHandler.addListener()</methodname> by
+ casting it to type
+ <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>
+ and calling <methodname>getCallbackSessionId()</methodname>. It is
+ also possible to retrieve the unique identifier of the
+ <classname>Client</classname> upon which
+ <methodname>addListener()</methodname> was invoked by casting the
+ <classname>InvokerCallbackHandler</classname> to type
+ <classname>ServerInvokerCallbackHandler</classname> and calling
+ <methodname>getClientSessionId()</methodname>.
</para>
</section>
@@ -2670,7 +2752,11 @@
<title>Transmitting callbacks</title>
<para>
- Once the <classname>ServerInvocationHandler</classname> has generated information to be sent to the client, it can be packaged in an <classname>org.jboss.remoting.callback.Callback</classname> and transmitted on one or more callback connections in one of two ways. One way to transmit a callback is by invoking the
+ Once the <classname>ServerInvocationHandler</classname> has generated
+ information to be sent to the client, it can be packaged in an
+ <classname>org.jboss.remoting.callback.Callback</classname> and
+ transmitted on one or more callback connections in one of two ways.
+ One way to transmit a callback is by invoking the
</para>
<programlisting>
@@ -2678,11 +2764,22 @@
</programlisting>
<para>
- method of <classname>InvokerCallbackHandler</classname>. The subsequent disposition of the callback depends on whether the callback connection is configured for push or pull callbacks. For a pull callback connection, the <classname>Callback</classname> is simply stored on the server, and for a push callback connection, <methodname>handleCallback()</methodname> is analogous to (and is implemented by) an ordinary <methodname>Client.invoke()</methodname> invocation.
+ method of <classname>InvokerCallbackHandler</classname>. The
+ subsequent disposition of the callback depends on whether the callback
+ connection is configured for push or pull callbacks. For a pull
+ callback connection, the <classname>Callback</classname> is simply
+ stored on the server, and for a push callback connection,
+ <methodname>handleCallback()</methodname> is analogous to (and is
+ implemented by) an ordinary <methodname>Client.invoke()</methodname>
+ invocation.
</para>
<para>
- An alternative method of transmitting a callback is by casting an <classname>InvokerCallbackHandler</classname> to type <classname>org.jboss.remoting.callback.AsynchInvokerCallbackHandler</classname> and invoking one of the overloaded <methodname>handleCallbackOneway()</methodname> methods
+ An alternative method of transmitting a callback is by casting an
+ <classname>InvokerCallbackHandler</classname> to type
+ <classname>org.jboss.remoting.callback.AsynchInvokerCallbackHandler</classname>
+ and invoking one of the overloaded
+ <methodname>handleCallbackOneway()</methodname> methods
</para>
<programlisting>
@@ -2692,8 +2789,16 @@
</programlisting>
<para>
- of <classname>AsynchInvokerCallbackHandler</classname>. (Note that all <classname>InvokerCallbackHandler</classname>s passed in to <classname>ServerInvocationHandler.addListener()</classname> implement <classname>AsynchInvokerCallbackHandler</classname>.) For a pull callback connection <methodname>handleCallbackOneway()</methodname> has the same behavior as <methodname>handleCallback()</methodname>, but for a push callback connection it is analogous to (and implemented by) a
- <methodname>Client.invokeOneway()</methodname> invocation. The <code>serverSide</code> parameter is analogous to the <code>clientSide</code> parameter in the
+ of <classname>AsynchInvokerCallbackHandler</classname>. (Note that all
+ <classname>InvokerCallbackHandler</classname>s passed in to
+ <classname>ServerInvocationHandler.addListener()</classname> implement
+ <classname>AsynchInvokerCallbackHandler</classname>.) For a pull
+ callback connection <methodname>handleCallbackOneway()</methodname>
+ has the same behavior as <methodname>handleCallback()</methodname>,
+ but for a push callback connection it is analogous to (and implemented
+ by) a <methodname>Client.invokeOneway()</methodname> invocation. The
+ <code>serverSide</code> parameter is analogous to the
+ <code>clientSide</code> parameter in the
</para>
<programlisting>
@@ -2701,7 +2806,15 @@
</programlisting>
<para>
- method of <classname>org.jboss.remoting.Client</classname>. That is, if <code>serverSide</code> is true, then the oneway invocation is handed off to a separate thread on the server side and the call to <methodname>handleCallbackOneway()</methodname> returns immediately. If <code>serverSide</code> is false, then callback <classname>Client</classname> makes an invocation on the callback server, which hands the invocation off to a separate thread on the client side and returns, after which the call to <methodname>handleCallbackOneway()</methodname> returns.
+ method of <classname>org.jboss.remoting.Client</classname>. That is,
+ if <code>serverSide</code> is true, then the oneway invocation is
+ handed off to a separate thread on the server side and the call to
+ <methodname>handleCallbackOneway()</methodname> returns immediately.
+ If <code>serverSide</code> is false, then callback
+ <classname>Client</classname> makes an invocation on the callback
+ server, which hands the invocation off to a separate thread on the
+ client side and returns, after which the call to
+ <methodname>handleCallbackOneway()</methodname> returns.
</para>
</section>
@@ -2709,11 +2822,21 @@
<title>Callback acknowledgements</title>
<para>
- Unlike the <methodname>Client.invoke()</methodname> method, <methodname>InvokerCallbackHandler.handleCallback()</methodname> has a void return type, so it does not provide a way of knowing if the callback has been received by the client. In fact, a void return type is appropriate since the immediate effect of a call to <methodname>InvokerCallbackHandler.handleCallback()</methodname> may be no more than storing the callback for later retrieval. However, it may be useful for the application to be informed when the callback has made its way to the client, and Remoting has a listener mechanism that can provide callback acknowledgements.
+ Unlike the <methodname>Client.invoke()</methodname> method,
+ <methodname>InvokerCallbackHandler.handleCallback()</methodname> has a
+ void return type, so it does not provide a way of knowing if the
+ callback has been received by the client. In fact, a void return type
+ is appropriate since the immediate effect of a call to
+ <methodname>InvokerCallbackHandler.handleCallback()</methodname> may
+ be no more than storing the callback for later retrieval. However, it
+ may be useful for the application to be informed when the callback has
+ made its way to the client, and Remoting has a listener mechanism that
+ can provide callback acknowledgements.
</para>
<para>
- An object that implements the <classname>org.jboss.remoting.callback.CallbackListener</classname> interface
+ An object that implements the
+ <classname>org.jboss.remoting.callback.CallbackListener</classname> interface
</para>
<programlisting>
@@ -2729,7 +2852,18 @@
</programlisting>
<para>
- may be registered to receive an acknowledgement for a particular callback by adding it to the callback's <code>returnPayload</code> map with the key <code>org.jboss.remoting.callback.ServerInvokerCallbackHandler.CALLBACK_LISTENER</code> (actual value "callbackListener"). It is also necessary to assign an identifier to the callback by adding some unique object, recognizable by the application, to the callback's <code>returnPayload</code> map with the key <code>ServerInvokerCallbackHandler.CALLBACK_ID</code> (actual value "callbackId"). This identifier will be passed as the <code>callbackId</code> parameter of the <methodname>CallbackListener.acknowledgeCallback()</methodname> method.
+ may be registered to receive an acknowledgement for a particular
+ callback by adding it to the callback's <code>returnPayload</code> map
+ with the key
+ <code>org.jboss.remoting.callback.ServerInvokerCallbackHandler.CALLBACK_LISTENER</code>
+ (actual value "callbackListener"). It is also necessary to assign an
+ identifier to the callback by adding some unique object, recognizable
+ by the application, to the callback's <code>returnPayload</code> map
+ with the key <code>ServerInvokerCallbackHandler.CALLBACK_ID</code>
+ (actual value "callbackId"). This identifier will be passed as the
+ <code>callbackId</code> parameter of the
+ <methodname>CallbackListener.acknowledgeCallback()</methodname>
+ method.
</para>
<para>
@@ -2742,10 +2876,18 @@
</orderedlist>
<para>
- Note that automatic acknowledgements are available only for push callbacks and simulated push callbacks (see Section <xref linkend="section-callback-handlers"/>) transmitted by the <methodname>InvokerCallbackHandler.handleCallback()</methodname> method.
+ Note that automatic acknowledgements are available only for push
+ callbacks and simulated push callbacks (see Section <xref
+ linkend="section-callback-handlers"/>) transmitted by the
+ <methodname>InvokerCallbackHandler.handleCallback()</methodname>
+ method.
</para>
+
<para>
- Callbacks may be acknowledged explicitly by the client side application code by calling one of the overloaded <methodname>acknowledgeCallback()</methodname> and <methodname>acknowledgeCallbacks()</methodname> methods
+ Callbacks may be acknowledged explicitly by the client side
+ application code by calling one of the overloaded
+ <methodname>acknowledgeCallback()</methodname> and
+ <methodname>acknowledgeCallbacks()</methodname> methods
</para>
<programlisting>
@@ -2759,15 +2901,40 @@
</programlisting>
<para>
- of the <classname>Client</classname> class. In each case the <code>callbackHandler</code> parameter is the client side <classname>InvokerCallbackHandler</classname> which received the callback. The first two and the latter two methods acknowledge a single callback and a list of callbacks, respectively. In the latter case, each of the callbacks must have the same registered <classname>CallbackListener</classname>. The second and fourth methods also allow a response value to be associated with each callback acknowledgement, which will passed as the <code>response</code> parameter of the <methodname>CallbackListener.acknowledgeCallback()</methodname> method. For the fourth method, the lengths of the <code>callbacks</code> list and the <code>responses</code> list must be the same.
+ of the <classname>Client</classname> class. In each case the
+ <code>callbackHandler</code> parameter is the client side
+ <classname>InvokerCallbackHandler</classname> which received the
+ callback. The first two and the latter two methods acknowledge a
+ single callback and a list of callbacks, respectively. In the latter
+ case, each of the callbacks must have the same registered
+ <classname>CallbackListener</classname>. The second and fourth methods
+ also allow a response value to be associated with each callback
+ acknowledgement, which will passed as the <code>response</code>
+ parameter of the
+ <methodname>CallbackListener.acknowledgeCallback()</methodname>
+ method. For the fourth method, the lengths of the
+ <code>callbacks</code> list and the <code>responses</code> list must
+ be the same.
</para>
<para>
- It is also possible to request that Remoting automatically supply acknowledgements for push callbacks and simulated push callbacks by adding the key <code>ServerInvokerCallbackHandler.REMOTING_ACKNOWLEDGES_PUSH_CALLBACKS</code> (actual value "remotingAcknowledgesPushCallbacks") to the callback's <code>returnPayload</code> map with the value of true, along with the <code>ServerInvokerCallbackHandler.CALLBACK_LISTENER</code> and <code>ServerInvokerCallbackHandler.CALLBACK_ID</code> entries. The acknowledgement is generated after the callback has been delivered by a call to <methodname>handleCallback()</methodname> on the client side <methodname>InvokerCallbackHandler</methodname>.
+ It is also possible to request that Remoting automatically supply
+ acknowledgements for push callbacks and simulated push callbacks by
+ adding the key
+ <code>ServerInvokerCallbackHandler.REMOTING_ACKNOWLEDGES_PUSH_CALLBACKS</code>
+ (actual value "remotingAcknowledgesPushCallbacks") to the callback's
+ <code>returnPayload</code> map with the value of true, along with the
+ <code>ServerInvokerCallbackHandler.CALLBACK_LISTENER</code> and
+ <code>ServerInvokerCallbackHandler.CALLBACK_ID</code> entries. The
+ acknowledgement is generated after the callback has been delivered by
+ a call to <methodname>handleCallback()</methodname> on the client side
+ <methodname>InvokerCallbackHandler</methodname>.
</para>
<para>
- For an example of code that uses callback acknowledgements, see the classes in the package <code>org.jboss.remoting.samples.callback.acknowledgement</code>.
+ For an example of code that uses callback acknowledgements, see the
+ classes in the package
+ <code>org.jboss.remoting.samples.callback.acknowledgement</code>.
</para>
</section>
@@ -2778,14 +2945,19 @@
<title>Registering callback handlers.</title>
<para>There are several ways in which callback handlers can be configured.
- The main distinction in type of callback setup is whether the callbacks will be push (asynchronous) or pull (synchronous) callbacks.</para>
+ The main distinction in type of callback setup is whether the callbacks will
+ be push (asynchronous) or pull (synchronous) callbacks.</para>
<section>
<title>Pull callbacks.</title>
<para>
- A pull callback connection is implemented by an object (an <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>) on the server side which stores information that is
- generated asynchronously on the server and subsequently retrieved by the client. It is set up by invoking one of the following overloaded <methodname>addListener()</methodname> methods in the
+ A pull callback connection is implemented by an object (an
+ <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>)
+ on the server side which stores information that is generated
+ asynchronously on the server and subsequently retrieved by the client.
+ It is set up by invoking one of the following overloaded
+ <methodname>addListener()</methodname> methods in the
<classname>Client</classname> class:
</para>
@@ -2810,8 +2982,14 @@
</programlisting>
<para>
- method of the <classname>Client</classname> class.
- Note that for pull callbacks, the <classname>InvokerCallbackHandler</classname> registered on the client side doesn't really participate in the handling of callbacks. However, when <methodname>client.getCallbacks(callbackHandler)</methodname> is called for a particular <classname>Client</classname> and <classname>InvokerCallbackHandler</classname>, the two objects together identify a particular callback connection.
+ method of the <classname>Client</classname> class. Note that for pull
+ callbacks, the <classname>InvokerCallbackHandler</classname>
+ registered on the client side doesn't really participate in the
+ handling of callbacks. However, when
+ <methodname>client.getCallbacks(callbackHandler)</methodname> is
+ called for a particular <classname>Client</classname> and
+ <classname>InvokerCallbackHandler</classname>, the two objects
+ together identify a particular callback connection.
</para>
</section>
@@ -2820,13 +2998,19 @@
<title>Push callbacks.</title>
<para>
- A push callback connection is implemented by a pair of objects, one on the server side and one on the client side, which facilitate
+ A push callback connection is implemented by a pair of objects, one on
+ the server side and one on the client side, which facilitate
transmitting to the client some information which has been generated
- asynchronously on the server. There are two versions of push callbacks: <emphasis role="bold">true push callbacks</emphasis> and <emphasis role="bold">simulated push callbacks</emphasis>, also known as <emphasis role="bold">polled callbacks</emphasis>.</para>
+ asynchronously on the server. There are two versions of push
+ callbacks: <emphasis role="bold">true push callbacks</emphasis> and
+ <emphasis role="bold">simulated push callbacks</emphasis>, also known
+ as <emphasis role="bold">polled callbacks</emphasis>.
+ </para>
<para>
In the case of true push callbacks, there is a Remoting object on the
- server side (an <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>) which uses a <classname>Client</classname> to make
+ server side (an <classname>org.jboss.remoting.callback.ServerInvokerCallbackHandler</classname>)
+ which uses a <classname>Client</classname> to make
invocations to the client side. On the client side there is a
<classname>Connector</classname> and an implementation of the
<classname>org.jboss.remoting.callback.InvokerCallbackHandler</classname>
@@ -2842,7 +3026,13 @@
</para>
<para>
- For simulated push callbacks, the server side Remoting object stores callbacks for later retrieval by the client, exactly as in the case of pull callbacks. However, there is a Remoting poller (an <classname>org.jboss.remoting.callback.CallbackPoller</classname>) on the client side which periodically retrieves the callbacks and, as in the case of true push callbacks, delivers them to the <classname>InvokerCallbackHandler</classname>.
+ For simulated push callbacks, the server side Remoting object stores
+ callbacks for later retrieval by the client, exactly as in the case of
+ pull callbacks. However, there is a Remoting poller (an
+ <classname>org.jboss.remoting.callback.CallbackPoller</classname>) on
+ the client side which periodically retrieves the callbacks and, as in
+ the case of true push callbacks, delivers them to the
+ <classname>InvokerCallbackHandler</classname>.
</para>
<para>
@@ -2878,9 +3068,11 @@
Because there is a <classname>Connector</classname>, explicit configuration always results in true push callbacks.
</para>
- <para>In the case of implicit configuration, only the
- <classname>InvokerCallbackHandler</classname> is passed and Remoting takes care of the rest. One of the following versions of <methodname>addListener()</methodname>
- is used:
+ <para>
+ In the case of implicit configuration, only the
+ <classname>InvokerCallbackHandler</classname> is passed and Remoting
+ takes care of the rest. One of the following versions of
+ <methodname>addListener()</methodname> is used:
</para>
<programlisting>
@@ -2892,48 +3084,113 @@
</programlisting>
<para>
- Note that the latter three methods are distinguished from the first two by the presence of the <code>metadata</code> parameter, which can be used to configure the callback connection. Depending on the transport being used and the
- parameters supplied to <methodname>addListener()</methodname>,
- Remoting will set up either true or simulated push callbacks.
- If the client is in an environment where the server will be allowed to establish a connection to the client, then the final version of <methodname>addLIstener()</methodname> could be used with the <code>serverToClient</code> parameter set to true. In this case, regardless of the transport, Remoting will automatically create a callback <classname>Connector</classname> on behalf of the user, which behaves just as though the user had created it and passed the <classname>InvokerLocator</classname> as a parameter to <methodname>addListener()</methodname>.
+ Note that the latter three methods are distinguished from the first
+ two by the presence of the <code>metadata</code> parameter, which can
+ be used to configure the callback connection. Depending on the
+ transport being used and the parameters supplied to
+ <methodname>addListener()</methodname>, Remoting will set up either
+ true or simulated push callbacks. If the client is in an environment
+ where the server will be allowed to establish a connection to the
+ client, then the final version of
+ <methodname>addLIstener()</methodname> could be used with the
+ <code>serverToClient</code> parameter set to true. In this case,
+ regardless of the transport, Remoting will automatically create a
+ callback <classname>Connector</classname> on behalf of the user, which
+ behaves just as though the user had created it and passed the
+ <classname>InvokerLocator</classname> as a parameter to
+ <methodname>addListener()</methodname>.
</para>
<para>
- If the client is in an environment where the server is not allowed to establish a network connection to the client (e.g. firewall rules disallow it or security rules prohibit the creation of a <classname>ServerSocket</classname>), then there are two options. One is to use
- one of the <emphasis role="bold">bidirectional</emphasis> transports,
- each of which has a strategy for the creation of a connection from the server to the client without connecting a client <classname>Socket</classname> to a <classname>ServerSocket</classname>. There are currently three bidirectional transports: local (i.e., the client and server reside in the same JVM), bisocket, and multiplex. When one of the second set of <methodname>addListener()</methodname> methods is invoked for a bidirectional transport, it will create a callback <classname>Connector</classname>, even if <code>serverToClient</code> is set to false. The other option is to use any of the <emphasis role="bold">unidirectional</emphasis> transports (socket, http, rmi) with <code>serverToClient</code> set to false (which is the default value if it is not an explicit parameter), in which case, Remoting will configure polled callbacks.
+ If the client is in an environment where the server is not allowed to
+ establish a network connection to the client (e.g. firewall rules
+ disallow it or security rules prohibit the creation of a
+ <classname>ServerSocket</classname>), then there are two options. One
+ is to use one of the <emphasis role="bold">bidirectional</emphasis>
+ transports, each of which has a strategy for the creation of a
+ connection from the server to the client without connecting a client
+ <classname>Socket</classname> to a
+ <classname>ServerSocket</classname>. There are currently three
+ bidirectional transports: local (i.e., the client and server reside in
+ the same JVM), bisocket, and multiplex. When one of the second set of
+ <methodname>addListener()</methodname> methods is invoked for a
+ bidirectional transport, it will create a callback
+ <classname>Connector</classname>, even if <code>serverToClient</code>
+ is set to false. The other option is to use any of the <emphasis
+ role="bold">unidirectional</emphasis> transports (socket, http, rmi)
+ with <code>serverToClient</code> set to false (which is the default
+ value if it is not an explicit parameter), in which case, Remoting
+ will configure polled callbacks.
</para>
<para>
- There are six 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 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.
+ There are six 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
+ 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.
</para>
<para>
- <emphasis role="bold">CALLBACK_SERVER_PROTOCOL</emphasis> (actual value is "callbackServerProtocol): the transport protocol to be used for callbacks. By default it will be the protocol used by the <classname>Client</classname> upon which <methodname>addListener()</methodname> is invoked.
+ <emphasis role="bold">CALLBACK_SERVER_PROTOCOL</emphasis> (actual
+ value is "callbackServerProtocol): the transport protocol to be used
+ for callbacks. By default it will be the protocol used by the
+ <classname>Client</classname> upon which
+ <methodname>addListener()</methodname> is invoked.
</para>
<para>
- <emphasis role="bold">CALLBACK_SERVER_HOST</emphasis> (actual value is "callbackServerHost"): the host name to be used by the callback server. By default it will be the result of calling <methodname>InetAddress.getLocalHost().getHostAddress()</methodname>.
+ <emphasis role="bold">CALLBACK_SERVER_HOST</emphasis> (actual value
+ is "callbackServerHost"): the host name to be used by the callback
+ server. By default it will be the result of calling
+ <methodname>InetAddress.getLocalHost().getHostAddress()</methodname>.
</para>
<para>
- <emphasis role="bold">CALLBACK_SERVER_PORT</emphasis> (actual value is "callbackServerPort"): the port to be used by the callback server. By default it will be a randomly chosen unused port.
+ <emphasis role="bold">CALLBACK_SERVER_PORT</emphasis> (actual value
+ is "callbackServerPort"): the port to be used by the callback
+ server. By default it will be a randomly chosen unused port.
</para>
<para>
- <emphasis role="bold">CALLBACK_POLL_PERIOD</emphasis> (actual value is "callbackPollPeriod"): the interval in milliseconds between attempts to download callbacks from the server.
+ <emphasis role="bold">CALLBACK_POLL_PERIOD</emphasis> (actual value
+ is "callbackPollPeriod"): the interval in milliseconds between
+ attempts to download callbacks from the server.
</para>
<para>
- <emphasis role="bold">CALLBACK_SCHEDULE_MODE</emphasis> (actual value is "scheduleMode"): may be set to either <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> (actual value "scheduleFixedRate") or <code>CallbackPoller.SCHEDULE_FIXED_DELAY</code> (actual value "scheduleFixedDelay"). In either case, polling will take place at approximately regular intervals, but in the former case the scheduler will attempt to perform each poll CALLBACK_POLL_PERIOD milliseconds after the previous attempt, and in the latter case the scheduler will attempt to schedule polling so that the <emphasis>average</emphasis> interval will be approximately CALLBACK_POLL_PERIOD milliseconds. <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> is the default.
+ <emphasis role="bold">CALLBACK_SCHEDULE_MODE</emphasis> (actual
+ value is "scheduleMode"): may be set to either
+ <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> (actual value
+ "scheduleFixedRate") or
+ <code>CallbackPoller.SCHEDULE_FIXED_DELAY</code> (actual value
+ "scheduleFixedDelay"). In either case, polling will take place at
+ approximately regular intervals, but in the former case the
+ scheduler will attempt to perform each poll CALLBACK_POLL_PERIOD
+ milliseconds after the previous attempt, and in the latter case the
+ scheduler will attempt to schedule polling so that the
+ <emphasis>average</emphasis> interval will be approximately
+ CALLBACK_POLL_PERIOD milliseconds.
+ <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> is the default.
</para>
<para>
- <emphasis role="bold">REPORT_STATISTICS</emphasis> (actual value is "reportStatistics"): The presence of this key in <code>metadata</code>, regardless of its value, will cause the <classname>CallbackPoller</classname> to print statistics that might be useful for configuring the other parameters..
+ <emphasis role="bold">REPORT_STATISTICS</emphasis> (actual value is
+ "reportStatistics"): The presence of this key in
+ <code>metadata</code>, regardless of its value, will cause the
+ <classname>CallbackPoller</classname> to print statistics that might
+ be useful for configuring the other parameters..
</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>.
+ 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>
</section>
@@ -2951,7 +3208,18 @@
</programlisting>
<para>
- in the <classname>org.jboss.remoting.Client</classname> class. It is good practice to eliminate callback connections when they are no longer needed. For example, callback <classname>Connector</classname>s can, depending on the transport, occupy TCP ports, and <classname>CallbackPoller</classname>s will continue to poll as long as a connection exists.
+ in the <classname>org.jboss.remoting.Client</classname> class. A
+ <classname>Client</classname> can unregister only those
+ <classname>InvokerCallbackHandler</classname>s that it originally
+ registered.
+ </para>
+
+ <para>
+ It is good practice to eliminate callback connections when they are no
+ longer needed. For example, callback <classname>Connector</classname>s
+ can, depending on the transport, occupy TCP ports, and
+ <classname>CallbackPoller</classname>s will continue to poll as long as
+ a connection exists.
</para>
</section>
@@ -2965,13 +3233,14 @@
until the client calls to collect them. Since the server has no control
of when the client will call to get the callbacks, it has to be aware of
memory constraints as it manages a growing number of callbacks. The way
- the callback server does this is through use of a <emphasis role="bold">persistence policy</emphasis>.
+ the callback server does this is through use of a
+ <emphasis role="bold">persistence policy</emphasis>.
</para>
<para>
- The persistence policy indicates at what point the server has too little free
- memory available and therefore the callback message should be put into a
- persistent store. This policy can be configured via the
+ The persistence policy indicates at what point the server has too little
+ free memory available and therefore the callback message should be put
+ into a persistent store. This policy can be configured via the
<code>memPercentCeiling</code> attribute (see more on configuring this
below).</para>
@@ -4982,17 +5251,27 @@
<para><emphasis role="bold">CALLBACK_POLL_PERIOD</emphasis> (actual value
is 'callbackPollPeriod') - key for setting the frequency (in milliseconds)
in which Client's internal callback poller should poll server for waiting
- callbacks. This configuration is only necessary when using one of the
+ callbacks. The default value is five seconds.</para>
+
+ <para>
+ <emphasis role="bold">CALLBACK_SCHEDULE_MODE</emphasis> (actual value is "scheduleMode"): may be set to either <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> (actual value "scheduleFixedRate") or <code>CallbackPoller.SCHEDULE_FIXED_DELAY</code> (actual value "scheduleFixedDelay"). In either case, polling will take place at approximately regular intervals, but in the former case the scheduler will attempt to perform each poll CALLBACK_POLL_PERIOD milliseconds after the previous attempt, and in the latter case the scheduler will attempt to schedule polling so that the <emphasis>average</emphasis> interval will be approximately CALLBACK_POLL_PERIOD milliseconds. <code>CallbackPoller.SCHEDULE_FIXED_RATE</code> is the default.
+ </para>
+
+ <para>
+ <emphasis role="bold">REPORT_STATISTICS</emphasis> (actual value is "reportStatistics"): The presence of this key in <code>metadata</code>, regardless of its value, will cause the <classname>CallbackPoller</classname> to print statistics that might be useful for configuring the other parameters..
+ </para>
+
+ <para><classname>CallbackPoller</classname>
+ configuration is only necessary when using one of the
following Client methods:</para>
<programlisting>public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject) throws Throwable
public void addListener(InvokerCallbackHandler callbackhandler, Map metadata, Object callbackHandlerObject, boolean serverToClient) throws Throwable</programlisting>
- <para>and should be one of the entries in the metadata Map passed. This
+ <para>The keys should be among the entries in the metadata Map passed. This
will also only apply when the underlying transport is uni-directional
(e.g. socket, http, rmi). Bi-directional transports will not need to poll.
- If this property is not set, the default (see
- CallbackPoller.DEFAULT_POLL_PERIOD) value is five seconds.</para>
+ </para>
<para></para>
More information about the jboss-cvs-commits
mailing list