[jboss-cvs] JBossRemoting/docs/guide/en ...

[Tom Elrod]

  User: telrod  
  Date: 06/09/22 01:51:28

  Modified:    docs/guide/en  chap5.xml
  Log:
  JBREM-363 - updating remoting doc to include more info on setting up callbacks for uni and bi directional transports (to simulate push callback via internal polling for uni-directional transports).
  
  Revision  Changes    Path
  1.12      +57 -0     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.11
  retrieving revision 1.12
  diff -u -b -r1.11 -r1.12
  --- chap5.xml	25 Aug 2006 19:50:01 -0000	1.11
  +++ chap5.xml	22 Sep 2006 05:51:28 -0000	1.12
  @@ -2676,6 +2676,63 @@
   
         <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>