View Javadoc
1   /*
2    * Copyright (C) 2007 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. You may obtain a copy of the License at
6    *
7    * http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  
15  package com.google.common.eventbus;
16  
17  import static com.google.common.base.Preconditions.checkNotNull;
18  
19  import com.google.common.annotations.Beta;
20  import com.google.common.base.MoreObjects;
21  import com.google.common.util.concurrent.MoreExecutors;
22  import java.lang.reflect.Method;
23  import java.util.Iterator;
24  import java.util.Locale;
25  import java.util.concurrent.Executor;
26  import java.util.logging.Level;
27  import java.util.logging.Logger;
28  
29  /**
30   * Dispatches events to listeners, and provides ways for listeners to register themselves.
31   *
32   * <p>The EventBus allows publish-subscribe-style communication between components without requiring
33   * the components to explicitly register with one another (and thus be aware of each other). It is
34   * designed exclusively to replace traditional Java in-process event distribution using explicit
35   * registration. It is <em>not</em> a general-purpose publish-subscribe system, nor is it intended
36   * for interprocess communication.
37   *
38   * <h2>Receiving Events</h2>
39   *
40   * <p>To receive events, an object should:
41   * <ol>
42   * <li>Expose a public method, known as the <i>event subscriber</i>, which accepts a single argument
43   *     of the type of event desired;
44   * <li>Mark it with a {@link Subscribe} annotation;
45   * <li>Pass itself to an EventBus instance's {@link #register(Object)} method.
46   * </ol>
47   *
48   * <h2>Posting Events</h2>
49   *
50   * <p>To post an event, simply provide the event object to the {@link #post(Object)} method. The
51   * EventBus instance will determine the type of event and route it to all registered listeners.
52   *
53   * <p>Events are routed based on their type &mdash; an event will be delivered to any subscriber for
54   * any type to which the event is <em>assignable.</em> This includes implemented interfaces, all
55   * superclasses, and all interfaces implemented by superclasses.
56   *
57   * <p>When {@code post} is called, all registered subscribers for an event are run in sequence, so
58   * subscribers should be reasonably quick. If an event may trigger an extended process (such as a
59   * database load), spawn a thread or queue it for later. (For a convenient way to do this, use an
60   * {@link AsyncEventBus}.)
61   *
62   * <h2>Subscriber Methods</h2>
63   *
64   * <p>Event subscriber methods must accept only one argument: the event.
65   *
66   * <p>Subscribers should not, in general, throw. If they do, the EventBus will catch and log the
67   * exception. This is rarely the right solution for error handling and should not be relied upon; it
68   * is intended solely to help find problems during development.
69   *
70   * <p>The EventBus guarantees that it will not call a subscriber method from multiple threads
71   * simultaneously, unless the method explicitly allows it by bearing the
72   * {@link AllowConcurrentEvents} annotation. If this annotation is not present, subscriber methods
73   * need not worry about being reentrant, unless also called from outside the EventBus.
74   *
75   * <h2>Dead Events</h2>
76   *
77   * <p>If an event is posted, but no registered subscribers can accept it, it is considered "dead."
78   * To give the system a second chance to handle dead events, they are wrapped in an instance of
79   * {@link DeadEvent} and reposted.
80   *
81   * <p>If a subscriber for a supertype of all events (such as Object) is registered, no event will
82   * ever be considered dead, and no DeadEvents will be generated. Accordingly, while DeadEvent
83   * extends {@link Object}, a subscriber registered to receive any Object will never receive a
84   * DeadEvent.
85   *
86   * <p>This class is safe for concurrent use.
87   *
88   * <p>See the Guava User Guide article on
89   * <a href="https://github.com/google/guava/wiki/EventBusExplained">{@code EventBus}</a>.
90   *
91   * @author Cliff Biffle
92   * @since 10.0
93   */
94  @Beta
95  public class EventBus {
96  
97    private static final Logger logger = Logger.getLogger(EventBus.class.getName());
98  
99    private final String identifier;
100   private final Executor executor;
101   private final SubscriberExceptionHandler exceptionHandler;
102 
103   private final SubscriberRegistry subscribers = new SubscriberRegistry(this);
104   private final Dispatcher dispatcher;
105 
106   /**
107    * Creates a new EventBus named "default".
108    */
109   public EventBus() {
110     this("default");
111   }
112 
113   /**
114    * Creates a new EventBus with the given {@code identifier}.
115    *
116    * @param identifier a brief name for this bus, for logging purposes. Should be a valid Java
117    *     identifier.
118    */
119   public EventBus(String identifier) {
120     this(
121         identifier,
122         MoreExecutors.directExecutor(),
123         Dispatcher.perThreadDispatchQueue(),
124         LoggingHandler.INSTANCE);
125   }
126 
127   /**
128    * Creates a new EventBus with the given {@link SubscriberExceptionHandler}.
129    *
130    * @param exceptionHandler Handler for subscriber exceptions.
131    * @since 16.0
132    */
133   public EventBus(SubscriberExceptionHandler exceptionHandler) {
134     this(
135         "default",
136         MoreExecutors.directExecutor(),
137         Dispatcher.perThreadDispatchQueue(),
138         exceptionHandler);
139   }
140 
141   EventBus(
142       String identifier,
143       Executor executor,
144       Dispatcher dispatcher,
145       SubscriberExceptionHandler exceptionHandler) {
146     this.identifier = checkNotNull(identifier);
147     this.executor = checkNotNull(executor);
148     this.dispatcher = checkNotNull(dispatcher);
149     this.exceptionHandler = checkNotNull(exceptionHandler);
150   }
151 
152   /**
153    * Returns the identifier for this event bus.
154    *
155    * @since 19.0
156    */
157   public final String identifier() {
158     return identifier;
159   }
160 
161   /**
162    * Returns the default executor this event bus uses for dispatching events to subscribers.
163    */
164   final Executor executor() {
165     return executor;
166   }
167 
168   /**
169    * Handles the given exception thrown by a subscriber with the given context.
170    */
171   void handleSubscriberException(Throwable e, SubscriberExceptionContext context) {
172     checkNotNull(e);
173     checkNotNull(context);
174     try {
175       exceptionHandler.handleException(e, context);
176     } catch (Throwable e2) {
177       // if the handler threw an exception... well, just log it
178       logger.log(
179           Level.SEVERE,
180           String.format(Locale.ROOT, "Exception %s thrown while handling exception: %s", e2, e),
181           e2);
182     }
183   }
184 
185   /**
186    * Registers all subscriber methods on {@code object} to receive events.
187    *
188    * @param object object whose subscriber methods should be registered.
189    */
190   public void register(Object object) {
191     subscribers.register(object);
192   }
193 
194   /**
195    * Unregisters all subscriber methods on a registered {@code object}.
196    *
197    * @param object object whose subscriber methods should be unregistered.
198    * @throws IllegalArgumentException if the object was not previously registered.
199    */
200   public void unregister(Object object) {
201     subscribers.unregister(object);
202   }
203 
204   /**
205    * Posts an event to all registered subscribers. This method will return successfully after the
206    * event has been posted to all subscribers, and regardless of any exceptions thrown by
207    * subscribers.
208    *
209    * <p>If no subscribers have been subscribed for {@code event}'s class, and {@code event} is not
210    * already a {@link DeadEvent}, it will be wrapped in a DeadEvent and reposted.
211    *
212    * @param event event to post.
213    */
214   public void post(Object event) {
215     Iterator<Subscriber> eventSubscribers = subscribers.getSubscribers(event);
216     if (eventSubscribers.hasNext()) {
217       dispatcher.dispatch(event, eventSubscribers);
218     } else if (!(event instanceof DeadEvent)) {
219       // the event had no subscribers and was not itself a DeadEvent
220       post(new DeadEvent(this, event));
221     }
222   }
223 
224   @Override
225   public String toString() {
226     return MoreObjects.toStringHelper(this).addValue(identifier).toString();
227   }
228 
229   /**
230    * Simple logging handler for subscriber exceptions.
231    */
232   static final class LoggingHandler implements SubscriberExceptionHandler {
233     static final LoggingHandler INSTANCE = new LoggingHandler();
234 
235     @Override
236     public void handleException(Throwable exception, SubscriberExceptionContext context) {
237       Logger logger = logger(context);
238       if (logger.isLoggable(Level.SEVERE)) {
239         logger.log(Level.SEVERE, message(context), exception);
240       }
241     }
242 
243     private static Logger logger(SubscriberExceptionContext context) {
244       return Logger.getLogger(EventBus.class.getName() + "." + context.getEventBus().identifier());
245     }
246 
247     private static String message(SubscriberExceptionContext context) {
248       Method method = context.getSubscriberMethod();
249       return "Exception thrown by subscriber method "
250           + method.getName()
251           + '('
252           + method.getParameterTypes()[0].getName()
253           + ')'
254           + " on subscriber "
255           + context.getSubscriber()
256           + " when dispatching event: "
257           + context.getEvent();
258     }
259   }
260 }