Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> eclipse >> osgi >> framework >> [ eventmgr overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

org.eclipse.osgi.framework.eventmgr
Class EventManager  

java.lang.Object
  org.eclipse.osgi.framework.eventmgr.EventManager

---

public class EventManager

extends java.lang.Object

This class is the central class for the Event Manager. Each program that wishes to use the Event Manager should construct an EventManager object and use that object to construct ListenerQueue for dispatching events. EventListeners objects should be used to manage listener lists.

This example uses the ficticous SomeEvent class and shows how to use this package to deliver a SomeEvent to a set of SomeEventListeners.

 		// Create an EventManager with a name for an asynchronous event dispatch thread
 		EventManager eventManager = new EventManager("SomeEvent Async Event Dispatcher Thread");
 		// Create an EventListeners to hold the list of SomeEventListeners
		EventListeners eventListeners = new EventListeners();

		// Add a SomeEventListener to the listener list
	    eventListeners.addListener(someEventListener, null);

		// Asynchronously deliver a SomeEvent to registered SomeEventListeners
		// Create the listener queue for this event delivery
		ListenerQueue listenerQueue = new ListenerQueue(eventManager);
		// Add the listeners to the queue and associate them with the event dispatcher
		listenerQueue.queueListeners(eventListeners, new EventDispatcher() {
	        public void dispatchEvent(Object eventListener, Object listenerObject, 
                                    int eventAction, Object eventObject) {
 				try {
					(SomeEventListener)eventListener.someEventOccured((SomeEvent)eventObject);
 				} catch (Throwable t) {
 					// properly log/handle any Throwable thrown by the listener
 				}
			}
		});
		// Deliver the event to the listeners. 
		listenerQueue.dispatchEventAsynchronous(0, new SomeEvent());
		
		// Remove the listener from the listener list
	    eventListeners.removeListener(someEventListener);

		// Close EventManager to clean when done to terminate async event dispatch thread
		eventManager.close();
 

At first glance, this package may seem more complicated than necessary but it has support for some important features. The listener list supports companion objects for each listener object. This is used by the OSGi framework to create wrapper objects for a listener which are passed to the event dispatcher. The ListenerQueue class is used to build a snap shot of the listeners prior to beginning event dispatch. The OSGi framework uses a 2 level listener list (EventListeners) for each listener type (4 types). Level one is managed by the framework and contains the list of BundleContexts which have registered a listener. Level 2 is managed by each BundleContext for the listeners in that context. This allows all the listeners of a bundle to be easily and atomically removed from the level one list. To use a "flat" list for all bundles would require the list to know which bundle registered a listener object so that the list could be traversed when stopping a bundle to remove all the bundle's listeners. When an event is fired, a snapshot list (ListenerQueue) must be made of the current listeners before delivery is attempted. The snapshot list is necessary to allow the listener list to be modified while the event is being delivered to the snapshot list. The memory cost of the snapshot list is low since the ListenerQueue object shares the array of listeners with the EventListeners object. EventListeners uses copy-on-write semantics for managing the array and will copy the array before changing it IF the array has been shared with a ListenerQueue. This minimizes object creation while guaranteeing the snapshot list is never modified once created. The OSGi framework also uses a 2 level dispatch technique (EventDispatcher). Level one dispatch is used by the framework to add the level 2 listener list of each BundleContext to the snapshot in preparation for delivery of the event. Level 2 dispatch is used as the final event deliverer and must cast the listener and event objects to the proper type before calling the listener. Level 2 dispatch will cancel delivery of an event to a bundle that has stopped bewteen the time the snapshot was created and the attempt was made to deliver the event.

The highly dynamic nature of the OSGi framework had necessitated these features for proper and efficient event delivery.

---

Field Summary
(package private) static boolean	DEBUG
private  EventThread	thread           EventThread for asynchronous dispatch of events.
protected  java.lang.String	threadName           EventThread Name

 

Constructor Summary

EventManager()           EventManager constructor.

EventManager(java.lang.String threadName)           EventManager constructor.

 

Method Summary
void	close()           This method can be called to release any resources associated with this EventManager.
(package private) static void	dispatchEvent(ListElement[] listeners, EventDispatcher dispatcher, int eventAction, java.lang.Object eventObject)           This method calls the EventDispatcher object to complete the dispatch of the event.
(package private)  EventThread	getEventThread()           Returns the EventThread to use for dispatching events asynchronously for this EventManager.

 

Methods inherited from class java.lang.Object

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

 

Field Detail

DEBUG

static final boolean DEBUG

See Also:

Constant Field Values

---

thread

private EventThread thread

EventThread for asynchronous dispatch of events. Access to this field must be protected by a synchronized region.

---

threadName

protected final java.lang.String threadName

EventThread Name

Constructor Detail

EventManager

public EventManager()

EventManager constructor. An EventManager object is responsible for the delivery of events to listeners via an EventDispatcher.

---

EventManager

public EventManager(java.lang.String threadName)

EventManager constructor. An EventManager object is responsible for the delivery of events to listeners via an EventDispatcher.

Method Detail

close

public void close()

This method can be called to release any resources associated with this EventManager.

---

getEventThread

EventThread getEventThread()

Returns the EventThread to use for dispatching events asynchronously for this EventManager.

---

dispatchEvent

static void dispatchEvent(ListElement[] listeners,
                          EventDispatcher dispatcher,
                          int eventAction,
                          java.lang.Object eventObject)

This method calls the EventDispatcher object to complete the dispatch of the event. If there are more elements in the list, call dispatchEvent on the next item on the list. This method is package private.

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> eclipse >> osgi >> framework >> [ eventmgr overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---