com.zynaptic.reaction

Interface Deferred<T>

Type Parameters:

T - This type parameter specifies the type of data which will be emitted by the deferred event object at the end of the current callback chain.

public interface Deferred<T>

Defines the deferred event interface. This is the public interface to the deferred event objects implemented by the Reaction framework. Deferred event objects are used to manage callback chains comprising multiple deferrable objects.

Method Summary

Methods

Modifier and Type	Method and Description
<U> Deferred<U>	addDeferrable(Deferrable<T,U> deferrable) Attaches a deferrable object to the deferred event.
<U> Deferred<U>	addDeferrable(Deferrable<T,U> deferrable, boolean terminal) Attaches a deferrable object to the deferred event.
void	callback(T data) Issues a deferred callback.
Deferred<T>	cancelTimeout() Cancels the timeout associated with the deferred event.
T	defer() Performs a synchronous wait for the deferred callback results.
void	discard() Discards the deferred event.
void	errback(java.lang.Exception error) Issues an error callback.
Deferred<T>	makeRestricted() Convert the deferred interface to restricted capability.
Deferred<T>	setTimeout(int msTimeout) Sets the timeout associated with the deferred event.
Deferred<T>	terminate() Terminates a deferred callback chain.

Method Detail

callback

void callback(T data)
              throws RestrictedCapabilityException,
                     DeferredTriggeredException

Issues a deferred callback. This issues a callback which propagates to the first deferrable object to have been attached to this deferred event. This call is used to notify the attached deferrable objects of successful completion. If this method is called while the reactor is not running, the callback chain will be triggered with an errback encapsulating an exception of type ReactorNotRunningException instead.

Parameters:

data - This parameter is a data object of type T which is used to pass data back to the deferrable object.

Throws:

RestrictedCapabilityException - This runtime exception is thrown if an attempt is made to call this method on a deferred event object reference with restricted capability.

DeferredTriggeredException - This runtime exception is raised if the deferred event has already been triggered via the callback or errback methods.

errback

void errback(java.lang.Exception error)
             throws RestrictedCapabilityException,
                    DeferredTriggeredException

Issues an error callback. This issues an error callback to the first deferrable object to have been attached to this deferred event. This call is used to notify the attached deferrables of error conditions. If this method is called while the reactor is not running, the callback chain will be triggered with an errback encapsulating an exception of type ReactorNotRunningException instead.

Parameters:

error - The error parameter passes an exception object which can be used to identify the error condition.

Throws:

RestrictedCapabilityException - This exception is thrown if an attempt is made to call this method on a deferred event object reference with restricted capability.

DeferredTriggeredException - This runtime exception is raised if the deferred event has already been triggered via the callback or errback methods.

addDeferrable

<U> Deferred<U> addDeferrable(Deferrable<T,U> deferrable,
                            boolean terminal)
                          throws DeferredTerminationException

Attaches a deferrable object to the deferred event. Multiple deferrable objects can be attached, forming a callback chain. The callbacks on deferrable objects are called in the same order in which they are added to the deferred event object. Deferrable objects specify their input and output data types, and the parameterised type of the deferred event object will be updated to match the new output type each time a new deferrable object is added to the callback chain.

Type Parameters:

U - This type parameter specifies the data type which is returned by the onCallback and onErrback methods of the deferrable object which is being added to the callback chain.

Parameters:

deferrable - This is the deferrable object which is to be added to the callback chain. It may be a link deferrable or a terminal deferrable, depending on the state of the terminal parameter.

terminal - This flag is set to indicate that this deferrable should terminate the callback chain. Once a terminal deferrable has been added no further deferrables can be added.

Returns:

Returns a reference to this deferred object where the parameterised data type has been modified to match the return type declared by the deferrable object. In order to maintain type consistency, this new reference should then be used for adding further deferrable objects to the deferred callback chain.

Throws:

DeferredTerminationException - This runtime exception is raised if the deferred callback chain has already been terminated by adding a terminal deferrable.

addDeferrable

<U> Deferred<U> addDeferrable(Deferrable<T,U> deferrable)
                          throws DeferredTerminationException

Attaches a deferrable object to the deferred event. Multiple deferrable objects can be attached, forming a callback chain. The callbacks on deferrable objects are called in the same order in which they are added to the deferred event object. Deferrable objects specify their input and output data types, and the parameterised type of the deferred event object will be updated to match the new output type each time a new deferrable object is added to the callback chain.

Type Parameters:

U - This type parameter specifies the data type which is returned by the onCallback and onErrback methods of the deferrable object which is being added to the callback chain.

Parameters:

deferrable - This is the deferrable object which is to be added to the callback chain.

Returns:

Returns a reference to this deferred object where the parameterised data type has been modified to match the return type declared by the deferrable object. In order to maintain type consistency, this new reference should then be used for adding further deferrable objects to the deferred callback chain.

Throws:

DeferredTerminationException - This runtime exception is raised if the deferred callback chain has already been terminated by adding a terminal deferrable.

terminate

Deferred<T> terminate()
                      throws DeferredTerminationException

Terminates a deferred callback chain. This method is used to terminate a deferred callback chain without adding any further deferrable callback objects.

Returns:

Returns a reference to the current Deferred interface, allowing fluent-style callback chain termination.

Throws:

DeferredTerminationException - This runtime exception is raised if the deferred callback chain has already been terminated, or if no deferrable callback handlers have previously been added to the callback chain.

setTimeout

Deferred<T> setTimeout(int msTimeout)
                       throws ReactorNotRunningException

Sets the timeout associated with the deferred event. The timeout is scheduled for the specified number of milliseconds after this call was made. If the timeout expires before the deferred event has been triggered it generates an errback call, passing an exception of type DeferredTimedOutException as the parameter. By default no timeout is set. If this function is called multiple times, the most recently requested timeout is used. A timeout value of zero or less may be used to force an immediate timeout.

Parameters:

msTimeout - This is the timeout to be used by the deferred event, specified as an integer number of milliseconds.

Returns:

Returns a reference to the current Deferred interface, allowing fluent-style timeout assignments.

Throws:

ReactorNotRunningException - This exception is thrown if an attempt is made to set a deferred timeout when the reactor is not running.

cancelTimeout

Deferred<T> cancelTimeout()

Cancels the timeout associated with the deferred event. If there is an outstanding timeout it will be cancelled, otherwise this call has no effect.

Returns:

Returns a reference to the current Deferred interface, allowing fluent-style timeout assignments.

discard

void discard()
             throws DeferredTerminationException

Discards the deferred event. There are circumstances where an API call may return a deferred event for which the caller has no use. Ignoring the deferred results in an unterminated deferred going out of scope, which is reported in the logs as an error. This method terminates the deferred with a default deferrable which simply discards any callbacks and reports any errback conditions to the log.

Throws:

DeferredTerminationException - This runtime exception is raised if the deferred callback chain has already been terminated by adding a terminal deferrable.

makeRestricted

Deferred<T> makeRestricted()

Convert the deferred interface to restricted capability. This method should be used to restrict the capability of a deferred interface so that the callback and errback methods are protected from unauthorised use.

Returns:

Returns a version of the current Deferred interface with restricted capability.

defer

T defer()
        throws DeferredContextException,
               java.lang.Exception

Performs a synchronous wait for the deferred callback results. This method causes the current thread to block until the deferred event has been triggered and the callback results passed back. It must not be called from within the main reactor thread context (ie, not from within any timed, signalled or deferred callback handlers).

Returns:

Returns the callback parameter passed back via the deferred callback chain.

Throws:

DeferredContextException - This exception will be thrown if an attempt is made to call this method from within the context of the main reactor thread.

java.lang.Exception - This arbitrary exception will be thrown if an error condition has been passed back via the deferred errback chain. The types of exception which may be thrown are dependent on the error conditions which may occur for a given application call.