org.eclipse.osgi.framework.eventmgr

Class ListenerQueue<K,V,E>

java.lang.Object

org.eclipse.osgi.framework.eventmgr.ListenerQueue<K,V,E>

public class ListenerQueue<K,V,E>
extends Object

The ListenerQueue is used to snapshot the list of listeners at the time the event is fired. The snapshot list is then used to dispatch events to those listeners. A ListenerQueue object is associated with a specific EventManager object. ListenerQueue objects constructed with the same EventManager object will get in-order delivery of events when using asynchronous delivery. No delivery order is guaranteed for synchronous delivery to avoid any potential deadly embraces.

ListenerQueue objects are created as necessary to build a list of listeners that should receive a specific event or events. Once the list is created, the event can then be synchronously or asynchronously delivered to the list of listeners. After the event has been dispatched for delivery, the ListenerQueue object should be discarded as it is likely the list of listeners is stale. A new ListenerQueue object should be created when it is time to deliver another event. The Sets used to build the list of listeners must not change after being added to the list.

Since:

3.1

Field Summary

Fields

Modifier and Type	Field and Description
protected EventManager	manager EventManager with which this queue is associated.

Constructor Summary

Constructors

Constructor and Description
ListenerQueue(EventManager manager) ListenerQueue constructor.

Method Summary

Methods

Modifier and Type	Method and Description
void	dispatchEventAsynchronous(int eventAction, E eventObject) Asynchronously dispatch an event to the snapshot list.
void	dispatchEventSynchronous(int eventAction, E eventObject) Synchronously dispatch an event to the snapshot list.
void	queueListeners(EventListeners<K,V> listeners, EventDispatcher<K,V,E> dispatcher) Deprecated. As of 3.5. Replaced by queueListeners(Set, EventDispatcher).
void	queueListeners(Set<Map.Entry<K,V>> listeners, EventDispatcher<K,V,E> dispatcher) Add a set of listeners to the snapshot list.

Methods inherited from class java.lang.Object

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

Field Detail

manager

protected final EventManager manager

EventManager with which this queue is associated.

Constructor Detail

ListenerQueue

public ListenerQueue(EventManager manager)

ListenerQueue constructor. This method creates an empty snapshot list.

Parameters:

manager - The EventManager this queue is associated with.

Throws:

IllegalArgumentException - If manager is null.

Method Detail

queueListeners

public void queueListeners(EventListeners<K,V> listeners,
                  EventDispatcher<K,V,E> dispatcher)

Deprecated. As of 3.5. Replaced by queueListeners(Set, EventDispatcher).

Add a listener list to the snapshot list. This method can be called multiple times, prior to calling one of the dispatchEvent methods, to build the set of listeners for the delivery of a specific event. The current list of listeners in the specified EventListeners object is added to the snapshot list.

Parameters:

listeners - An EventListeners object to add to the queue. The current listeners in the EventListeners object will be called when an event is dispatched.

dispatcher - An EventDispatcher object to use when dispatching an event to the listeners on the specified EventListeners.

Throws:

IllegalStateException - If called after one of the dispatch methods has been called.

queueListeners

public void queueListeners(Set<Map.Entry<K,V>> listeners,
                  EventDispatcher<K,V,E> dispatcher)

Add a set of listeners to the snapshot list. This method can be called multiple times, prior to calling one of the dispatchEvent methods, to build the list of listeners for the delivery of a specific event. The specified listeners are added to the snapshot list.

Parameters:

listeners - A Set of Map.Entries to add to the queue. This is typically the entrySet from a CopyOnWriteIdentityMap object. This set must not change after being added to this snapshot list.

dispatcher - An EventDispatcher object to use when dispatching an event to the specified listeners.

Throws:

IllegalStateException - If called after one of the dispatch methods has been called.

Since:

3.5

dispatchEventAsynchronous

public void dispatchEventAsynchronous(int eventAction,
                             E eventObject)

Asynchronously dispatch an event to the snapshot list. An event dispatch thread maintained by the associated EventManager is used to deliver the events. This method may return immediately to the caller.

Parameters:

eventAction - This value is passed to the EventDispatcher.

eventObject - This object is passed to the EventDispatcher.

dispatchEventSynchronous

public void dispatchEventSynchronous(int eventAction,
                            E eventObject)

Synchronously dispatch an event to the snapshot list. The event may be dispatched on the current thread or an event dispatch thread maintained by the associated EventManager. This method will not return to the caller until the EventDispatcher has been called (and has returned) for each listener on the queue.

Parameters:

eventAction - This value is passed to the EventDispatcher.

eventObject - This object is passed to the EventDispatcher.