Class EventListenerSupport<L>

java.lang.Object
org.apache.commons.lang3.event.EventListenerSupport<L>
Type Parameters:
L - the type of event listener that is supported by this proxy.
All Implemented Interfaces:
Serializable

public class EventListenerSupport<L> extends Object implements Serializable

An EventListenerSupport object can be used to manage a list of event listeners of a particular type. The class provides addListener(Object) and removeListener(Object) methods for registering listeners, as well as a fire() method for firing events to the listeners.

To use this class, suppose you want to support ActionEvents. You would do:


 public class MyActionEventSource
 {
   private EventListenerSupport<ActionListener> actionListeners =
       EventListenerSupport.create(ActionListener.class);

   public void someMethodThatFiresAction()
   {
     ActionEvent e = new ActionEvent(this, ActionEvent.ACTION_PERFORMED, "somethingCool");
     actionListeners.fire().actionPerformed(e);
   }
 }
 

Serializing an EventListenerSupport instance will result in any non-Serializable listeners being silently dropped.

Since:
3.0
See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serialization version
      See Also:
    • listeners

      private List<L> listeners
      The list used to hold the registered listeners. This list is intentionally a thread-safe copy-on-write-array so that traversals over the list of listeners will be atomic.
    • proxy

      private transient L proxy
      The proxy representing the collection of listeners. Calls to this proxy object will sent to all registered listeners.
    • prototypeArray

      private transient L[] prototypeArray
      Empty typed array for #getListeners().
  • Constructor Details

    • EventListenerSupport

      public EventListenerSupport(Class<L> listenerInterface)
      Creates an EventListenerSupport object which supports the provided listener interface.
      Parameters:
      listenerInterface - the type of listener interface that will receive events posted using this class.
      Throws:
      NullPointerException - if listenerInterface is null.
      IllegalArgumentException - if listenerInterface is not an interface.
    • EventListenerSupport

      public EventListenerSupport(Class<L> listenerInterface, ClassLoader classLoader)
      Creates an EventListenerSupport object which supports the provided listener interface using the specified class loader to create the JDK dynamic proxy.
      Parameters:
      listenerInterface - the listener interface.
      classLoader - the class loader.
      Throws:
      NullPointerException - if listenerInterface or classLoader is null.
      IllegalArgumentException - if listenerInterface is not an interface.
    • EventListenerSupport

      private EventListenerSupport()
      Create a new EventListenerSupport instance. Serialization-friendly constructor.
  • Method Details

    • create

      public static <T> EventListenerSupport<T> create(Class<T> listenerInterface)
      Creates an EventListenerSupport object which supports the specified listener type.
      Type Parameters:
      T - the type of the listener interface
      Parameters:
      listenerInterface - the type of listener interface that will receive events posted using this class.
      Returns:
      an EventListenerSupport object which supports the specified listener type.
      Throws:
      NullPointerException - if listenerInterface is null.
      IllegalArgumentException - if listenerInterface is not an interface.
    • fire

      public L fire()
      Returns a proxy object which can be used to call listener methods on all of the registered event listeners. All calls made to this proxy will be forwarded to all registered listeners.
      Returns:
      a proxy object which can be used to call listener methods on all of the registered event listeners
    • addListener

      public void addListener(L listener)
      Registers an event listener.
      Parameters:
      listener - the event listener (may not be null).
      Throws:
      NullPointerException - if listener is null.
    • addListener

      public void addListener(L listener, boolean allowDuplicate)
      Registers an event listener. Will not add a pre-existing listener object to the list if allowDuplicate is false.
      Parameters:
      listener - the event listener (may not be null).
      allowDuplicate - the flag for determining if duplicate listener objects are allowed to be registered.
      Throws:
      NullPointerException - if listener is null.
      Since:
      3.5
    • getListenerCount

      int getListenerCount()
      Returns the number of registered listeners.
      Returns:
      the number of registered listeners.
    • removeListener

      public void removeListener(L listener)
      Unregisters an event listener.
      Parameters:
      listener - the event listener (may not be null).
      Throws:
      NullPointerException - if listener is null.
    • getListeners

      public L[] getListeners()
      Gets an array containing the currently registered listeners. Modification to this array's elements will have no effect on the EventListenerSupport instance.
      Returns:
      L[]
    • writeObject

      private void writeObject(ObjectOutputStream objectOutputStream) throws IOException
      Serialize.
      Parameters:
      objectOutputStream - the output stream
      Throws:
      IOException - if an IO error occurs
    • readObject

      private void readObject(ObjectInputStream objectInputStream) throws IOException, ClassNotFoundException
      Deserialize.
      Parameters:
      objectInputStream - the input stream
      Throws:
      IOException - if an IO error occurs
      ClassNotFoundException - if the class cannot be resolved
    • initializeTransientFields

      private void initializeTransientFields(Class<L> listenerInterface, ClassLoader classLoader)
      Initialize transient fields.
      Parameters:
      listenerInterface - the class of the listener interface
      classLoader - the class loader to be used
    • createProxy

      private void createProxy(Class<L> listenerInterface, ClassLoader classLoader)
      Create the proxy object.
      Parameters:
      listenerInterface - the class of the listener interface
      classLoader - the class loader to be used
    • createInvocationHandler

      protected InvocationHandler createInvocationHandler()
      Create the InvocationHandler responsible for broadcasting calls to the managed listeners. Subclasses can override to provide custom behavior.
      Returns:
      ProxyInvocationHandler