Class EventBus
- java.lang.Object
-
- com.google.common.eventbus.EventBus
-
- Direct Known Subclasses:
AsyncEventBus
@Beta @Deprecated(since="2022-12-01") public class EventBus extends java.lang.Object
Deprecated.The Google Guava Core Libraries are deprecated and will not be part of the AEM SDK after April 2023Dispatches 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:
- Expose a public method, known as the event handler, which accepts a single argument of the type of event desired;
- Mark it with a
Subscribe
annotation; - 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 handler 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 handlers for an event are run in sequence, so handlers 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 anAsyncEventBus
.)Handler Methods
Event handler methods must accept only one argument: the event.
Handlers 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 handler method from multiple threads simultaneously, unless the method explicitly allows it by bearing the
AllowConcurrentEvents
annotation. If this annotation is not present, handler methods need not worry about being reentrant, unless also called from outside the EventBus.Dead Events
If an event is posted, but no registered handlers 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 handler 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 handler 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
-
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
post(java.lang.Object event)
Deprecated.Posts an event to all registered handlers.void
register(java.lang.Object object)
Deprecated.Registers all handler methods onobject
to receive events.void
unregister(java.lang.Object object)
Deprecated.Unregisters all handler methods on a registeredobject
.
-
-
-
Constructor Detail
-
EventBus
public EventBus()
Deprecated.Creates a new EventBus named "default".
-
EventBus
public EventBus(java.lang.String identifier)
Deprecated.Creates a new EventBus with the givenidentifier
.- Parameters:
identifier
- a brief name for this bus, for logging purposes. Should be a valid Java identifier.
-
-
Method Detail
-
register
public void register(java.lang.Object object)
Deprecated.Registers all handler methods onobject
to receive events. Handler methods are selected and classified using this EventBus'sHandlerFindingStrategy
; the default strategy is theAnnotatedHandlerFinder
.- Parameters:
object
- object whose handler methods should be registered.
-
unregister
public void unregister(java.lang.Object object)
Deprecated.Unregisters all handler methods on a registeredobject
.- Parameters:
object
- object whose handler methods should be unregistered.- Throws:
java.lang.IllegalArgumentException
- if the object was not previously registered.
-
post
public void post(java.lang.Object event)
Deprecated.Posts an event to all registered handlers. This method will return successfully after the event has been posted to all handlers, and regardless of any exceptions thrown by handlers.If no handlers have been subscribed for
event
's class, andevent
is not already aDeadEvent
, it will be wrapped in a DeadEvent and reposted.- Parameters:
event
- event to post.
-
-