Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
   * Copyright (C) 2007 The Guava Authors
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
 import java.util.Set;
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 handler, 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(java.lang.Object) method.

Posting Events

To post an event, simply provide the event object to the post(java.lang.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 an AsyncEventBus.)

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 java.lang.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.

Cliff Biffle
public class EventBus {

All registered event handlers, indexed by event type.
  private final SetMultimap<Class<?>, EventHandlerhandlersByType =
      Multimaps.newSetMultimap(new ConcurrentHashMap<Class<?>, Collection<EventHandler>>(),
          new Supplier<Set<EventHandler>>() {
            public Set<EventHandlerget() {
              return newHandlerSet();

Logger for event dispatch failures. Named by the fully-qualified name of this class, followed by the identifier provided at construction.
  private final Logger logger;

Strategy for finding handler methods in registered objects. Currently, only the AnnotatedHandlerFinder is supported, but this is encapsulated for future expansion.
  private final HandlerFindingStrategy finder = new AnnotatedHandlerFinder();

queues of events for the current thread to dispatch
      eventsToDispatch =
      return new ConcurrentLinkedQueue<EventWithHandler>();

true if the current thread is currently dispatching an event
  private final ThreadLocal<BooleanisDispatching =
      new ThreadLocal<Boolean>() {
    @Override protected Boolean initialValue() {
      return false;

A thread-safe cache for flattenHierarchy(). The Class class is immutable.
  private final LoadingCache<Class<?>, Set<Class<?>>> flattenHierarchyCache =
          .build(new CacheLoader<Class<?>, Set<Class<?>>>() {
            @SuppressWarnings({"unchecked""rawtypes"}) // safe cast
            public Set<Class<?>> load(Class<?> concreteClassthrows Exception {
              return (Set) TypeToken.of(concreteClass).getTypes().rawTypes();

Creates a new EventBus named "default".
  public EventBus() {

Creates a new EventBus with the given identifier.

identifier a brief name for this bus, for logging purposes. Should be a valid Java identifier.
  public EventBus(String identifier) {
     = Logger.getLogger(EventBus.class.getName() + "." + identifier);

Registers all handler methods on object to receive events. Handler methods are selected and classified using this EventBus's HandlerFindingStrategy; the default strategy is the AnnotatedHandlerFinder.

object object whose handler methods should be registered.
  public void register(Object object) {

Unregisters all handler methods on a registered object.

object object whose handler methods should be unregistered.
java.lang.IllegalArgumentException if the object was not previously registered.
  public void unregister(Object object) {
    Multimap<Class<?>, EventHandlermethodsInListener = .findAllHandlers(object);
    for (Entry<Class<?>, Collection<EventHandler>> entry : methodsInListener.asMap().entrySet()) {
      Set<EventHandlercurrentHandlers = getHandlersForEventType(entry.getKey());
      Collection<EventHandlereventMethodsInListener = entry.getValue();
      if (currentHandlers == null || !currentHandlers.containsAll(entry.getValue())) {
        throw new IllegalArgumentException(
            "missing event handler for an annotated method. Is " + object + " registered?");

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, and event is not already a DeadEvent, it will be wrapped in a DeadEvent and reposted.

event event to post.
  @SuppressWarnings("deprecation"// only deprecated for external subclasses
  public void post(Object event) {
    Set<Class<?>> dispatchTypes = flattenHierarchy(event.getClass());
    boolean dispatched = false;
    for (Class<?> eventType : dispatchTypes) {
      Set<EventHandlerwrappers = getHandlersForEventType(eventType);
      if (wrappers != null && !wrappers.isEmpty()) {
        dispatched = true;
        for (EventHandler wrapper : wrappers) {
    if (!dispatched && !(event instanceof DeadEvent)) {
      post(new DeadEvent(thisevent));

Queue the event for dispatch during dispatchQueuedEvents(). Events are queued in-order of occurrence so they can be dispatched in the same order.
  void enqueueEvent(Object eventEventHandler handler) {
    .get().offer(new EventWithHandler(eventhandler));

Drain the queue of events to be dispatched. As the queue is being drained, new events may be posted to the end of the queue.

This method should not be overridden outside of the eventbus package. It is scheduled for removal in Guava 14.0.
  protected void dispatchQueuedEvents() {
    // don't dispatch if we're already dispatching, that would allow reentrancy
    // and out-of-order events. Instead, leave the events to be dispatched
    // after the in-progress dispatch is complete.
    if (.get()) {
    try {
      while (true) {
        EventWithHandler eventWithHandler = .get().poll();
        if (eventWithHandler == null) {
    } finally {

Dispatches event to the handler in wrapper. This method is an appropriate override point for subclasses that wish to make event delivery asynchronous.

event event to dispatch.
wrapper wrapper that will call the handler.
  void dispatch(Object eventEventHandler wrapper) {
    try {
    } catch (InvocationTargetException e) {
          "Could not dispatch event: " + event + " to handler " + wrappere);

Retrieves a mutable set of the currently registered handlers for type. If no handlers are currently registered for type, this method may either return null or an empty set.

type type of handlers to retrieve.
currently registered handlers, or null.
    return .get(type);

Creates a new Set for insertion into the handler map. This is provided as an override point for subclasses. The returned set should support concurrent access.

a new, mutable set for handlers.
    return new CopyOnWriteArraySet<EventHandler>();

Flattens a class's type hierarchy into a set of Class objects. The set will include all superclasses (transitively), and all interfaces implemented by these superclasses.

concreteClass class whose type hierarchy will be retrieved.
clazz's complete type hierarchy, flattened and uniqued.
  Set<Class<?>> flattenHierarchy(Class<?> concreteClass) {
    try {
      return .get(concreteClass);
    } catch (ExecutionException e) {
      throw Throwables.propagate(e.getCause());

simple struct representing an event and it's handler
  static class EventWithHandler {
    final Object event;
    final EventHandler handler;
    public EventWithHandler(Object eventEventHandler handler) {
      this. = event;
      this. = handler;
New to GrepCode? Check out our FAQ X