org.eclipse.osgi.framework.eventmgr
Class ListenerQueue

java.lang.Object
  extended by org.eclipse.osgi.framework.eventmgr.ListenerQueue

public class ListenerQueue
extends java.lang.Object

The ListenerQueue is used to snapshot the set 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 using asynchronous delivery. No delivery order is guaranteed for synchronous delivery to avoid any potential deadly embraces.

ListenerQueue objects are created as necesssary to build a set of listeners that should receive a specific event or events. Once the set is created, the event can then be synchronously or asynchronously delivered to the set 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 memory cost of a ListenerQueue object is low since the ListenerQueue object shares the array of listeners with the EventListeners object which are queued. EventListeners uses copy-on-write semantics for managing the array and will copy the array before changing it once the array has been shared with a ListenerQueue. This minimizes object creation while guaranteeing the snapshot list is never modified once created.

Since:
3.1

Field Summary
protected  EventManager manager
          EventManager with which this queue is associated.
 
Constructor Summary
ListenerQueue(EventManager manager)
          ListenerQueue constructor.
 
Method Summary
 void dispatchEventAsynchronous(int eventAction, java.lang.Object eventObject)
          Asynchronously dispatch an event to the snapshot list.
 void dispatchEventSynchronous(int eventAction, java.lang.Object eventObject)
          Synchronously dispatch an event to the snapshot list.
 void queueListeners(EventListeners listeners, EventDispatcher dispatcher)
          Add a listener list 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 snapshop list.

Parameters:
manager - The EventManager this queue is associated with.
Throws:
java.lang.IllegalArgumentException - If manager is null.
Method Detail

queueListeners

public void queueListeners(EventListeners listeners,
                           EventDispatcher dispatcher)
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:
java.lang.IllegalStateException - If called after one of the dispatch methods has been called.

dispatchEventAsynchronous

public void dispatchEventAsynchronous(int eventAction,
                                      java.lang.Object 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,
                                     java.lang.Object 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.