public class EventManager extends Object
This example uses the fictitious 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 a CopyOnWriteIdentityMap to hold the list of SomeEventListeners
Map eventListeners = new CopyOnWriteIdentityMap();
// Add a SomeEventListener to the listener list
eventListeners.put(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.entrySet(), 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.remove(someEventListener);
// Close EventManager to clean when done to terminate async event dispatch thread.
// Note that closing the event manager while asynchronously delivering events
// may cause some events to not be delivered before the async event dispatch
// thread terminates
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 for each listener type (4 types). Level one is managed per framework instance and contains the list of BundleContexts which have registered a listener. Level 2 is managed per 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 uses the copy-on-write semantics of the CopyOnWriteIdentityMap. This guarantees 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 between 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.
| Modifier and Type | Field and Description |
|---|---|
protected ThreadGroup |
threadGroup
The thread group used for asynchronous event delivery
|
protected String |
threadName
Thread name used for asynchronous event delivery
|
| Constructor and Description |
|---|
EventManager()
EventManager constructor.
|
EventManager(String threadName)
EventManager constructor.
|
EventManager(String threadName,
ThreadGroup threadGroup)
EventManager constructor.
|
protected final String threadName
protected final ThreadGroup threadGroup
public EventManager()
public EventManager(String threadName)
threadName - The name to give the event thread associated with
this EventManager. A null value is allowed.public EventManager(String threadName, ThreadGroup threadGroup)
threadName - The name to give the event thread associated with
this EventManager. A null value is allowed.threadGroup - The thread group to use for the asynchronous event
thread associated with this EventManager. A null value is allowed.Copyright © 2007-2016 FuseSource, Corp.. All Rights Reserved.