Register callback handlers with push callbacks
This topic has not yet been written. The content below is from the topic description.
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: true push callbacks and simulated push callbacks, also known as polled callbacks. In the case of true push callbacks, there is a Remoting object on the server side (an org.jboss.remoting.callback.ServerInvokerCallbackHandler) which uses a Client to make invocations to the client side. On the client side there is a Connector and an implementation of the org.jboss.remoting.callback.InvokerCallbackHandler interface which functions as an invocation handler for callbacks. Like implementations of org.jboss.remoting.ServerInvocationHandler on the server side, implementations of InvokerCallbackHandler are supplied by the application. When a ServerInvocationHandler generates a callback object, it will be sent to the callback Connector, which will, in turn, deliver it to the InvokerCallbackHandler 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 org.jboss.remoting.callback.CallbackPoller) on the client side which periodically retrieves the callbacks and, as in the case of true push callbacks, delivers them to the InvokerCallbackHandler. There are two ways to set up push callback handling, each of which entails the use of one of the overloaded addListener() methods in the Client class: explicit creation of a Connector implicit configuration. In the first case, the application creates a Connector and passes its InvokerLocator, along with an implementation of InvokerCallbackHandler, to one of the following versions of addListener(): public void addListener( InvokerCallbackHandler callbackHandler, InvokerLocator clientLocator) throws Throwable; public void addListener( InvokerCallbackHandler callbackHandler,InvokerLocator clientLocator, Object callbackHandlerObject) throws Throwable; Because there is a Connector, explicit configuration always results in true push callbacks. In the case of implicit configuration, only the InvokerCallbackHandler is passed and Remoting takes care of the rest. One of the following versions of addListener() is used: 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; Note that the latter three methods are distinguished from the first two by the presence of the metadata parameter, which can be used to configure the callback connection. Depending on the transport being used and the parameters supplied to addListener(), 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 addLIstener() could be used with the serverToClient parameter set to true. In this case, regardless of the transport, Remoting will automatically create a callback Connector on behalf of the user, which behaves just as though the user had created it and passed the InvokerLocator as a parameter to addListener(). Note. Since release 2.5.1, if the first instance of the parameter org.jboss.remoting.Client.USE_ALL_PARAMS (actual value "useAllParams") found successively in the InvokerLocator, the Client's configuration map, or the metadata map is set to "true", then polled callbacks can be configured by parameters in the InvokerLocator and Client's configuration map as well as the metadata map passed to addListener(). 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 ServerSocket), then there are two options. One is to use one of the bidirectional transports, each of which has a strategy for the creation of a connection from the server to the client without connecting a client Socket to a ServerSocket. There are currently three bidirectional transports: local (i.e., the client and server reside in the same JVM), bisocket, and multiplex (deprecated). When one of the second set of addListener() methods is invoked for a bidirectional transport, it will create a callback Connector, even if serverToClient is set to false. The other option is to use any of the unidirectional transports (socket, http, rmi) with serverToClient set to false (which is the default value if it is not an explicit parameter), in which case, Remoting will configure polled callbacks. The implicitly created callback Connectors are available for reuse. Each Client maintains a set of all callback Connectors it has implicitly created for each InvokerCallbackHandler that is passed in by way of one of the addListener() methods. For example, InvokerCallbackHandler callbackHandler = new SampleCallbackHandler(); client.addListener(callbackHandler, new HashMap(), null, true); client.addListener(callbackHandler, new HashMap(), null, true); would result in a set of two callback Connectors associated with callbackHandler. These sets of callback Connectors are accessible by way of the Client method public Set getCallbackConnectors(InvokerCallbackHandler callbackHandler); A callback Connector could be reused as in the following code: InvokerCallbackHandler callbackHandler1 = new SampleCallbackHandler(); client.addListener(callbackHandler1, new HashMap(), null, true); Set callbackConnectors = client.getCallbackConnectors(callbackHandler1); Connector callbackConnector = (Connector) callbackConnectors.iterator().next(); InvokerCallbackHandler callbackHandler2 = new SampleCallbackHandler(); client.addListener(callbackHandler2, callbackConnector.getLocator()); which would result in the implicitly created callback Connector having two registered InvokerCallbackHandlers. Note, by the way, that if the InvokerCallbackHandler were reused as in the following: InvokerCallbackHandler callbackHandler1 = new SampleCallbackHandler(); client.addListener(callbackHandler1, new HashMap(), null, true); Set callbackConnectors = client.getCallbackConnectors(callbackHandler1); Connector callbackConnector = (Connector) callbackConnectors.iterator().next(); client.addListener(callbackHandler1, callbackConnector.getLocator()); then only one callback connection would be created, because a single (Connector, InvokerCallbackHandler) pair can be associated with only one callback connection. Note. As of Remoting version 2.4, there are two versions of pull callbacks: non-blocking (original) and blocking (new). For more information, see Pull callbacks. Since the CallbackPoller uses pull callbacks, this distinction is relevant to polled callbacks as well. The default behavior of CallbackPoller is to use non-blocking mode, but blocking mode can be requested by using the key ServerInvoker.BLOCKING_MODE set to ServerInvoker.BLOCKING in the metadata map passed to Client.addListener(). There are nine parameters that can be passed to Client.addListener() in the metadata map which are specific to push callback configuration. The first three 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 org.jboss.remoting.Client class, and the keys related to polled callbacks are defined in the org.jboss.remoting.callback.CallbackPoller class (with the exception of ServerInvoker.BLOCKING_MODE and ServerInvoker.BLOCKING_TIMEOUT). CALLBACK_SERVER_PROTOCOL (actual value is "callbackServerProtocol): the transport protocol to be used for callbacks. By default it will be the protocol used by the Client upon which addListener() is invoked. CALLBACK_SERVER_HOST (actual value is "callbackServerHost"): the host name to be used by the callback server. By default it will be the result of calling InetAddress.getLocalHost().getHostAddress(). CALLBACK_SERVER_PORT (actual value is "callbackServerPort"): the port to be used by the callback server. By default it will be a randomly chosen unused port. CALLBACK_POLL_PERIOD (actual value is "callbackPollPeriod"): the interval in milliseconds between attempts to download callbacks from the server. CALLBACK_SCHEDULE_MODE (actual value is "scheduleMode"): may be set to either CallbackPoller.SCHEDULE_FIXED_RATE (actual value "scheduleFixedRate") or CallbackPoller.SCHEDULE_FIXED_DELAY (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 average interval will be approximately CALLBACK_POLL_PERIOD milliseconds. CallbackPoller.SCHEDULE_FIXED_RATE is the default. REPORT_STATISTICS (actual value is "reportStatistics"): The presence of this key in metadata, regardless of its value, will cause the CallbackPoller to print statistics that might be useful for configuring the other parameters.. MAX_ERROR_COUNT (actual value is "maxErrorCount"): determines the maximum number of errors that may be experienced during polling before CallbackPoller will shut itself down. The default value is "5". SYNCHRONIZED_SHUTDOWN (actual value is "doSynchronizedShutdown"): if set to "true", CallbackPoller.stop() will wait for Client.getCallbacks() 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". BLOCKING_MODE (actual value is "blockingMode"): if set to ServerInvoker.BLOCKING (actual value "blocking"), CallbackPoller will do blocking polled callbacks, and if set to ServerInvoker.NONBLOCKING (actual value "nonblocking"), CallbackPoller will do non-blocking polled callbacks. BLOCKING_TIMEOUT (actual value is "blockingTimeout"): the value is used as the per-invocation timeout Note that all of the elements in metadata will be passed to the callback Connector and appended to its InvokerLocator. Note. As of Remoting version 2.4, 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. [This feature has been ported to Remoting release 2.2.2.GA, so it exists in later versions of the 2.2 family]. The parameter is org.jboss.remoting.callback.ServerInvokerCallbackHandler.CALLBACK_TIMEOUT (actual value "callbackTimeout"), and it should be used to configure the Connector. In the absence of ServerInvokerCallbackHandler.CALLBACK_TIMEOUT, the timeout value configured for the Connector will be used.