Package org.apache.commons.lang3.event

Class EventListenerSupport<L>

  • Type Parameters:
    L - the type of event listener that is supported by this proxy.
    All Implemented Interfaces:
    java.io.Serializable
    public class EventListenerSupport<L>
extends java.lang.Object
implements java.io.Serializable
    Manages a list of event listeners of a given generic type. This class provides addListener(Object) and removeListener(Object) methods for managing listeners, as well as a fire() method for firing events to the listeners.

    For example, to support ActionEvents: 

    
 public class MyActionEventSource {

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

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

    Events are fired

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

    Since:
    3.0
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.List<L> listeners
      Hold the registered listeners.
      private L[] prototypeArray
      Empty typed array for #getListeners().
      private L proxy
      The proxy representing the collection of listeners.
      private static long serialVersionUID
      Serialization version

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private EventListenerSupport()
      Constructs a new EventListenerSupport instance.
        EventListenerSupport​(java.lang.Class<L> listenerInterface)
      Constructs an EventListenerSupport object which supports the provided listener interface.
        EventListenerSupport​(java.lang.Class<L> listenerInterface, java.lang.ClassLoader classLoader)
      Constructs an EventListenerSupport object which supports the provided listener interface using the specified class loader to create the JDK dynamic proxy.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addListener​(L listener)
      Adds an event listener.
      void addListener​(L listener, boolean allowDuplicate)
      Adds an event listener.
      static <T> EventListenerSupport<T> create​(java.lang.Class<T> listenerInterface)
      Creates an EventListenerSupport object which supports the specified listener type.
      protected java.lang.reflect.InvocationHandler createInvocationHandler()
      Creates the InvocationHandler responsible for calling to the managed listeners.
      private void createProxy​(java.lang.Class<L> listenerInterface, java.lang.ClassLoader classLoader)
      Creates the proxy object.
      L fire()
      Returns a proxy object which can be used to call listener methods on all of the registered event listeners.
      (package private) int getListenerCount()
      Gets the number of registered listeners.
      L[] getListeners()
      Gets an array containing the currently registered listeners.
      private void initializeTransientFields​(java.lang.Class<L> listenerInterface, java.lang.ClassLoader classLoader)
      Initializes transient fields.
      private void readObject​(java.io.ObjectInputStream objectInputStream)
      Deserializes the next object into this instance.
      void removeListener​(L listener)
      Removes an event listener.
      private void writeObject​(java.io.ObjectOutputStream objectOutputStream)
      Serializes this instance onto the given ObjectOutputStream.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        Serialization version
        See Also:
        Constant Field Values

      • listeners

        private java.util.List<L> listeners
        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 be sent to all registered listeners.

      • prototypeArray

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

    • Constructor Detail

      • EventListenerSupport

        private EventListenerSupport()
        Constructs a new EventListenerSupport instance.

        This constructor is needed for serialization.

      • EventListenerSupport

        public EventListenerSupport​(java.lang.Class<L> listenerInterface)
        Constructs 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:
        java.lang.NullPointerException - if listenerInterface is null.
        java.lang.IllegalArgumentException - if listenerInterface is not an interface.

      • EventListenerSupport

        public EventListenerSupport​(java.lang.Class<L> listenerInterface,
                            java.lang.ClassLoader classLoader)
        Constructs 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:
        java.lang.NullPointerException - if listenerInterface or classLoader is null.
        java.lang.IllegalArgumentException - if listenerInterface is not an interface.

    • Method Detail

      • create

        public static <T> EventListenerSupport<T> create​(java.lang.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:
        java.lang.NullPointerException - if listenerInterface is null.
        java.lang.IllegalArgumentException - if listenerInterface is not an interface.

      • addListener

        public void addListener​(L listener)
        Adds an event listener.

        Listeners are called in the order added.

        Parameters:
        listener - the event listener (may not be null).
        Throws:
        java.lang.NullPointerException - if listener is null.

      • addListener

        public void addListener​(L listener,
                        boolean allowDuplicate)
        Adds an event listener. Will not add a pre-existing listener object to the list if allowDuplicate is false.

        Listeners are called in the order added.

        Parameters:
        listener - the event listener (may not be null).
        allowDuplicate - the flag for determining if duplicate listener objects are allowed to be registered.
        Throws:
        java.lang.NullPointerException - if listener is null.
        Since:
        3.5

      • createInvocationHandler

        protected java.lang.reflect.InvocationHandler createInvocationHandler()
        Creates the InvocationHandler responsible for calling to the managed listeners. Subclasses can override to provide custom behavior.
        Returns:
        ProxyInvocationHandler

      • createProxy

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

      • 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

      • getListenerCount

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

      • 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[]

      • initializeTransientFields

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

      • readObject

        private void readObject​(java.io.ObjectInputStream objectInputStream)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
        Deserializes the next object into this instance.
        Parameters:
        objectInputStream - the input stream
        Throws:
        java.io.IOException - if an IO error occurs
        java.lang.ClassNotFoundException - if the class cannot be resolved

      • removeListener

        public void removeListener​(L listener)
        Removes an event listener.
        Parameters:
        listener - the event listener (may not be null).
        Throws:
        java.lang.NullPointerException - if listener is null.

      • writeObject

        private void writeObject​(java.io.ObjectOutputStream objectOutputStream)
                  throws java.io.IOException
        Serializes this instance onto the given ObjectOutputStream.
        Parameters:
        objectOutputStream - the output stream
        Throws:
        java.io.IOException - if an IO error occurs