7.3 Using Deferred Event Splitters

The deferred event splitter is used to `fork' a single callback chain so that callbacks may be processed in parallel by multiple output callback chains. This is typically used when there are multiple client components which need to wait on the same underlying transaction. An example of this is shown in Listing 7.6. The full version of this example is present in the deferred examples package as DeferredSplitterExample.

% latex2html id marker 1977\begin{small}\begin{verbatim}...
...m} \end{small}\caption{Example of Using a Deferred Event Splitter}

In this example a deferred event splitter object is created using the reactor's factory method. A number of deferrable callback handlers are then created, which are attached to the outputs of the deferred event splitter. Output deferred event objects are created dynamically on calling the getOutputDeferred method, so an arbitrary number of output callback chains can be attached.

The example then initiates a long running task and attaches the resulting deferred event object to the input of the deferred event splitter using the addInputDeferred method. Finally, more output handlers can be attached if required. The deferred splitter component differs from the deferred concentrator in that the only constraint is that the addInputDeferred method must be called exactly once. Extra output callback chains can be attached even after the input callback chain has triggered, since the output of the input callback chain is cached for the lifetime of the deferred splitter object.

It is important to note that when the callback on the input deferred event object is triggered, the data parameter which is passed by that callback will be passed in turn to each of the registered output callback chains. Therefore callback handlers attached to the outputs of a deferred splitter object must not make any changes to the parameter data object which is passed to them. In order to ensure that this is the case, it is recommended that all parameter data objects passed to the input of a deferred event splitter are made immutable.

The handling of errback conditions by the deferred event splitter is essentially the same as for callback handling. The exception object which is passed as the input errback parameter will be forwarded in turn to each of the registered output errback chains. Again, output errback handlers should not modify the underlying exception object during processing.