public class EventBus extends Object
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.
To receive events, an object should:
Subscribe annotation;
register(Object) method.
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.)
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.
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.
| Modifier and Type | Class and Description |
|---|---|
(package private) static class |
EventBus.DirectExecutor
Simple executor singleton that runs commands in the same thread.
|
(package private) static class |
EventBus.LoggingHandler
Simple logging handler for subscriber exceptions.
|
| Modifier and Type | Field and Description |
|---|---|
private Dispatcher |
dispatcher |
private SubscriberExceptionHandler |
exceptionHandler |
private Executor |
executor |
private String |
identifier |
private static Logger |
logger |
private SubscriberRegistry |
subscribers |
| Constructor and Description |
|---|
EventBus()
Creates a new EventBus named "default".
|
EventBus(String identifier)
Creates a new EventBus with the given
identifier. |
EventBus(String identifier,
Executor executor,
Dispatcher dispatcher,
SubscriberExceptionHandler exceptionHandler)
Constructs a new
EventBus. |
EventBus(SubscriberExceptionHandler exceptionHandler)
Creates a new EventBus with the given
SubscriberExceptionHandler. |
| Modifier and Type | Method and Description |
|---|---|
(package private) Executor |
executor()
Returns the default executor this event bus uses for dispatching events to subscribers.
|
(package private) void |
handleSubscriberException(Throwable e,
SubscriberExceptionContext context)
Handles the given exception thrown by a subscriber with the given context.
|
String |
identifier()
Returns the identifier for this event bus.
|
void |
post(Object event)
Posts an event to all registered subscribers.
|
void |
register(Object object)
Registers all subscriber methods on
object to receive events. |
String |
toString() |
void |
unregister(Object object)
Unregisters all subscriber methods on a registered
object. |
private final String identifier
private final SubscriberExceptionHandler exceptionHandler
private final SubscriberRegistry subscribers
private final Dispatcher dispatcher
public EventBus()
public EventBus(String identifier)
identifier.identifier - a brief name for this bus, for logging purposes. Should be a valid Java
identifier.public EventBus(SubscriberExceptionHandler exceptionHandler)
SubscriberExceptionHandler.exceptionHandler - Handler for subscriber exceptions.EventBus(String identifier, Executor executor, Dispatcher dispatcher, SubscriberExceptionHandler exceptionHandler)
EventBus.identifier - the identifier for this event bus. Must not be nullexecutor - the default executor to use for dispatching events to subscribers. Must not be nulldispatcher - the event dispatcher. Must not be nullexceptionHandler - handles the exceptions thrown by a subscriber. Must not be nullpublic final String identifier()
final Executor executor()
void handleSubscriberException(Throwable e, SubscriberExceptionContext context)
e - exception thrown by a subscribercontext - subscriber contextpublic void register(Object object)
object to receive events.object - object whose subscriber methods should be registered.public void unregister(Object object)
object.object - object whose subscriber methods should be unregistered.IllegalArgumentException - if the object was not previously registered.public void post(Object event)
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.
event - event to post.