Class EventListenerList

  • All Implemented Interfaces:
    java.io.Serializable

    public class EventListenerList
    extends java.lang.Object
    implements java.io.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:

    1. 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.
    2. 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).
    3. 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.
    4. This implementation adds add(EventListener, int), which allows the addition of a listener at a specific position in the array.
    5. 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.

    Version:
    $Revision: 5951 $ $Date: 2005-12-13 14:58:48 -0700 (Tue, 13 Dec 2005) $
    Author:
    Jeff Norris
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.EventListener[] listenerList
      The internal list of listeners that is returned from getListenerList
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(java.util.EventListener newListener)
      Adds the listener to the end of the listener list.
      void add​(java.util.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.
      java.util.EventListener[] getListenerList()
      Passes back the event listener list as an array of EventListeners.
      boolean remove​(java.util.EventListener listenerToRemove)
      Removes the listener as a listener of the specified type.
      java.lang.String toString()
      Returns a string representation of the EventListenerList.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • listenerList

        protected transient java.util.EventListener[] listenerList
        The internal list of listeners that is returned from getListenerList
    • Constructor Detail

      • EventListenerList

        public EventListenerList()
    • Method Detail

      • getListenerList

        public java.util.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.
      • getListenerCount

        public int getListenerCount()

        Returns the total number of listeners in this listener list.

      • add

        public void add​(java.util.EventListener newListener)

        Adds the listener to the end of the listener list.

        Parameters:
        newListener - the listener to be added
        Throws:
        java.lang.IllegalArgumentException - if the specified newListener is null
      • add

        public void add​(java.util.EventListener newListener,
                        int index)

        Adds the listener at the specified index in the listener list.

        Parameters:
        newListener - the listener to be added
        Throws:
        java.lang.IllegalArgumentException - if the specified newListener is null, or the specified index is less than zero or greater than the length of the listener list array.
      • remove

        public boolean remove​(java.util.EventListener listenerToRemove)
        Removes the listener as a listener of the specified type.
        Parameters:
        listenerToRemove - the listener to be removed
        Throws:
        java.lang.IllegalArgumentException - if the specified listener is null
      • toString

        public java.lang.String toString()
        Returns a string representation of the EventListenerList.
        Overrides:
        toString in class java.lang.Object