/*
* 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
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* 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.
*/
package com.google.common.eventbus;
import static com.google.common.base.Preconditions.checkNotNull;
import com.google.common.annotations.Beta;
import com.google.common.base.MoreObjects;
import com.google.common.util.concurrent.MoreExecutors;
import java.lang.reflect.Method;
import java.util.Iterator;
import java.util.concurrent.Executor;
import java.util.logging.Level;
import java.util.logging.Logger;
/**
* Dispatches events to listeners, and provides ways for listeners to register
* themselves.
*
* <p>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 <em>not</em> a general-purpose publish-subscribe system,
* nor is it intended for interprocess communication.
*
* <h2>Receiving Events</h2>
* <p>To receive events, an object should:
* <ol>
* <li>Expose a public method, known as the <i>event subscriber</i>, which accepts
* a single argument of the type of event desired;</li>
* <li>Mark it with a {@link Subscribe} annotation;</li>
* <li>Pass itself to an EventBus instance's {@link #register(Object)} method.
* </li>
* </ol>
*
* <h2>Posting Events</h2>
* <p>To post an event, simply provide the event object to the
* {@link #post(Object)} method. The EventBus instance will determine the type
* of event and route it to all registered listeners.
*
* <p>Events are routed based on their type — an event will be delivered
* to any subscriber for any type to which the event is <em>assignable.</em> This
* includes implemented interfaces, all superclasses, and all interfaces
* implemented by superclasses.
*
* <p>When {@code 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 {@link AsyncEventBus}.)
*
* <h2>Subscriber Methods</h2>
* <p>Event subscriber methods must accept only one argument: the event.
*
* <p>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.
*
* <p>The EventBus guarantees that it will not call a subscriber method from
* multiple threads simultaneously, unless the method explicitly allows it by
* bearing the {@link AllowConcurrentEvents} annotation. If this annotation is
* not present, subscriber methods need not worry about being reentrant, unless
* also called from outside the EventBus.
*
* <h2>Dead Events</h2>
* <p>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 {@link DeadEvent} and reposted.
*
* <p>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 {@link Object}, a subscriber registered to
* receive any Object will never receive a DeadEvent.
*
* <p>This class is safe for concurrent use.
*
* <p>See the Guava User Guide article on <a href=
* "http://code.google.com/p/guava-libraries/wiki/EventBusExplained">
* {@code EventBus}</a>.
*
* @author Cliff Biffle
* @since 10.0
*/
@Beta
public class EventBus {
private static final Logger logger = Logger.getLogger(EventBus.class.getName());
private final String identifier;
private final Executor executor;
private final SubscriberExceptionHandler exceptionHandler;
private final SubscriberRegistry subscribers = new SubscriberRegistry(this);
private final Dispatcher dispatcher;
/**
* Creates a new EventBus named "default".
*/
public EventBus() {
this("default");
}
/**
* Creates a new EventBus with the given {@code identifier}.
*
* @param identifier a brief name for this bus, for logging purposes. Should
* be a valid Java identifier.
*/
public EventBus(String identifier) {
this(identifier, MoreExecutors.directExecutor(),
Dispatcher.perThreadDispatchQueue(), LoggingHandler.INSTANCE);
}
/**
* Creates a new EventBus with the given {@link SubscriberExceptionHandler}.
*
* @param exceptionHandler Handler for subscriber exceptions.
* @since 16.0
*/
public EventBus(SubscriberExceptionHandler exceptionHandler) {
this("default",
MoreExecutors.directExecutor(), Dispatcher.perThreadDispatchQueue(), exceptionHandler);
}
EventBus(String identifier, Executor executor, Dispatcher dispatcher,
SubscriberExceptionHandler exceptionHandler) {
this.identifier = checkNotNull(identifier);
this.executor = checkNotNull(executor);
this.dispatcher = checkNotNull(dispatcher);
this.exceptionHandler = checkNotNull(exceptionHandler);
}
/**
* Returns the identifier for this event bus.
*/
public final String identifier() {
return identifier;
}
/**
* Returns the default executor this event bus uses for dispatching events to subscribers.
*/
final Executor executor() {
return executor;
}
/**
* Handles the given exception thrown by a subscriber with the given context.
*/
void handleSubscriberException(Throwable e, SubscriberExceptionContext context) {
checkNotNull(e);
checkNotNull(context);
try {
exceptionHandler.handleException(e, context);
} catch (Throwable e2) {
// if the handler threw an exception... well, just log it
logger.log(Level.SEVERE,
String.format("Exception %s thrown while handling exception: %s", e2, e), e2);
}
}
/**
* Registers all subscriber methods on {@code object} to receive events.
*
* @param object object whose subscriber methods should be registered.
*/
public void register(Object object) {
subscribers.register(object);
}
/**
* Unregisters all subscriber methods on a registered {@code object}.
*
* @param object object whose subscriber methods should be unregistered.
* @throws IllegalArgumentException if the object was not previously registered.
*/
public void unregister(Object object) {
subscribers.unregister(object);
}
/**
* Posts an event to all registered subscribers. This method will return
* successfully after the event has been posted to all subscribers, and
* regardless of any exceptions thrown by subscribers.
*
* <p>If no subscribers have been subscribed for {@code event}'s class, and
* {@code event} is not already a {@link DeadEvent}, it will be wrapped in a
* DeadEvent and reposted.
*
* @param event event to post.
*/
public void post(Object event) {
Iterator<Subscriber> eventSubscribers = subscribers.getSubscribers(event);
if (eventSubscribers.hasNext()) {
dispatcher.dispatch(event, eventSubscribers);
} else if (!(event instanceof DeadEvent)) {
// the event had no subscribers and was not itself a DeadEvent
post(new DeadEvent(this, event));
}
}
@Override
public String toString() {
return MoreObjects.toStringHelper(this)
.addValue(identifier)
.toString();
}
/**
* Simple logging handler for subscriber exceptions.
*/
static final class LoggingHandler implements SubscriberExceptionHandler {
static final LoggingHandler INSTANCE = new LoggingHandler();
@Override
public void handleException(Throwable exception, SubscriberExceptionContext context) {
Logger logger = logger(context);
if (logger.isLoggable(Level.SEVERE)) {
logger.log(Level.SEVERE, message(context), exception);
}
}
private static Logger logger(SubscriberExceptionContext context) {
return Logger.getLogger(EventBus.class.getName() + "." + context.getEventBus().identifier());
}
private static String message(SubscriberExceptionContext context) {
Method method = context.getSubscriberMethod();
return "Exception thrown by subscriber method "
+ method.getName() + '(' + method.getParameterTypes()[0].getName() + ')'
+ " on subscriber " + context.getSubscriber()
+ " when dispatching event: " + context.getEvent();
}
}
}