Package org.omegazero.common.eventbus

Class EventBus

java.lang.Object
org.omegazero.common.eventbus.EventBus
public class EventBus extends Object
An EventBus is used for dispatching Events to event bus subscribers which are listening for the specific event and registered in this EventBus.

An event bus subscriber is listening for an event if its class contains a method with the name given in the Event instance, matching parameters and the SubscribeEvent annotation. The SubscribeEvent annotation may contain the optional argument SubscribeEvent.priority(). The handlers with priority HIGHEST will be invoked first, the handlers with priority LOWEST will be executed last. The order of execution of multiple handlers with the same priority is undefined. An event bus subscriber can declare itself as listening for specific events. If an attempt is made to execute an event but no handler method is found in the subscriber class, event execution will fail.

During execution of this event, any handler may cancel the event using Event.cancel() if Event.isCancelable() is true, in which case the event will be stopped being delivered to subsequent event handlers. If Event.isIncludeAllReturns() is false, event delivery will be stopped as soon as the first listener returns a non-null value. If the event return type is void, all listeners will be attempted to be executed, because void methods always effectively return null.

Since:
2.1

  • Constructor Summary

    Constructors
    Constructor
    Description
    EventBus()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    dispatchEvent(Event event, Object... args)
    Dispatches the given event to all event bus subscribers listening for this event.
    EventResult
    dispatchEventRes(Event event, Object... args)
    The behavior of this method is equal to dispatchEvent(Event, Object...), except that this method also returns the return values of the listener methods, wrapped in an EventResult object.
    void
    flushEventCache()
    Flushes the event cache for all events.
    int
    getSubscriberCount()
    Returns the number of registered event bus subscribers.
    void
    register(Class<?> type, Object instance, String... forcedEvents)
    Adds the instance of type type to the list of listeners receiving events from the event bus.
    void
    register(Class<?> type, String... forcedEvents)
    Adds a listener for type type to the list of listeners receiving events from the event bus.
    void
    register(Object instance, String... forcedEvents)
    Adds the instance to the list of listeners receiving events from the event bus.
    void
    register(Subscriber subscriber, String... forcedEvents)
    Adds the event bus subscriber to the list of listeners receiving events from the event bus.
    void
    unregister(Class<?> type)
    Removes all event bus subscribers of the given type from the list of listeners receiving events from the event bus.
    void
    unregister(Object instance)
    Removes the event bus subscriber with instance from the list of listeners receiving events from the event bus.
    boolean
    unregister(Subscriber subscriber)
    Removes the given event bus subscriber from the list of listeners receiving events from the event bus.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • EventBus

      public EventBus()

  • Method Details

    • register

      public void register(Object instance, String... forcedEvents)
      Adds the instance to the list of listeners receiving events from the event bus.

      The class is derived from the given instance parameter.

      Parameters:
      instance - The instance of the event bus subscriber. The class of the instance must have the EventBusSubscriber annotation
      forcedEvents - The list of event names the caller asserts that the given event bus subscriber is listening to

    • register

      public void register(Class<?> type, String... forcedEvents)
      Adds a listener for type type to the list of listeners receiving events from the event bus.

      Note that non-static methods cannot be used as listeners using this method. To use non-static methods, pass an instance with register(Class, Object, String[]) or register(Object, String[]).

      Parameters:
      type - The type of the event bus subscriber. This class must have the EventBusSubscriber annotation
      forcedEvents - The list of event names the caller asserts that the given event bus subscriber is listening to

    • register

      public void register(Class<?> type, Object instance, String... forcedEvents)
      Adds the instance of type type to the list of listeners receiving events from the event bus.
      Parameters:
      type - The type of the event bus subscriber. This class must have the EventBusSubscriber annotation
      instance - The instance of the event bus subscriber
      forcedEvents - The list of event names the caller asserts that the given event bus subscriber is listening to

    • register

      public void register(Subscriber subscriber, String... forcedEvents)
      Adds the event bus subscriber to the list of listeners receiving events from the event bus.
      Parameters:
      subscriber - The event bus subscriber
      forcedEvents - The list of event names the caller asserts that the given event bus subscriber is listening to

    • unregister

      public boolean unregister(Subscriber subscriber)
      Removes the given event bus subscriber from the list of listeners receiving events from the event bus.
      Parameters:
      subscriber - The event bus subscriber instance
      Returns:
      true if the given subscriber was registered
      Since:
      2.7

    • unregister

      public void unregister(Object instance)
      Removes the event bus subscriber with instance from the list of listeners receiving events from the event bus. This method effectively does nothing if the given instance is not the instance of a registered event bus subscriber.
      Parameters:
      instance - The event bus subscriber instance

    • unregister

      public void unregister(Class<?> type)
      Removes all event bus subscribers of the given type from the list of listeners receiving events from the event bus. This method effectively does nothing if the given instance is not a registered event bus subscriber.
      Parameters:
      type - The type

    • flushEventCache

      public void flushEventCache()
      Flushes the event cache for all events.

      The next time an event is dispatched, the list of listeners must be rebuilt from the list of subscribers.

    • getSubscriberCount

      public int getSubscriberCount()
      Returns the number of registered event bus subscribers.
      Returns:
      The number of registered event bus subscribers

    • dispatchEvent

      public int dispatchEvent(Event event, Object... args)
      Dispatches the given event to all event bus subscribers listening for this event.

      This method may be used instead of dispatchEventRes(Event, Object...) if return types are not needed to save resources, because no EventResult object is being created.

      Parameters:
      event - The event to be executed among all subscribers listening to this event
      args - Arguments to be passed to event listeners
      Returns:
      The number of executed event handlers
      Throws:
      EventBusException - If an error occurs during execution of an event handler
      See Also:

    • dispatchEventRes

      public EventResult dispatchEventRes(Event event, Object... args)
      The behavior of this method is equal to dispatchEvent(Event, Object...), except that this method also returns the return values of the listener methods, wrapped in an EventResult object.
      Parameters:
      event - The event to be executed among all subscribers listening to this event
      args - Arguments to be passed to event listeners
      Returns:
      An EventResult object containing data about this event dispatch
      Throws:
      EventBusException - If an error occurs during execution of an event handler
      See Also: