Package org.threadly.concurrent.event

Class ListenerHelper<T>

  • Type Parameters:
    T - Interface for listeners to implement and called into with
    Direct Known Subclasses:
    AsyncCallListenerHelper, DefaultExecutorListenerHelper
    public class ListenerHelper<T>
extends java.lang.Object
    Class which assist with holding and calling to listeners of any interface. In parallel designs it is common to have things subscribe for actions to occur (to later be alerted once an action occurs). This class makes it easy to allow things to register as a listener.

    For listener designs which do NOT need to provide arguments for their listeners, look at using RunnableListenerHelper. RunnableListenerHelper is more efficient and flexible for listeners of that type. It also has a cleaner and easier to use interface.

    Since:
    2.2.0

    • Constructor Summary

      Constructors 
      Constructor Description
      ListenerHelper​(java.lang.Class<? super T> listenerInterface)
      Constructs a new ListenerHelper that will handle listeners with the provided interface.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addListener​(T listener)
      Adds a listener to be executed on the next call() to this instance.
      void addListener​(T listener, java.util.concurrent.Executor executor)
      Adds a listener to be executed on the next call() to this instance.
      T call()
      Calls to notify the subscribed listeners with the given call.
      void clearListeners()
      Removes all listeners currently registered.
      java.util.Collection<T> getSubscribedListeners()
      Return a collection of the currently subscribed listener instances.
      int registeredListenerCount()
      Returns how many listeners were added, and will be ran on the next call() invocation.
      boolean removeListener​(T listener)
      Attempts to remove a listener waiting to be called.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • ListenerHelper

        public ListenerHelper​(java.lang.Class<? super T> listenerInterface)
        Constructs a new ListenerHelper that will handle listeners with the provided interface. The provided class MUST be an interface.
        Parameters:
        listenerInterface - Interface that listeners need to implement

    • Method Detail

      • getSubscribedListeners

        public java.util.Collection<T> getSubscribedListeners()
        Return a collection of the currently subscribed listener instances. This returned collection can NOT be modified.
        Returns:
        A non-null collection of currently subscribed listeners

      • call

        public T call()
        Calls to notify the subscribed listeners with the given call. This returns an implementation of the listener interface, you can then call to the function you wish to have called on the listeners (of course providing the arguments you want the listeners to be called with).

        Any calls off the returned instance will execute on all subscribed listeners. If those listeners were provided with an executor the execution for calling that listener will happen on the provided executor. If no executor was provided, the execution of the listener will happen on the thread invoking this call.

        Returns:
        Implementation of listener interface to have call subscribed listeners

      • addListener

        public void addListener​(T listener)
        Adds a listener to be executed on the next call() to this instance. This is the same as adding a listener and providing null for the Executor.
        Parameters:
        listener - Listener to be called when call() is invoked

      • addListener

        public void addListener​(T listener,
                        java.util.concurrent.Executor executor)
        Adds a listener to be executed on the next call() to this instance. If an executor is provided, on the next call() a task will be put on the executor to call this listener. If none is provided, the listener will be executed on the thread that is invoking the call().

        If an Executor is provided, and that Executor is NOT single threaded, the listener may be called concurrently. You can ensure this wont happen by using the KeyDistributedExecutor to get an executor from a single key, or by using the ExecutorLimiter with a limit of one, or an instance of the SingleThreadScheduler.

        Parameters:
        listener - Listener to be called when call() is invoked
        executor - Executor to call listener on, or null

      • removeListener

        public boolean removeListener​(T listener)
        Attempts to remove a listener waiting to be called.
        Parameters:
        listener - listener instance to be removed
        Returns:
        true if the listener was removed

      • clearListeners

        public void clearListeners()
        Removes all listeners currently registered.

      • registeredListenerCount

        public int registeredListenerCount()
        Returns how many listeners were added, and will be ran on the next call() invocation.
        Returns:
        number of listeners registered to be called