API change > 1.0.2 to callback handling

In JBossRemoting versions 1.0.2 and before, the method signature within org.jboss.remoting.InvokerCallbackHandler for handling callbacks was:

public void handleCallback(InvocationRequest invocation) throws HandleCallbackException

In version 1.0.1 final the Callback class, which extends the InvocationRequest class, was introduced to be used as the object passed to the handleCallback() method to make it simpler to create the callback payload to be passed.  However, the API for InvokerCallbackHandler was not changed in order to maintain backwards compatibility with all 1.0.x versions.

Post 1.0.x versions, the method signature has been changed to:

public void handleCallback(Callback callback) throws HandleCallbackException

to make is easier to process the callback payload.  The Callback object still extends InvocationRequest, so all the API previously available is still there.

Callback exception handling

When an InvokerCallbackHandler's handleCallback() method is called, it is possible that a HandleCallbackException is thrown.  In many cases, the original cause of the exception can be found by calling the HandleCallbackException's getCause() method. 

Cases in which can expect HandleCallbackException to be thrown:

Pull callbacks:

- If try to persist callback due to being low on memory and get an IOException from the callback store.  The HandleCallbackException's cause will contain the IOException that originally caused the exception.

Push callbacks:

- If there is any Throwable exception that occurs trying to send the callback to the client callback handler.  The original exception will be set as the cause.  This will include any exceptions thrown by the client's InvokerCallbackHandler's handleCallback() method.  The only exception to this would be if the client's InvokerCallbackHandler's handleCallback() method itself throws a HandleCallbackException, which will be thrown as is to the original caller.

How callbacks work

The document below explains how push and pull callbacks work.  It includes details on both the design and the implementation.