org.ceryle.util.event
Class EventManager

java.lang.Object
  org.ceryle.util.event.EventManager

public class EventManager
extends Object

A singleton class that manages the addition and removal of ChangeListeners to a event source, as well as the firing of events to those listeners. An "event source" is the class delegating its event handling to an implementation of the EventDelegate interface, in this case, the (inner) delegating class EventManager.EventDelegateImpl supplied by this manager. The class being serviced is considered a "client" of the EventDelegate.

This class was originally written for a generic EventObject but there was then no useful listener signature, so ChangeEvents were settled on.

This permits consolidation of all event listeners and their associated methods in one place rather than having them attached to specific subcomponents of an application, and avoids a great deal of event-related cut-and-paste code. Convenience methods that call the EventManager for event delegation can be written to maintain existing APIs.

If you want to provide delegate service outside the bounds of this manager, you can use EventSourceDelegate.

Using a Delegate for Event Listener Management

Basically, rather than have all manner of client classes maintain their own listener lists, add and remove listener methods, any class wanting to attach listeners can simply request a delegate object to provide that service. The delegate handles the listener list, the add and remove listener methods. Firing events is then a matter of calling the EventManager's fireEvent(Object,ChangeEvent) method, where the Object is the client. Prior to instantiating the event object, the client can call isListening(Object) to see there are any listeners attached to its delegate.

Adding Listeners

Adding a ChangeListener to an object is very simple:

      EventManager.addChangeListener(object,
              new ChangeListener() {
                  public void stateChanged( ChangeEvent e ) {
                      YourObject o = (YourObject)e.getSource();
                      // react to event...
                  }
              });
  

Firing Events

To fire an event from your class, use something akin to this:

      private final void fireEvent()
      {
          if ( EventManager.isListening(this) ) {
              EventManager.fireEvent(this,new ChangeEvent(this));
          }
      }
  

Removing Listeners

Removing a ChangeListener from an object is very simple:

      EventManager.removeChangeListener(object,listener);
  

If you only have a reference to the listener, the following method will remove it from any clients managed by the EventManager:

      EventManager.removeChangeListener(listener);
  

Preloading Listeners

This may be used to create listeners for objects that don't yet exist, particularly designed for embedded applications that need to be able to listen for the instantiation of an Object, by maintaining a cache of client-less event sources that set their client upon being popped from the cache. Each time the getDelegateFor(Object) method is called with a null parameter it will preload an internal cache with a client-less EventDelegate that will be popped and returned in preference to creating a new object. This can have unwanted side effects if there are multiple clients populating the cache with listeners. The only check is for a Class match, so be aware if others might be populating the client-less cache with listeners.

Since:

2.4.20

Author:

Murray Altheim

Nested Class Summary

class

EventManager.EventDelegateImpl Inner delegating class that manages event listener addition and removal.

Method Summary

static void	addChangeListener(Object client, ChangeListener listener) Registers a ChangeListener with a EventDelegate for the provided client object.
static void	fireEvent(Object client, ChangeEvent event) Notify all listeners of the EventDelegate having a registered interest in change events of the supplied Event.
static Set	getChangeListeners(Object client) Return the Set containing the ChangeListeners attached to the delegate for the supplied client.
EventDelegate	getDelegateFor(Object client) Returns a EventDelegate for the provided client Object.
static EventManager	getInstance() As this is a singleton class, this returns the single instance of this class provided with the property file filename and bit-wise application settings.
static boolean	isListening(Object client) Returns true if there are one or more listeners registered with the provided client Object (undelegated event source).
static boolean	removeChangeListener(ChangeListener listener) Un-registers a ChangeListener from any EventDelegate client managed by this EventManager.
static void	removeChangeListener(Object client, ChangeListener listener) Un-registers a ChangeListener with the EventDelegate for the provided client object.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static EventManager getInstance()

As this is a singleton class, this returns the single instance of this class provided with the property file filename and bit-wise application settings.

addChangeListener

public static final void addChangeListener(Object client,
                                           ChangeListener listener)

Registers a ChangeListener with a EventDelegate for the provided client object.

Parameters:

client - the client of the event source

listener - the event listener

removeChangeListener

public static final void removeChangeListener(Object client,
                                              ChangeListener listener)

Un-registers a ChangeListener with the EventDelegate for the provided client object.

Parameters:

client - the client of the event source

listener - the event listener

getChangeListeners

public static final Set getChangeListeners(Object client)

Return the Set containing the ChangeListeners attached to the delegate for the supplied client. If there are no attached listeners, returns an empty Iterator rather than null. Note that this will create a delegate for the client if it did not exist prior to the call.

NOTE

This method returns a Set rather than an Iterator because of the high likelihood of the Set being modified while an Iterator might be active. This returns an unmodifiable reference to the actual Set containing the delegate's listeners. Any attempt to modify the Set will throw an UnsupportedOperationException. This method is not synchronized and it should be understood that the composition of the backing Set may change at any time.

Parameters:

client - the client of the event source

Returns:

an unmodifiable Set containing the ChangeListeners attached to the client

Throws:

UnsupportedOperationException - if any attempt is made to modify the Set

removeChangeListener

public static final boolean removeChangeListener(ChangeListener listener)

Un-registers a ChangeListener from any EventDelegate client managed by this EventManager. Since this is a one-to-one relation, the first match will be returned upon removal; a true return value indicates the ChangeListener was found and removed.

Parameters:

listener - the event listener

Returns:

true if the listener was found and removed.

isListening

public static boolean isListening(Object client)

Returns true if there are one or more listeners registered with the provided client Object (undelegated event source). This locates any delegate and checks to see if it has any listeners attached.

Parameters:

client - the client Object

fireEvent

public static void fireEvent(Object client,
                             ChangeEvent event)

Notify all listeners of the EventDelegate having a registered interest in change events of the supplied Event.

Parameters:

client - the client initiating the event.

event - the Event to fire.

getDelegateFor

public EventDelegate getDelegateFor(Object client)

Returns a EventDelegate for the provided client Object. If the parameter is a class reference, will generate and return a client-less EventDelegate. If the parameter is not a Class and the delegate cache contains any objects matching the Class of any delegates in the cache, the first Class-matching delegate will be used in preference to creating a new delegate. If a null parameter is supplied, this will create a client-less delegate that will attach to the first incoming client (i.e., there will be no Class-matching requirement).

Parameters:

client - the client Object, or alternately a Class reference

Returns:

the EventDelegate.