@Beta 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
.
Constructor and Description |
---|
EventBus()
Creates a new EventBus named "default".
|
EventBus(String identifier)
Creates a new EventBus with the given
identifier . |
EventBus(SubscriberExceptionHandler exceptionHandler)
Creates a new EventBus with the given
SubscriberExceptionHandler . |
Modifier and Type | Method and Description |
---|---|
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()
Returns a string representation of the object.
|
void |
unregister(Object object)
Unregisters all subscriber methods on a registered
object . |
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.public final String identifier()
public 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.public String toString()
java.lang.Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
Copyright © 2010–2019. All rights reserved.