EventBus
Date: 2016-05-24

com.google.common.eventbus

## Class EventBus

- java.lang.Object
- - com.google.common.eventbus.EventBus

- Direct Known Subclasses:
    AsyncEventBus

      @Beta
      public class EventBus
      extends java.lang.Object

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

  The EventBus allows publish-subscribe-style communication between components without requiring the components to explicitly register with one another (and thus be aware of each other). It is designed exclusively to replace traditional Java in-process event distribution using explicit registration. It is not a general-purpose publish-subscribe system, nor is it intended for interprocess communication.

  ## Receiving Events

  To receive events, an object should:

  1. Expose a public method, known as the event subscriber, which accepts a single argument of the type of event desired;
  2. Mark it with a `Subscribe` annotation;
  3. Pass itself to an EventBus instance's `register(Object)` method.

  ## Posting Events

  To post an event, simply provide the event object to the `post(Object)` method. The EventBus instance will determine the type of event and route it to all registered listeners.

  Events are routed based on their type — an event will be delivered to any subscriber for any type to which the event is assignable. This includes implemented interfaces, all superclasses, and all interfaces implemented by superclasses.

  When `post` is called, all registered subscribers for an event are run in sequence, so subscribers should be reasonably quick. If an event may trigger an extended process (such as a database load), spawn a thread or queue it for later. (For a convenient way to do this, use an `AsyncEventBus`.)

  ## Subscriber Methods

  Event subscriber methods must accept only one argument: the event.

  Subscribers should not, in general, throw. If they do, the EventBus will catch and log the exception. This is rarely the right solution for error handling and should not be relied upon; it is intended solely to help find problems during development.

  The EventBus guarantees that it will not call a subscriber method from multiple threads simultaneously, unless the method explicitly allows it by bearing the `AllowConcurrentEvents` annotation. If this annotation is not present, subscriber methods need not worry about being reentrant, unless also called from outside the EventBus.

  ## Dead Events

  If an event is posted, but no registered subscribers can accept it, it is considered "dead." To give the system a second chance to handle dead events, they are wrapped in an instance of `DeadEvent` and reposted.

  If a subscriber for a supertype of all events (such as Object) is registered, no event will ever be considered dead, and no DeadEvents will be generated. Accordingly, while DeadEvent extends `Object`, a subscriber registered to receive any Object will never receive a DeadEvent.

  This class is safe for concurrent use.

  See the Guava User Guide article on `EventBus`.

  Since:
    10.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `EventBus()` Creates a new EventBus named "default".
    `EventBus(java.lang.String identifier)` Creates a new EventBus with the given `identifier`.
    `EventBus(SubscriberExceptionHandler exceptionHandler)` Creates a new EventBus with the given `SubscriberExceptionHandler`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `identifier()` Returns the identifier for this event bus.
    `void` | `post(java.lang.Object event)` Posts an event to all registered subscribers.
    `void` | `register(java.lang.Object object)` Registers all subscriber methods on `object` to receive events.
    `java.lang.String` | `toString()`
    `void` | `unregister(java.lang.Object object)` Unregisters all subscriber methods on a registered `object`.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### EventBus

          public EventBus()

      Creates a new EventBus named "default".

    - #### EventBus

          public EventBus(java.lang.String identifier)

      Creates a new EventBus with the given `identifier`.
      Parameters:
        `identifier` - a brief name for this bus, for logging purposes. Should be a valid Java identifier.

    - #### EventBus

          public EventBus(SubscriberExceptionHandler exceptionHandler)

      Creates a new EventBus with the given `SubscriberExceptionHandler`.
      Parameters:
        `exceptionHandler` - Handler for subscriber exceptions.
      Since:
        16.0

  - ### Method Detail

    - #### identifier

          public final java.lang.String identifier()

      Returns the identifier for this event bus.
      Since:
        19.0

    - #### register

          public void register(java.lang.Object object)

      Registers all subscriber methods on `object` to receive events.
      Parameters:
        `object` - object whose subscriber methods should be registered.

    - #### unregister

          public void unregister(java.lang.Object object)

      Unregisters all subscriber methods on a registered `object`.
      Parameters:
        `object` - object whose subscriber methods should be unregistered.
      Throws:
        `java.lang.IllegalArgumentException` - if the object was not previously registered.

    - #### post

          public void post(java.lang.Object event)

      Posts an event to all registered subscribers. This method will return successfully after the event has been posted to all subscribers, and regardless of any exceptions thrown by subscribers.

      If no subscribers have been subscribed for `event`'s class, and `event` is not already a `DeadEvent`, it will be wrapped in a DeadEvent and reposted.

      Parameters:
        `event` - event to post.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`