Package org.lsst.ccs.utilities.dispatch

The Observer/observable pattern may come in different flavors offered by this package.

See:
Description

Interface Summary

ASyncObserver<P>	An Observable that needs parrallel processing of updates.
CommandFor<T>	This interface defines the behaviour of a class implementing a Command pattern.
Invoker
SynchronousCommandFor<T>	This marker interface is used to specify that implementers of the code executing the command explicitly acknowledge that the caller is waiting for completion of the command.
SynchronousObserver<P>	An Observer that knows that its code should terminate quickly because it is invoked in sequence by the SynchronousObservable.

Class Summary

InvocationDispenser	Typical use of this pattern is to have two threads: one is going to write commands to a stream.
ParallelCommandDispatcher<T>	Dispatches a Command object to registered "executants" able to handle the command; each command execution may be handled by a different Thread so every registered agent does not have to wait for termination of code from the previous call.
ParallelDispatchProxy<I>	Instances of this class creates a dynamic proxy that parallely dispatches method call to registered agents implementing an interface type.
ParallelObservable<P>	An Observable that notifies Observers through an ExecutorService (that is through different threads).
SynchronousCommandDispatcher<T>	Registers codes interested in receiving commands.
SynchronousDispatchProxy<I>	Instances of this class creates a dynamic proxy that dispatches method call to registered agents implementing an interface type.
SynchronousObservable<P>	An Observable with protocol control at compile time.

Exception Summary

InvocationDispenser.TokenLostException

Package org.lsst.ccs.utilities.dispatch Description

The Observer/observable pattern may come in different flavors offered by this package.

Primarily there are two main concerns addressed in the codes of this package:

• Control over the parameter passed to method notifyObservers and received by update : this control is through the use of a parameterized type. At compile-time we can now check what is sent and what is received (named here the "protocol").
• Explicit specification of the nature of code dispatching: "synchronous" means that the update codes of the Observer are executed in sequence and that the implementers are conscious that thus their code should terminate quickly; "parallel" means that the update codes are executed by different Threads. In both cases the nature of the update method is procedural (no return type) and exceptions are logged (they should not crash the system).
  TODO: change the logging to log4j

So the "traditional" Observer/Observable pair can be replaced by SynchronousObserver and SynchronousObservable. The main differences are:

• method update takes no reference to the Observable (if you need one: create an Event like protocol that has a reference to the sender).
• method notifyObservers does not need a previous call to setChanged

If parallel processing is needed use instead ASyncObserver and ParallelObservable .

Now why limit notifications to a single method? We may go through different methods....

So there are two different patterns in this package to handle calls to different methods for the registered agents:

• Use of a Command pattern: see interfaces CommandFor, SynchronousCommandFor and Observable-like classes SynchronousCommandDispatcher, ParallelCommandDispatcher
• Use of a Proxy: in that case the Observer classes should implement an interface class that is passed to a proxy generator (SynchronousDispatchProxy or ParallelDispatchProxy). These classes generate a very special object implementing the requested interface: a call to a method of this object is automatically forwarded to all the registered agents that implement the same interface.