org.exolab.castor.util
Class EventListenerList
java.lang.Object
org.exolab.castor.util.EventListenerList
- Serializable
public class EventListenerList
extends java.lang.Object
implements Serializable
This class is an efficient repository for EventListeners based
on javax.swing.EventListenerList.
This modification of javax.swing.EventListenerList retains the
core functionality of that class but changes the basic API and adds
a few more features, as summarized below:
- javax.swing.EventListenerList requires all listeners to be
added in conjunction with a class object that identified the type
of the listener. This implementation's add methods simply take the
listener object.
- The listener list returned from javax.swing.EventListenerList
had to be iterated over in a cumbersome manner because the
listeners were stored along with their Class objects in the array.
Since listener classes are not stored in this listener list, the
returned listener array can be iterated over normally (1 element at
a time).
- The remove method in javax.swing.EventListenerList had return
type "void". This implementation's remove method returns true if
the specified listener was found in the listener array and false
otherwise.
- This implementation adds
add(EventListener,int)
,
which allows the addition of a listener at a specific position in
the array.
- The add and remove methods in this implementation throw
IllegalArgumentExceptions when their arguments are null.
As is the case with javax.swing.EventListenerList, this class
provides multi-threaded safety through a copy-on-modify strategy.
It is optimized to provide high performance when events are being
fired, with slightly slower performance than the Collection API
when listeners are being added and removed. Like its predecessor,
this class will never return a null array from getListenerList.
The most important thing to keep in mind when using this class
is that the array returned by getListenerList is the actual
internal array of this class and MUST NOT BE MODIFIED UNDER ANY
CIRCUMSTANCES. Below is an example of how to use this class,
borrowed (and slightly modified) from the
javax.swing.EventListenerList documentation:
Usage example:
Say one is defining a class that sends out FooEvents, and one wants
to allow users of the class to register FooListeners and receive
notification when FooEvents occur. The following should be added
to the class definition:
EventListenerList listenerList = new EventListenerList();
FooEvent fooEvent = null;
public void addFooListener(FooListener l) {
listenerList.add(l);
}
public void removeFooListener(FooListener l) {
listenerList.remove(l);
}
// Notify all listeners that have registered interest for
// notification on this event type. The event instance
// is lazily created using the parameters passed into
// the fire method.
protected void fireFooXXX() {
// Guaranteed to return a non-null array
EventListener[] listeners = listenerList.getListenerList();
// Process the listeners last to first, notifying
// those that are interested in this event
for (int i = 0 ; i < listeners.length ; i++) {
// Lazily create the event:
if (fooEvent == null)
fooEvent = new FooEvent(this);
((FooListener)listeners[i]).fooXXX(fooEvent);
}
}
foo should be changed to the appropriate name, and fireFooXxx to the
appropriate method name. One fire method should exist for each
notification method in the FooListener interface.
The authors of javax.swing.EventListenerList are Georges Saab,
Hans Muller, and James Gosling.
$Revision: 1.1.1.1 $ $Date: 2003/03/03 07:09:04 $protected EventListener[] | listenerList - The internal list of listeners that is returned from
getListenerList
|
void | add(EventListener newListener) - Adds the listener to the end of the listener list.
|
void | add(EventListener newListener, int index) - Adds the listener at the specified index in the listener
list.
|
int | getListenerCount() - Returns the total number of listeners in this listener
list.
|
EventListener[] | getListenerList() - Passes back the event listener list as an array of
EventListeners.
|
boolean | remove(EventListener listenerToRemove) - Removes the listener as a listener of the specified type.
|
String | toString() - Returns a string representation of the EventListenerList.
|
listenerList
protected EventListener[] listenerList
The internal list of listeners that is returned from
getListenerList
add
public void add(EventListener newListener)
Adds the listener to the end of the listener list.
newListener
- the listener to be added
add
public void add(EventListener newListener,
int index)
Adds the listener at the specified index in the listener
list.
newListener
- the listener to be added
getListenerCount
public int getListenerCount()
Returns the total number of listeners in this listener
list.
getListenerList
public EventListener[] getListenerList()
Passes back the event listener list as an array of
EventListeners.
Note that for performance reasons, this implementation passes
back the actual data structure in which the listener data is
stored internally! This method is guaranteed to pass back a
non-null array, so that no null-checking is required in fire
methods. A zero-length array of Object will be returned if
there are currently no listeners.
WARNING!!! Absolutely NO modification of
the data contained in this array should be made -- if
any such manipulation is necessary, it should be done
on a copy of the array returned rather than the array
itself.
remove
public boolean remove(EventListener listenerToRemove)
Removes the listener as a listener of the specified type.
toString
public String toString()
Returns a string representation of the EventListenerList.
Intalio Inc. (C) 1999-2003. All rights reserved http://www.intalio.com