Package com.blamejared.crafttweaker.api.event.bus

Interface IEventBus<T>

Type Parameters:
T - The type of event to be posted on the event bus.
public interface IEventBus<T>
Represents a bus on which events of a specific type can be posted.

An event bus provides an easy way for a series of Consumers, usually called listeners or handlers to subscribe to certain events occurring within the program and be notified of their occurrence.

There are no restriction on the type of the event object, nor on the amount of buses that might exist for a single class. It is in fact possible, although discouraged, for a single event class to be mapped to more than one bus. Particular users of this class, such as the ZenCode scripting integration, might assume that every event class has a single bus associated to it.

An event bus might be of two types: either a direct or a cancelable event bus. A direct event bus acts as a simple notifier, invoking the various handlers. A cancelable event bus allows the consumer to also cancel a specific event, blocking processing of the event and letting the dispatcher, i.e. the user that posted the event, know that one handler wants to prevent the action from happening, if possible. Some handlers might still want to listen to canceled events, though, so such an option is also provided.

Every event bus has a wire associated to it, that allows for the wiring of this event bus to another event bus that might be present, such as platform-specific buses. It is also possible to create wireless event buses, meaning buses that are standalone, by using the CommonWirelessEventBusWire class as the wire.

Every handler on an event bus might also be associated to a Phase. Refer to the class documentation for additional specifications.

While possible, it is discouraged to create custom sub-classes of this interface. Rather, clients of this API should prefer using one of the factory methods provided in this class to construct the desired event bus.

It is customary, although not required, for an event bus to be located within the event class itself, in a public static final field:

     
     class MyEvent {
         public static final IEventBus<MyEvent> BUS = IEventBus.direct(MyEvent.class, CommonWirelessEventBusWire.of());
     }
Since:
11.0.0

  • Method Details

    • direct

      static <T> IEventBus<T> direct(Class<T> clazz, IEventBusWire wire)
      Constructs a new direct IEventBus for the given event type.

      A direct event bus does not support cancellation.

      Type Parameters:
      T - The type of the event to post in the bus.
      Parameters:
      clazz - The type of the event.
      wire - The IEventBusWire to use to wire this event bus.
      Returns:
      A newly created IEventBus.
      Since:
      11.0.0

    • direct

      static <T> IEventBus<T> direct(com.google.common.reflect.TypeToken<T> token, IEventBusWire wire)
      Constructs a new direct IEventBus for the given event type.

      A direct event bus does not support cancellation.

      Type Parameters:
      T - The type of the event to post in the bus.
      Parameters:
      token - The type of the event.
      wire - The IEventBusWire to use to wire this event bus.
      Returns:
      A newly created IEventBus.
      Since:
      11.0.0

    • cancelable

      static <T> IEventBus<T> cancelable(Class<T> clazz, IEventBusWire wire, IEventCancellationCarrier<T> carrier)
      Constructs a new cancelable IEventBus for the given event type.

      A cancelable event bus supports cancellation of events, the state of which is tracked through the given IEventCancellationCarrier.

      Type Parameters:
      T - The type of the event to post in the bus.
      Parameters:
      clazz - The type of the event.
      wire - The IEventBusWire to use to wire this event bus.
      carrier - The IEventCancellationCarrier responsible to track the cancellation status of a particular event.
      Returns:
      A newly created IEventBus
      Since:
      11.0.0

    • cancelable

      static <T> IEventBus<T> cancelable(com.google.common.reflect.TypeToken<T> token, IEventBusWire wire, IEventCancellationCarrier<T> carrier)
      Constructs a new cancelable IEventBus for the given event type.

      A cancelable event bus supports cancellation of events, the state of which is tracked through the given IEventCancellationCarrier.

      Type Parameters:
      T - The type of the event to post in the bus.
      Parameters:
      token - The type of the event.
      wire - The IEventBusWire to use to wire this event bus.
      carrier - The IEventCancellationCarrier responsible to track the cancellation status of a particular event.
      Returns:
      A newly created IEventBus
      Since:
      11.0.0

    • registerHandler

      IHandlerToken<T> registerHandler(Consumer<T> handler)
      Registers the given Consumer as a handler for the event this bus is for.

      The consumer will be invoked in the event's default phase and, if this event bus is cancelable, solely if the event is not canceled.

      Parameters:
      handler - The handler to be invoked.
      Returns:
      A IHandlerToken that allows for the removal of the given handler.
      Since:
      11.0.0

    • registerHandler

      IHandlerToken<T> registerHandler(Phase phase, Consumer<T> handler)
      Registers the given Consumer as a handler for the event this bus is for on the given Phase.

      If the event bus is cancelable, then the handler will be invoked solely if the event is not canceled.

      Parameters:
      phase - The Phase on which the handler should be invoked on.
      handler - The handler to be invoked.
      Returns:
      A IHandlerToken that allows for the removal of the given handler.
      Since:
      11.0.0

    • registerHandler

      IHandlerToken<T> registerHandler(boolean listenToCanceled, Consumer<T> handler)
      Registers the given Consumer as a handler for the event this bus is for.

      If this event bus is cancelable, then the listenToCanceled boolean will determine whether the handler will be invoked solely when the event is not canceled (listenToCanceled = false) or in all cases, effectively ignoring cancellation status (listenToCanceled = true). If the event bus is direct, on the other hand, the value of listenToCanceled is ignored.

      Parameters:
      listenToCanceled - Whether the handler should be invoked for all events or only non-canceled ones.
      handler - The handler to be invoked.
      Returns:
      A IHandlerToken that allows for the removal of the given handler.
      Since:
      11.0.0

    • registerHandler

      IHandlerToken<T> registerHandler(Phase phase, boolean listenToCanceled, Consumer<T> handler)
      Registers the given Consumer as a handler for the event this bus is for on the given Phase.

      If this event bus is cancelable, then the listenToCanceled boolean will determine whether the handler will be invoked solely when the event is not canceled (listenToCanceled = false) or in all cases, effectively ignoring cancellation status (listenToCanceled = true). If the event bus is direct, on the other hand, the value of listenToCanceled is ignored.

      Parameters:
      phase - The Phase on which the handler should be invoked on.
      listenToCanceled - Whether the handler should be invoked for all events or only non-canceled ones.
      handler - The handler to be invoked.
      Returns:
      A IHandlerToken that allows for removal of the given handler.
      Since:
      11.0.0

    • unregisterHandler

      void unregisterHandler(IHandlerToken<T> token)
      Removes the handler associated to the given IHandlerToken from the ones associated to this bus.

      Removing a handler means that the event bus will no longer invoke it when an event is posted.

      It is not allowed to attempt removal of a given handler more than once.

      Parameters:
      token - The token associated to the handler that should be removed.
      Throws:
      IllegalArgumentException - If the token is not recognized by the event bus, possibly because it is of the wrong class or because it has been created by a different event bus.
      IllegalStateException - If an attempt to reuse the token after it has already been used once is detected.
      Since:
      11.0.0

    • post

      T post(T event)
      Posts the given event to all handlers on all Phases.

      The event will be dispatched on the various phases according to their natural ordering. Moreover, any BusHandlingException that might be raised during the posting of the event will be automatically handled according to an internal policy specified by the event bus itself. An event bus implementation need not raise the exception. If a custom policy is desired, then refer to postCatching(Object, Consumer) instead.

      Parameters:
      event - The event object that should be posted to the various listeners.
      Returns:
      event, for easier chaining.
      Since:
      11.0.0

    • post

      T post(Phase phase, T event)
      Posts the given event to all handlers listening on the specified Phase.

      Only the handlers listening to the given phase will be notified, no other handlers will. Moreover, any dispatching exceptions that might occur during the posting of the event will be automatically handled according to an internal policy specified by the event bus itself. An event bus implementation need not raise the exception. If a custom policy is desired, then use postCatching(Phase, Object, Consumer) instead.

      Parameters:
      phase - The Phase on which the event should be posted.
      event - The event object that should be posted to the various listeners.
      Returns:
      event, for easier chaining.
      Since:
      11.0.0

    • postCatching

      T postCatching(T event, Consumer<BusHandlingException> exceptionHandler)
      Posts the given event to all handlers on all Phases.

      The event will be dispatched on the various phases according to their natural ordering.

      Any BusHandlingException that might be raised during dispatching will be caught and provided to the specified exceptionHandler Consumer for additional processing.

      Parameters:
      event - The event object that should be posted to the various listeners.
      exceptionHandler - The Consumer responsible for the handling of dispatch errors, if any.
      Returns:
      event, for easier chaining.
      Since:
      11.0.0

    • postCatching

      T postCatching(Phase phase, T event, Consumer<BusHandlingException> exceptionHandler)
      Posts the given event to all handlers listening on the specified Phase.

      Only the handlers listening to the given phase will be notified, no other handlers will.

      Any BusHandlingException that might be raised during dispatching will be caught and provided to the specified exceptionHandler Consumer for additional processing.

      Parameters:
      phase - The Phase on which the event should be posted.
      event - The event object that should be posted to the various listeners.
      exceptionHandler - The Consumer responsible for the handling of dispatch errors, if any.
      Returns:
      event, for easier chaining.
      Since:
      11.0.0

    • eventType

      com.google.common.reflect.TypeToken<T> eventType()
      Gets the TypeToken representing the type of events that this bus dispatches.
      Returns:
      The type of events dispatched by this bus.
      Since:
      11.0.0