org.perfectjpattern.core.api.behavioral.observer
Interface ISubject<E>

Type Parameters:

E - Type of event data that this ISubject notifies with.

All Known Subinterfaces:

IParameterlessSubject

All Known Implementing Classes:

AsynchronousSubject, ParameterlessSubject, Subject

public interface ISubject<E>

Observer Design Pattern: Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically. (Gamma et al, Design Patterns)

Responsibility: Abstract generic definition of the "Subject". pattern role:

• Knows its observers. Any number of IObserver objects may observe a ISubject.
• Provides an interface for attaching and detaching IObserver objects.

Notes: Improves over the original GoF recipe and Java Observer implementation in that:

• Push over Pull approach: IObserver instances are not coupled to the ISubject interface i.e. there is no need for the IObserver to query ISubject's state. State change or Message content is pushed to the notifyObservers(E) callback method.
• Strongly typed generic parameter eliminates the need for IObserver to downcast the parameter as is the case for e.g. java.util.Observer implementation.

Example usage:

    //
    // Create Observer Pattern elements 
    //  
    ISubject<NullEventData> mySubject = new ConcreteSubject();
    IObserver<NullEventData> myFirstObserver = new ConcreteObserver();
    IObserver<NullEventData> mySecondObserver = new ConcreteObserver();
    
    //
    // Subscribe multiple Observer instances to the Subject
    //
    mySubject.attach(myFirstObserver, mySecondObserver);
    
    //
    // Notify all subscribed Observers, optionally pass some Event 
    // data associated with the Event.
    //
    mySubject.notifyObservers(NullEventData.getInstance());
    
    //
    // Detach Observer instances
    //
    mySubject.detach(myFirstObserver);
 

Version:

$Revision: 1.0 $ $Date: Jun 11, 2007 6:21:08 AM $

Author:

Giovanni Azua

Method Summary

void	attach(IObserver<E>... anObservers) Attaches a variable list of IObserver instances to the ISubject instance.
void	clear() Detaches all registered IObserver instances from this ISubject
void	detach(IObserver<E>... anObservers) Detaches a variable list of IObserver instances from the ISubject instance.
void	notifyObservers(E anEventData) Notifies the attached IObserver instances that a change has occurred.
int	size() Returns the number of attached IObserver instances

Method Detail

attach

void attach(IObserver<E>... anObservers)

Attaches a variable list of IObserver instances to the ISubject instance.

Parameters:

anObservers - IObserver instances to be attached.

Throws:

IllegalArgumentException - 'anObservers' must not be null.

clear

void clear()

Detaches all registered IObserver instances from this ISubject

detach

void detach(IObserver<E>... anObservers)

Detaches a variable list of IObserver instances from the ISubject instance.

Parameters:

anObservers - IObserver instances to be detached.

Throws:

IllegalArgumentException - 'anObservers' must not be null.

notifyObservers

void notifyObservers(E anEventData)

Notifies the attached IObserver instances that a change has occurred. It is compulsory to provide a non null parameter anEventData. For situations where passing information is not required use instead NullEventData singleton instance.

Parameters:

anEventData - Event data pushed to IObserver instances.

Throws:

IllegalArgumentException - 'anEventData' must not be null.

size

int size()

Returns the number of attached IObserver instances

Returns:

Number of attached IObserver instances.