com.zynaptic.reaction

Interface Signal<T>

Type Parameters:

T - This type parameter specifies the type of the data object which will be passed each time the signal is triggered.

public interface Signal<T>

Defines the signal event interface. This provides the user API for manipulating signal event objects. Signal event objects can only be created by using the newSignal method on the Reactor interface.

Method Summary

Methods

Modifier and Type	Method and Description
Signal<T>	makeRestricted() Convert the signal interface to restricted capability.
void	signal(T data) Sends a signal event notification.
void	signalFinalize(T data) Sends a finalising signal event notification.
void	subscribe(Signalable<T> signalable) Subscribes a new signalable object.
void	subscribe(Signalable<T> signalable, int priorityLevel) Subscribes a new signalable object with a specific priority level.
void	unsubscribe(Signalable<T> signalable) Unsubscribes a signalable object.

Method Detail

subscribe

void subscribe(Signalable<T> signalable)
               throws SignalContextException,
                      ReactorNotRunningException

Subscribes a new signalable object. This method is used in order to subscribe a signalable object to this signal, which means that the signalable object will be notified of any events associated with the signal. The signalable object is subscribed with a priority level of zero.

Parameters:

signalable - This is the signalable object which is being subscribed.

Throws:

SignalContextException - This runtime exception is thrown if there is an attempt to subscribe a new signalable object from the context of a signal event callback.

ReactorNotRunningException - This exception is thrown when attempt is made to subscribe to a signal when the reactor is not running.

subscribe

void subscribe(Signalable<T> signalable,
             int priorityLevel)
               throws SignalContextException,
                      ReactorNotRunningException

Subscribes a new signalable object with a specific priority level. This method is used in order to subscribe a signalable object to this signal, which means that the signalable object will be notified of any events associated with the signal. The signalable object is subscribed with the specified priority level. On a signal event, signalable objects will be notified in order of decreasing priority.

Parameters:

signalable - This is the signalable object which is being subscribed.

priorityLevel - This is the priority level which will be used to determine the notification order for subscribed signalable objects. Signalable objects with higher priority levels will be notified of signal events before those with lower priority levels.

Throws:

SignalContextException - This runtime exception is thrown if there is an attempt to subscribe a new signalable object from the context of a signal event callback.

ReactorNotRunningException - This exception is thrown when attempt is made to subscribe to a signal when the reactor is not running.

unsubscribe

void unsubscribe(Signalable<T> signalable)
                 throws SignalContextException,
                        ReactorNotRunningException

Unsubscribes a signalable object. This method is used in order to unsubscribe a signalable object so that it no longer receives event notifications associated with the signal.

Parameters:

signalable - This is the signalable object which is being unsubscribed.

Throws:

SignalContextException - This runtime exception is thrown if there is an attempt to unsubscribe a signalable object from the context of a signal event callback.

ReactorNotRunningException - This exception is thrown when attempt is made to unsubscribe from a signal when the reactor is not running.

signal

void signal(T data)
            throws RestrictedCapabilityException,
                   ReactorNotRunningException

Sends a signal event notification. This method is used in order to trigger the signal event. When called the event will be broadcast to all subscribed signalable objects.

Parameters:

data - This is the signal data parameter which will be passed to each subscribed signalable object in turn. It is good practice to make this parameter object immutable.

Throws:

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

ReactorNotRunningException - This exception is thrown if an attempt is made to signal an event when the reactor is not running.

signalFinalize

void signalFinalize(T data)
                    throws RestrictedCapabilityException,
                           ReactorNotRunningException

Sends a finalising signal event notification. Finalising signals are broadcast to all subscribers in the same way as for a conventional signal event, after which all subscribers are automatically unsubscribed from the signal. This will typically be used to notify shutdown of a service.

Parameters:

data - This is the signal data parameter which will be passed to each subscribed signalable object in turn. It is good practice to make this parameter object immutable.

Throws:

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

ReactorNotRunningException - This exception is thrown if an attempt is made to signal an event when the reactor is not running.

makeRestricted

Signal<T> makeRestricted()

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

Returns:

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