[jboss-cvs] JBossRemoting/docs/guide/en ...
Ron Sigal
ron_sigal at yahoo.com
Tue Mar 6 23:23:25 EST 2007
User: rsigal
Date: 07/03/06 23:23:25
Modified: docs/guide/en Tag: remoting_2_x chap5.xml
Log:
JBREM-634: Updated section on callbacks.
Revision Changes Path
No revision
No revision
1.12.2.2 +372 -89 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.12.2.1
retrieving revision 1.12.2.2
diff -u -b -r1.12.2.1 -r1.12.2.2
--- chap5.xml 3 Nov 2006 19:11:15 -0000 1.12.2.1
+++ chap5.xml 7 Mar 2007 04:23:24 -0000 1.12.2.2
@@ -867,18 +867,41 @@
<title>How the server bind address and port is ultimately
determined</title>
- <para>If the serverBindAddress property is set, it will be used for
- binding. If the serverBindAddress is not set, but the
- clientConnectAddress property is set, the server invoker will bind to
- local host address. If neither the serverBindAddress nor the
- clientConnectAddress properties are set, then will try to bind to the
- host specified within the InvokerLocator. If the host value of the
- InvokerLocator is also not set, will bind to local host.</para>
-
- <para>If there is a system property called 'remoting.bind_by_host' and
- if is false, will bind by IP address instead of host. Otherwise will use
- host name. This only applies when configured address is 0.0.0.0. To
- facilitate setting this property, the following static variable is
+ <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
+ 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
+ in the InvokerLocator, the server will bind to the address of the local
+ host, as determined by the call</para>
+
+ <programlisting>
+ InetAddress.getLocalHost().getHostAddress();
+ </programlisting>
+
+ <para>In other words, the logic is
+ </para>
+
+ <programlisting>
+ if (serverBindAddress is set)
+ use it
+ else if (the host is present in the InvokerLocator and clientConnectAddress is not set)
+ use host from InvokerLocator
+ else
+ use local host address
+ </programlisting>
+
+ <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>
+
+ <programlisting>
+ InetAddress.getLocalHost().getHostName();
+ </programlisting>
+
+ <para>If 'remoting.bind_by_host' is set to false, then local host address will
+ be used. To facilitate setting this property, the following static variable is
defined in <classname>InvokerLocator</classname>:</para>
<programlisting>
@@ -2608,24 +2631,345 @@
<section>
<title>Callback overview</title>
- <para>Although this section covers callback configuration, will need to
- first cover a little general information about callbacks within
- remoting. There are two models for callbacks, push and pull. In the push
- model, the client will register a callback server via an InvokerLocator
+ <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.</para>
+ 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
+ </para>
+
+ <programlisting>
+ public void addListener(InvokerCallbackHandler callbackHandler);
+ </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.
+ </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.
+ </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>.
+ </para>
+ </section>
+
+ <section>
+ <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
+ </para>
+
+ <programlisting>
+ public void handleCallback(Callback callback) throws HandleCallbackException;
+ </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.
+ </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
+ </para>
+
+ <programlisting>
+ public void handleCallbackOneway(Callback callback) throws HandleCallbackException;
+
+ public void handleCallbackOneway(Callback callback, boolean serverSide)) throws HandleCallbackException;
+ </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
+ </para>
+
+ <programlisting>
+ public void invokeOneway(final Object param, final Map sendPayload, boolean clientSide) throws Throwable;
+ </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.
+ </para>
+ </section>
+
+ <section>
+ <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.
+ </para>
+
+ <para>
+ An object that implements the <classname>org.jboss.remoting.callback.CallbackListener</classname> interface
+ </para>
+
+ <programlisting>
+ public interface CallbackListener
+ {
+ /**
+ * @param callbackHandler InvokerCallbackHandler that handled this callback
+ * @param callbackId id of callback being acknowledged
+ * @param response either (1) response sent with acknowledgement or (2) null
+ */
+ void acknowledgeCallback(InvokerCallbackHandler callbackHandler, Object callbackId, Object response);
+ }
+ </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.
+ </para>
+
+ <para>
+ There are two ways in which callbacks can be acknowledged:
+ </para>
+
+ <orderedlist>
+ <listitem>explicit acknowledgements, and</listitem>
+ <listitem>automatic acknowledgements.</listitem>
+ </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.
+ </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
+ </para>
+
+ <programlisting>
+ public int acknowledgeCallback(InvokerCallbackHandler callbackHandler, Callback callback) throws Throwable;
+
+ public int acknowledgeCallback(InvokerCallbackHandler callbackHandler, Callback callback, Object response) throws Throwable;
+
+ public int acknowledgeCallbacks(InvokerCallbackHandler callbackHandler, List callbacks) throws Throwable;
+
+ public int acknowledgeCallbacks(InvokerCallbackHandler callbackHandler, List callbacks, List responses) throws Throwable;
+ </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.
+ </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>.
+ </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>.
+ </para>
+
+ </section>
+ </section>
+
+ <section id="section-callback-handlers" xreflabel="Registering callback handlers">
+
+ <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>
+
+ <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
+ <classname>Client</classname> class:
+ </para>
+
+ <programlisting>
+ public void addListener(InvokerCallbackHandler) throws Throwable;
+
+ public void addListener(InvokerCallbackHandler callbackHandler, InvokerLocator clientLocator) throws Throwable;
+
+ public void addListener(InvokerCallbackHandler callbackHandler, InvokerLocator clientLocator, Object callbackHandlerObject) throws Throwable;
+ </programlisting>
+
+ <para>
+ where, in the latter two cases, the <code>clientLocator</code> parameter is set to null.
+ </para>
+
+ <para>
+ The callbacks stored for a pull callback connection may be retrieved by calling the
+ </para>
+
+ <programlisting>
+ public List getCallbacks(InvokerCallbackHandler callbackHandler) throws Throwable
+ </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.
+ </para>
+
+ </section>
+
+ <section>
+ <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
+ 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>
+
+ <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
+ 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>
+ interface which functions as an invocation handler for callbacks. Like
+ implementations of
+ <classname>org.jboss.remoting.ServerInvocationHandler</classname> on
+ the server side, implementations of
+ <classname>InvokerCallbackHandler</classname> are supplied by
+ the application. When a <classname>ServerInvocationHandler</classname>
+ generates a callback object, it will be sent to the callback
+ <classname>Connector</classname>, which will, in turn, deliver it to
+ the <classname>InvokerCallbackHandler</classname>
+ </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>.
+ </para>
+
+ <para>
+ There are two ways to set up push callback handling, each of which
+ entails the use of one of the overloaded
+ <methodname>addListener()</methodname> methods in the
+ <classname>Client</classname> class:
+ </para>
+
+ <orderedlist>
+ <listitem>explicit creation of a <classname>Connector</classname>
+ </listitem>
+
+ <listitem>implicit configuration.
+ </listitem>
+ </orderedlist>
+
+ <para>
+ In the first case, the application creates a <classname>Connector</classname>
+ and passes its <classname>InvokerLocator</classname>, along with an
+ implementation of <classname>InvokerCallbackHandler</classname>, to
+ one of the following versions of
+ <methodname>addListener()</methodname>:
+ </para>
- <para>The other model, pull callbacks, allows the client to call on the
- target server to collect the callback messages waiting for it. The
- target server then has to manage these callback messages on the server
+ <programlisting>
+ public void addListener(InvokerCallbackHandler callbackHandler, InvokerLocator clientLocator) throws Throwable;
+
+ public void addListener(InvokerCallbackHandler callbackHandler,InvokerLocator clientLocator, Object callbackHandlerObject) throws Throwable;
+ </programlisting>
+
+ <para>
+ 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>
+
+ <programlisting>
+ public void addListener(InvokerCallbackHandler callbackhandler, Map metadata) throws Throwable;
+
+ 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>
+ 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.
+ </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.
+ </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.
+ </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>.
+ </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.
+ </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.
+ </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>
+ 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>
+
+ </section>
+
+ <section>
+ <title>Unregistering callback handlers</title>
+
+ <para>
+ Callback connections are torn down through a call to the method
+ </para>
+
+ <programlisting>
+ public void removeListener(InvokerCallbackHandler callbackHandler) throws Throwable;
+ </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.
+ </para>
+
+ </section>
+
+ <section id="section-pull-callback-configuration" xreflabel="Server side configuration for pull callbacks">
+ <title>Server side configuration of pull callbacks</title>
+
+ <para>
+ For pull callbacks (and also simulated push callbacks), the
+ server has to manage callback messages
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 persistence policy.
- This 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 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
<code>memPercentCeiling</code> attribute (see more on configuring this
below).</para>
@@ -2701,67 +3045,6 @@
<para>Once a callback client has been removed as a listener, all
persisted callbacks will be removed from disk.</para>
- <para>There are several ways in which callbacks can be configured. The
- main distinction in type of callback setup is whether is a push
- (asynchronous) or pull (synchronous) callback. To setup callback
- handling to be done using the pull model, use one of the addListener()
- methods and pass a null InvokerLocator as one of the parameters. This
- will cause the server to collect callbacks and wait for them to be
- collected (by calling the Client.getCallbacks(InvokerCallbackHandler)
- method). For push callback handling, there are a few ways this can be
- configured. The first is to create a Connector for receiving callbacks
- from the server and pass the InvokerLocator for that Connector to the
- addListener() method of the client. When a server generates a callback
- object, it will be sent to the callback Connector, which will in turn,
- deliver it to the InvokerCallbackHandler originally registered. Another
- way to configure push callbacks is to let remoting take care of managing
- callback delivery internally (meaning does not require user to create a
- Connector for callbacks). If the client is in an environment where the
- server will be allowed to establish a connection to the client, could
- call the addLIstener() method with the 'serverToClient' parameter set to
- true. This will cause remoting to automatically create a callback
- Connector on behalf of the user (which behaves the same as though the
- user had created one and passed the InvokerLocator as a parameter to the
- addListner() method). If the client is not in an environment where the
- server is allowed to establish a network connection to the client (e.g.
- firewall rules disallow it), can still have remoting emulate push
- callbacks. In this case, remoting will check the transport protocol
- being used to see if it is bi-directional or uni-directional. A
- transport is bi-directional if is allows communication from the server
- to the client over the same physical network connection originally
- established by the client to the server (i.e. multiplex). If the
- transport is bi-directional, remoting know that it is safe to setup a
- callback Connector internally for receiving callbacks. A transport is
- uni-directional if communication from a server to a client requires a
- new network connection to be established (i.e. socket, http, rmi). In
- this case, remoting internally setup pull callbacks with the target
- server and automatically poll for callback messages. When callbacks are
- available and are pulled from the server, remoting will deliver them to
- the InvokerCallbackHandler originally registered (which emulates a true
- push model to the user). Configuration: /** * Key for the configuration
- when adding a callback handler and internal callback server * connector
- is created. The value should be the transport protocol to be used. By
- default * will use the same protocol as being used by this client (e.g.
- http, socket, rmi, multiplex, etc.) */ public static final String
- CALLBACK_SERVER_PROTOCOL = "callbackServerProtocol"; /** * Key for the
- configuration when adding a callback handler and internal callback
- server * connector is created. The value should be the host name to be
- used. By default * will use the result of calling
- InetAddress.getLocalHost().getHostAddress(). */ public static final
- String CALLBACK_SERVER_HOST = "callbackServerHost"; /** * Key for the
- configuration when adding a callback handler and internal callback
- server * connector is created. The value should be the port to be used.
- By default * will find a random unused port. */ public static final
- String CALLBACK_SERVER_PORT = "callbackServerPort"; /** * The key value
- to use to specify the desired poll period * within the metadata Map. */
- public static final String CALLBACK_POLL_PERIOD = "callbackPollPeriod";
- Transport types: bi-directional - multiplex, local uni-directional -
- http, socket, rmi</para>
- </section>
-
- <section>
- <title>Callback Configuration</title>
-
<para>All callback configuration will need to be defined within the
invoker configuration, since the invoker is the parent that creates the
callback servers as needed (when client registers for pull callbacks).
More information about the jboss-cvs-commits
mailing list