EventListenerSupport
Date: 2017-02-08

org.apache.commons.lang3.event

## 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:
    java.io.Serializable

      public class EventListenerSupport<L>
      extends java.lang.Object
      implements java.io.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:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `EventListenerSupport.ProxyInvocationHandler` An invocation handler used to dispatch the event(s) to all the listeners.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EventListenerSupport(java.lang.Class<L> listenerInterface)` Creates an EventListenerSupport object which supports the provided listener interface.
    `EventListenerSupport(java.lang.Class<L> listenerInterface, java.lang.ClassLoader classLoader)` Creates an EventListenerSupport object which supports the provided listener interface using the specified class loader to create the JDK dynamic proxy.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addListener(L listener)` Registers an event listener.
    `void` | `addListener(L listener, boolean allowDuplicate)` Registers 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()` Create the `InvocationHandler` responsible for broadcasting calls to the managed listeners.
    `L` | `fire()` Returns a proxy object which can be used to call listener methods on all of the registered event listeners.
    `L[]` | `getListeners()` Get an array containing the currently registered listeners.
    `void` | `removeListener(L listener)` Unregisters an event listener.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### EventListenerSupport

          public EventListenerSupport(java.lang.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:
        `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)

      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:
        `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.

    - #### 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:
        `java.lang.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:
        `java.lang.NullPointerException` - if `listener` is `null`.
      Since:
        3.5

    - #### removeListener

          public void removeListener(L listener)

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

    - #### getListeners

          public L[] getListeners()

      Get an array containing the currently registered listeners. Modification to this array's elements will have no effect on the `EventListenerSupport` instance.
      Returns:
        L[]

    - #### createInvocationHandler

          protected java.lang.reflect.InvocationHandler createInvocationHandler()

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