org.apache.cayenne.event
Class EventManager

java.lang.Object
  org.apache.cayenne.event.EventManager

public class EventManager
extends Object

This class acts as bridge between an Object that wants to inform others about its current state or a change thereof (Publisher) and a list of objects interested in the Subject (Listeners).

Field Summary

static int	DEFAULT_DISPATCH_THREAD_COUNT
protected List<org.apache.cayenne.event.EventManager.Dispatch>	eventQueue
protected boolean	singleThread
protected boolean	stopped
protected Map<EventSubject,org.apache.cayenne.event.DispatchQueue>	subjects

Constructor Summary

EventManager()
Creates a multithreaded EventManager using default thread count.

EventManager(int dispatchThreadCount)
Creates an EventManager starting the specified number of threads for multithreaded dispatching.

Method Summary

void	addListener(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject) Register an EventListener for events sent by any sender.
void	addListener(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject, Object sender) Register an EventListener for events sent by a specific sender.
protected void	addListener(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject, Object sender, boolean blocking)
void	addNonBlockingListener(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject)
void	addNonBlockingListener(Object listener, String methodName, Class<?> eventParameterClass, EventSubject subject, Object sender)
static EventManager	getDefaultManager() Deprecated. since 3.0 users should create their own instances of EventManager using constructor and share them as appropriate for their target use.
List<org.apache.cayenne.event.EventManager.Dispatch>	getEventQueue() Returns a list of currently queued events.
boolean	isSingleThreaded() Returns true if this EventManager is single-threaded.
void	postEvent(EventObject event, EventSubject subject) Sends an event to all registered objects about a particular subject.
void	postNonBlockingEvent(EventObject event, EventSubject subject) Sends an event to all registered objects about a particular subject.
boolean	removeAllListeners(EventSubject subject) Removes all listeners for a given subject.
boolean	removeListener(Object listener) Unregister the specified listener from all event subjects handled by this EventManager instance.
boolean	removeListener(Object listener, EventSubject subject) Unregister the specified listener for the events about the given subject.
boolean	removeListener(Object listener, EventSubject subject, Object sender) Unregister the specified listener for the events about the given subject and the given sender.
void	shutdown() Stops event threads.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_DISPATCH_THREAD_COUNT

public static final int DEFAULT_DISPATCH_THREAD_COUNT

See Also:

Constant Field Values

subjects

protected Map<EventSubject,org.apache.cayenne.event.DispatchQueue> subjects

eventQueue

protected List<org.apache.cayenne.event.EventManager.Dispatch> eventQueue

singleThread

protected boolean singleThread

stopped

protected volatile boolean stopped

Constructor Detail

EventManager

public EventManager()

Creates a multithreaded EventManager using default thread count.

EventManager

public EventManager(int dispatchThreadCount)

Creates an EventManager starting the specified number of threads for multithreaded dispatching. To create a single-threaded EventManager, use thread count of zero or less.

Method Detail

getDefaultManager

public static EventManager getDefaultManager()

Deprecated. since 3.0 users should create their own instances of EventManager using constructor and share them as appropriate for their target use.

Returns the shared EventManager. It is created on demand on the first call to this method. Cayenne internally doesn't use default EventManager. Instead Configuration EventManager is propagated to DataDomains and DataContexts.

Returns:

EventManager the shared EventManager instance

isSingleThreaded

public boolean isSingleThreaded()

Returns true if this EventManager is single-threaded. If so it will throw an exception on any attempt to register an unblocking listener or dispatch a non-blocking event.

Since:

1.2

getEventQueue

public List<org.apache.cayenne.event.EventManager.Dispatch> getEventQueue()

Returns a list of currently queued events. Queue is returned by copy. This method is useful for inspecting the state of the event queue at any particular moment, but doesn't allow callers to alter the queue state.

Since:

1.1

shutdown

public void shutdown()

Stops event threads. After the EventManager is stopped, it can not be restarted and should be discarded.

Since:

3.0

addListener

public void addListener(Object listener,
                        String methodName,
                        Class<?> eventParameterClass,
                        EventSubject subject)

Register an EventListener for events sent by any sender.

Throws:

RuntimeException - if methodName is not found

See Also:

addListener(Object, String, Class, EventSubject, Object)

addNonBlockingListener

public void addNonBlockingListener(Object listener,
                                   String methodName,
                                   Class<?> eventParameterClass,
                                   EventSubject subject)

addListener

public void addListener(Object listener,
                        String methodName,
                        Class<?> eventParameterClass,
                        EventSubject subject,
                        Object sender)

Register an EventListener for events sent by a specific sender.

Parameters:

listener - the object to be notified about events

methodName - the name of the listener method to be invoked

eventParameterClass - the class of the single event argument passed to methodName

subject - the event subject that the listener is interested in

sender - the object whose events the listener is interested in; null means 'any sender'.

Throws:

RuntimeException - if methodName is not found

addNonBlockingListener

public void addNonBlockingListener(Object listener,
                                   String methodName,
                                   Class<?> eventParameterClass,
                                   EventSubject subject,
                                   Object sender)

addListener

protected void addListener(Object listener,
                           String methodName,
                           Class<?> eventParameterClass,
                           EventSubject subject,
                           Object sender,
                           boolean blocking)

removeListener

public boolean removeListener(Object listener)

Unregister the specified listener from all event subjects handled by this EventManager instance.

Parameters:

listener - the object to be unregistered

Returns:

true if listener could be removed for any existing subjects, else returns false.

removeAllListeners

public boolean removeAllListeners(EventSubject subject)

Removes all listeners for a given subject.

removeListener

public boolean removeListener(Object listener,
                              EventSubject subject)

Unregister the specified listener for the events about the given subject.

Parameters:

listener - the object to be unregistered

subject - the subject from which the listener is to be unregistered

Returns:

true if listener could be removed for the given subject, else returns false.

removeListener

public boolean removeListener(Object listener,
                              EventSubject subject,
                              Object sender)

Unregister the specified listener for the events about the given subject and the given sender.

Parameters:

listener - the object to be unregistered

subject - the subject from which the listener is to be unregistered

sender - the object whose events the listener was interested in; null means 'any sender'.

Returns:

true if listener could be removed for the given subject, else returns false.

postEvent

public void postEvent(EventObject event,
                      EventSubject subject)

Sends an event to all registered objects about a particular subject. Event is sent synchronously, so the sender thread is blocked until all the listeners finish processing the event.

Parameters:

event - the event to be posted to the observers

subject - the subject about which observers will be notified

Throws:

IllegalArgumentException - if event or subject are null

postNonBlockingEvent

public void postNonBlockingEvent(EventObject event,
                                 EventSubject subject)

Sends an event to all registered objects about a particular subject. Event is queued by EventManager, releasing the sender thread, and is later dispatched in a separate thread.

Parameters:

event - the event to be posted to the observers

subject - the subject about which observers will be notified

Throws:

IllegalArgumentException - if event or subject are null

Since:

1.1