Interface EventBus

public interface EventBus
A framework for firing events and listening to them.

To listen to events, use registerListener(Class, byte, EventConsumer). The returned Listener may be unregistered later.

The event bus has guarantees regarding inheritance of events. When an event is fired, every listener which specified an event type which is assignment compatible with the event object will be invoked. That is, the listener will be called if the event is an instance of the specified event type.

Note well that, unlike some other event buses, implementations are required to provide consistent ordering of all listeners invoked by this method according to their priorities, as opposed to merely ordering within listeners specifying a certain event class. Thus, all applicable listeners to an event are always invoked in order of priority, no matter which event nor its inheritance heirarchy.

To fire events, implement Event or AsyncEvent on the event object and use one of the firing methods.

Null parameters are not permitted on any method. NullPointerException is thrown otherwise
Author:
A248

  • Method Details

    • fireEvent

      <E extends Event> void fireEvent(E event)
      Fires an event, invoking all applicable listeners.

      Events capable of asynchronous listeners should not use this method. Attempting to do so will throw IllegalArgumentException
      Type Parameters:
      E - the event type
      Parameters:
      event - the event itself
      Throws:
      IllegalArgumentException - if event is an AsyncEvent

    • fireAsyncEvent

      <E extends AsyncEvent> CompletableFuture<E> fireAsyncEvent(E event)
      Fires an asynchronous capable event, invoking all applicable listeners.

      For dealing with asynchronous listeners, this method returns a future. The future will never complete exceptionally, but if an asynchronous listener somehow fails its responsibility to continue the event execution, the future may stall. Therefore callers should choose an appropriate timeout using CompletableFuture.orTimeout(long, java.util.concurrent.TimeUnit)
      Type Parameters:
      E - the event type
      Parameters:
      event - the event itself
      Returns:
      a future completed once all listeners have completed firing. The future yields the event, for convenience.

    • fireAsyncEventWithoutFuture

      <E extends AsyncEvent> void fireAsyncEventWithoutFuture(E event)
      Fires an asynchronous capable event, invoking all applicable listeners.

      This is equivalent to fireAsyncEvent(AsyncEvent) except that any resulting future is discarded (creation of the future may be altogether avoided). This should be used when the caller wishes to proceed regardless of any listener modifications to the event.
      Type Parameters:
      E - the event type
      Parameters:
      event - the event itself

    • registerListener

      <E extends Event> RegisteredListener registerListener(Class<E> eventClass, byte priority, EventConsumer<? super E> eventConsumer)
      Creates and registers a listener, returning the created listener.
      The returned registered listener may be unregistered when desired.

      The same EventConsumer may be used to create a registered listener via this method multiple times without issue. It may even be used with the same priority for the same event.

      The priority determines the order in which listeners are called. Lower priorities are called first. See the class javadoc for more information on priorities.

      The event class specifies all events the listener will listen to. See the class javadoc for more information.
      Type Parameters:
      E - the event type
      Parameters:
      eventClass - the event class. All instances of this class, including subclasses, will be listened to
      priority - the priority at which the listener is placed
      eventConsumer - the logic to run when the event fires
      Returns:
      a listener which may be unregistered when necessary
      Throws:
      IllegalArgumentException - if the event class is an array, a primitive, or Object

    • registerListener

      <E extends AsyncEvent> RegisteredListener registerListener(Class<E> eventClass, byte priority, AsynchronousEventConsumer<? super E> asyncEventConsumer)
      Creates and registers an asynchronous listener, returning the created listener.
      The returned registered listener may be unregistered when desired.

      The same AsynchronousEventConsumer may be used to create a registered listener via this method multiple times without issue. It may even be used with the same priority for the same event.

      The priority determines the order in which listeners are called. Lower priorities are called first. See the class javadoc for more information on priorities.

      The event class specifies all events the listener will listen to. See the class javadoc for more information.
      Type Parameters:
      E - the event type
      Parameters:
      eventClass - the event class. All instances of this class, including subclasses, will be listened to
      priority - the priority at which the listener is placed
      asyncEventConsumer - the logic to run when the event fires
      Returns:
      a listener which may be unregistered when necessary
      Throws:
      IllegalArgumentException - if the event class is an array, a primitive, or Object

    • registerListeningMethods

      void registerListeningMethods(Object annotatedListener)
      Registers all methods on the target listener object which are annotated with ListeningMethod. Inherited methods are included.

      The runtime type of the listener object must be public. Additionally, if it is in a named module, the module must be unconditionally exported.
      Parameters:
      annotatedListener - the listener whose annotated methods to register
      Throws:
      IllegalStateException - if the listener object is already registered
      IllegalArgumentException - if any method on the listener object annotated with ListeningMethod does not obey the requirements of it, or the listener object is in an unexported package

    • unregisterListener

      void unregisterListener(RegisteredListener listener)
      Unregister a registered listener.

      This is the opposite of #registerListener. Unregistering a listener which is not currently registered is a no-op.
      Parameters:
      listener - the registered listener to unregister

    • unregisterListeningMethods

      void unregisterListeningMethods(Object annotatedListener)
      Unregisters any methods on the target listener object which are annotated with ListeningMethod and were previously registered.

      If the listener object was never registered, this is a no-op.
      Parameters:
      annotatedListener - the listener whose annotated methods to unregister

    • getDriver

      EventBusDriver getDriver()
      Gets the lower level event bus driver. Should not be used by most API users
      Returns:
      the event bus driver