org.ungoverned.oscar.util
Class DispatchQueue

java.lang.Object
  extended byorg.ungoverned.oscar.util.DispatchQueue
Direct Known Subclasses:
OscarDispatchQueue

public class DispatchQueue
extends java.lang.Object

This class implements an event dispatching queue to simplify delivering events to a list of event listener. To use this class, simply create an instance and use it to keep track of your event listeners, much like javax.swing.event.EventListenerList. To dispatch an event, simply create an instance of a Dispatcher and pass the instance to DispatchQueue.dispatch() method, for example:

  Dispatcher d = new Dispatcher() {
      public void dispatch(EventListener l, Object eventObj)
      {
          ((FooListener) l).fooXXX((FooEvent) eventObj);
      }
  };
  FooEvent event = new FooEvent(this);
  dispatchQueue.dispatch(d, FooListener.class, event);
 
In the above code substitute a specific listener and event for the Foo listener and event. Since Dispatchers are reusable, it is probably a good idea to create one for each type of event to be delivered and just reuse them everytime to avoid unnecessary memory allocation.

Currently, the DispatchQueue creates an internal thread with which all events are delivered; this means that events are never delivered using the caller's thread.


Constructor Summary
DispatchQueue()
          Constructs a dispatch queue and starts a dispather thread if necessary.
 
Method Summary
 void addListener(java.lang.Class clazz, java.util.EventListener l)
          Adds a listener to the dispatch queue's listener list; the listener is then able to receive events.
 void dispatch(Dispatcher d, java.lang.Class clazz, java.util.EventObject eventObj)
          Dispatches an event to a set of event listeners using a specified dispatcher object.
protected  void dispatch(java.lang.Object[] listeners, Dispatcher d, java.lang.Class clazz, java.util.EventObject eventObj)
           
 java.util.EventListener getListener(java.lang.Class clazz, java.util.EventListener l)
          Returns the listener if it is already in the dispatch queue.
 java.lang.Object[] getListeners()
          Returns a pointer to the array of event listeners.
 void removeListener(java.lang.Class clazz, java.util.EventListener l)
          Removes a listener from the dispatch queue's listener list; the listener is no longer able to receive events.
static void shutdown()
          Terminates the dispatching thread for a graceful shutdown of the dispatching queue; the caller will block until the dispatching thread has completed all pending dispatches.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DispatchQueue

public DispatchQueue()
Constructs a dispatch queue and starts a dispather thread if necessary.

Method Detail

shutdown

public static void shutdown()
Terminates the dispatching thread for a graceful shutdown of the dispatching queue; the caller will block until the dispatching thread has completed all pending dispatches. Since there is only one thread per all instances of DispatchQueue, this method should only be called prior to exiting the JVM.


getListeners

public java.lang.Object[] getListeners()
Returns a pointer to the array of event listeners. The array stores pairs of associated Class and EventListener objects; a pair corresponds to the arguments passed in to the addListener() method. Even numbered array elements are the class object and odd numbered elements are the corresponding event listener instance.

Returns:
guaranteed to return a non-null object array.

getListener

public java.util.EventListener getListener(java.lang.Class clazz,
                                           java.util.EventListener l)
Returns the listener if it is already in the dispatch queue.

Parameters:
clazz - the class of the listener to find.
l - the listener instance to find.
Returns:
the listener instance or null if the listener was not found.

addListener

public void addListener(java.lang.Class clazz,
                        java.util.EventListener l)
Adds a listener to the dispatch queue's listener list; the listener is then able to receive events.

Parameters:
clazz - the class object associated with the event listener type.
l - the instance of the event listener to add.

removeListener

public void removeListener(java.lang.Class clazz,
                           java.util.EventListener l)
Removes a listener from the dispatch queue's listener list; the listener is no longer able to receive events.

Parameters:
clazz - the class object associated with the event listener type.
l - the instance of the event listener to remove.

dispatch

public void dispatch(Dispatcher d,
                     java.lang.Class clazz,
                     java.util.EventObject eventObj)
Dispatches an event to a set of event listeners using a specified dispatcher object.

Parameters:
d - the dispatcher used to actually dispatch the event; this varies according to the type of event listener.
clazz - the class associated with the target event listener type; only event listeners of this type will receive the event.
eventObj - the actual event object to dispatch.

dispatch

protected void dispatch(java.lang.Object[] listeners,
                        Dispatcher d,
                        java.lang.Class clazz,
                        java.util.EventObject eventObj)