Interface EventManager

public interface EventManager
Dispatches events to listeners, and provides ways for listeners to register themselves.

An event manager allows users to publish events to previously registered listeners. The modular style allows plugins or modules to hook and unhook into/from the system dynamically. It is not designed for inter-process communication.

To receive an event a listener must:

  1. Define a method taking a single argument, the Event it wants to subscribe to.
  2. Mark that method with a EventListener annotation.
  3. Pass the listener class instance to registerListener(Object).

Note: event execution is always a blocking operation, NEVER should an event listener receive event notifications simultaneously. By default, no event listener will be called when any event publish is ongoing. Other implementations are free to change this behaviour as long as there are no calls to the same event listener simultaneously.

Since:
4.0
See Also:

  • Method Details

    • unregisterListeners

      @NonNull @NonNull EventManager unregisterListeners(@NonNull @NonNull ClassLoader classLoader)
      Unregisters all listeners in classes which were loaded by the given class loader.
      Parameters:
      classLoader - the loader based onm which to unregister listeners.
      Returns:
      the same event manager as used to call the method, for chaining.
      Throws:
      NullPointerException - if class loader is null.

    • unregisterListener

      @NonNull @NonNull EventManager unregisterListener(Object @NonNull ... listeners)
      Unregisters all listeners which were registered in each of the given listener classes.
      Parameters:
      listeners - the classes to unregister all listeners of.
      Returns:
      the same event manager as used to call the method, for chaining.
      Throws:
      NullPointerException - if any listener instance is null.

    • callEvent

      @NonNull default <T extends Event> T callEvent(@NonNull T event)
      Calls the given event to the * channel, triggering all event listeners which are listening to it.

      This method call is equivalent to callEvent("*", event).

      Type Parameters:
      T - the type of the event.
      Parameters:
      event - the event to call.
      Returns:
      the same event as used to call the method, after processing.
      Throws:
      NullPointerException - if the given event is null.
      EventListenerException - if any listener threw an exception while processing the event.

    • callEvent

      @NonNull <T extends Event> T callEvent(@NonNull @NonNull String channel, @NonNull T event)
      Calls the given event to the given channel, only triggering the event listeners which are specifically listening to the given channel unless the channel is *.
      Type Parameters:
      T - the type of the event.
      Parameters:
      channel - the specific channel to call the listeners on.
      event - the event to call.
      Returns:
      the same event as used to call the method, after processing.
      Throws:
      NullPointerException - if the given channel or event is null.
      EventListenerException - if any listener threw an exception while processing the event.

    • registerListener

      @NonNull @NonNull EventManager registerListener(@NonNull @NonNull Class<?> listenerClass)
      Registers all methods in the given listener class which are annotated with EventListener and are taking only one argument with a subtype of Event. The instance the constructed event listeners are bound to are created by requesting it from the default external injection layer.

      This method accepts public, protected, default (package) access, and private methods but will not include inherited methods at all.

      All methods which are not annotated with EventListener, are static and are not taking one or more arguments are silently ignored.

      Parameters:
      listenerClass - the class to create an instance of and register all listeners in.
      Returns:
      the same event manager as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given listener class is null.
      IllegalArgumentException - if an event listener target doesn't take an event as it's first argument.

    • registerListener

      @NonNull @NonNull EventManager registerListener(@NonNull @NonNull Object listener)
      Registers all methods in the given listener class which are annotated with EventListener and are taking only one argument with a subtype of Event.

      This method accepts public, protected, default (package) access, and private methods but will not include inherited methods at all.

      All methods which are not annotated with EventListener, are static and are not taking one or more arguments are silently ignored.

      Parameters:
      listener - the instance of the listener to register the methods in.
      Returns:
      the same event manager as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given listener is null.
      IllegalArgumentException - if an event listener target doesn't take an event as it's first argument.

    • registerListeners

      @NonNull default @NonNull EventManager registerListeners(Object @NonNull ... listeners)
      Registers all listeners which are in the given listener classes individually to this event manager.
      Parameters:
      listeners - the listeners to register.
      Returns:
      the same event manager as used to call the method, for chaining.
      Throws:
      NullPointerException - if one of the given listeners is null.
      IllegalArgumentException - if an event listener target doesn't take an event as it's only argument.
      See Also: