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

<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.
void	cancelTimeout() Cancels the timeout associated with the deferred event.
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.
void	setTimeout(int msTimeout) Sets the timeout associated with the deferred event.

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.

setTimeout

void 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.

Throws:

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

cancelTimeout

void 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.

discard

void discard()

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.