org.killbill.commons.eventbus.EventBus Maven / Gradle / Ivy
/*
* Copyright (C) 2007 The Guava Authors
* Copyright 2020-2022 Equinix, Inc
* Copyright 2014-2022 The Billing Project, LLC
*
* The Billing Project licenses this file to you 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 org.killbill.commons.eventbus;
import java.util.Iterator;
import java.util.Locale;
import java.util.concurrent.Executor;
import java.util.logging.Level;
import java.util.logging.Logger;
import org.killbill.commons.eventbus.Dispatcher.ImmediateDispatcher;
import org.killbill.commons.utils.Preconditions;
import org.killbill.commons.utils.concurrent.DirectExecutor;
/**
* Dispatches events to listeners, and provides ways for listeners to register themselves.
*
* Avoid EventBus
*
* We recommend against using EventBus. It was designed many years ago, and newer
* libraries offer better ways to decouple components and react to events.
*
*
To decouple components, we recommend a dependency-injection framework. For Android code, most
* apps use Dagger. For server code, common options include Guice and Spring.
* Frameworks typically offer a way to register multiple listeners independently and then request
* them together as a set (Dagger, Guice, Spring).
*
*
To react to events, we recommend a reactive-streams framework like RxJava (supplemented with its RxAndroid extension if you are building for
* Android) or Project Reactor. (For the basics of
* translating code from using an event bus to using a reactive-streams framework, see these two
* guides: 1, 2.) Some usages
* of EventBus may be better written using Kotlin coroutines, including Flow and Channels. Yet other usages are better served
* by individual libraries that provide specialized support for particular use cases.
*
*
Disadvantages of EventBus include:
*
*
* - It makes the cross-references between producer and subscriber harder to find. This can
* complicate debugging, lead to unintentional reentrant calls, and force apps to eagerly
* initialize all possible subscribers at startup time.
*
- It uses reflection in ways that break when code is processed by optimizers/minimizers like
* R8 and Proguard.
*
- It doesn't offer a way to wait for multiple events before taking action. For example, it
* doesn't offer a way to wait for multiple producers to all report that they're "ready," nor
* does it offer a way to batch multiple events from a single producer together.
*
- It doesn't support backpressure and other features needed for resilience.
*
- It doesn't provide much control of threading.
*
- It doesn't offer much monitoring.
*
- It doesn't propagate exceptions, so apps don't have a way to react to them.
*
- It doesn't interoperate well with RxJava, coroutines, and other more commonly used
* alternatives.
*
- It imposes requirements on the lifecycle of its subscribers. For example, if an event
* occurs between when one subscriber is removed and the next subscriber is added, the event
* is dropped.
*
- Its performance is suboptimal, especially under Android.
*
- It doesn't support parameterized
* types.
*
- With the introduction of lambdas in Java 8, EventBus went from less verbose than listeners
* to more verbose.
*
*
* EventBus Summary
*
* 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 subscriber, which accepts a single
* argument of the type of event desired;
*
- Mark it with a {@link Subscribe} annotation;
*
- Pass itself to an EventBus instance's {@link #register(Object)} method.
*
*
* Posting Events
*
* 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.
*
*
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.
*
*
Subscriber Methods
*
* 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 {@link
* AllowConcurrentEvents} annotation. If this annotation is not present, subscriber methods need not
* worry about being reentrant, unless also called from outside the EventBus.
*
*
Dead Events
*
* 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.
*
*
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.
*
*
This class is safe for concurrent use.
*
*
See the Guava User Guide article on {@code EventBus}.
*
* @author Cliff Biffle
* @since 10.0
*/
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}. Different with original Guava's implementation,
* this constructor will use {@link ImmediateDispatcher} and {@link DefaultCatchableSubscriberExceptionsHandler}.
*
* @param identifier a brief name for this bus.
*/
public EventBus(final String identifier) {
this(identifier, DirectExecutor.INSTANCE, Dispatcher.immediate(), new DefaultCatchableSubscriberExceptionsHandler());
}
/**
* Creates a new EventBus with the given {@link SubscriberExceptionHandler}. Different with original Guava's
* implementation, this constructor will use {@link ImmediateDispatcher} as default dispatcher.
*
* @param exceptionHandler Handler for subscriber exceptions.
* @since 16.0
*/
public EventBus(final SubscriberExceptionHandler exceptionHandler) {
this("default", DirectExecutor.INSTANCE, Dispatcher.immediate(), exceptionHandler);
}
public EventBus(final String identifier, final Executor executor, final Dispatcher dispatcher, final SubscriberExceptionHandler exceptionHandler) {
this.identifier = Preconditions.checkNotNull(identifier);
this.executor = Preconditions.checkNotNull(executor);
this.dispatcher = Preconditions.checkNotNull(dispatcher);
this.exceptionHandler = Preconditions.checkNotNull(exceptionHandler);
}
/**
* Returns the identifier for this event bus.
*
* @since 19.0
*/
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(final Throwable e, final SubscriberExceptionContext context) {
Preconditions.checkNotNull(e);
Preconditions.checkNotNull(context);
try {
exceptionHandler.handleException(e, context);
} catch (final Throwable e2) {
// if the handler threw an exception... well, just log it
logger.log(
Level.SEVERE,
String.format(Locale.ROOT, "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(final 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(final 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.
*
*
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(final Object event) {
final Iterator 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));
}
}
/**
* Post an event with ability to handle exception, if any.
*
* Using this method require that when creating {@code EventBus} instance:
*
* - exceptionHandler should be instance of CatchableSubscriberExceptionHandler
* - executor should be instance of DirectExecutor
* - dispatcher should be instance of ImmediateDispatcher
*
*
* @param event event to post.
* @throws EventBusException
*/
public void postWithException(final Object event) throws EventBusException {
Preconditions.checkState(exceptionHandler instanceof CatchableSubscriberExceptionHandler, "exceptionHandler should be instance of CatchableSubscriberExceptionHandler");
Preconditions.checkState(executor instanceof DirectExecutor, "executor should be instance of DirectExecutor");
Preconditions.checkState(dispatcher instanceof ImmediateDispatcher, "dispatcher should be instance of ImmediateDispatcher");
final CatchableSubscriberExceptionHandler catchableExceptionHandler = (CatchableSubscriberExceptionHandler) exceptionHandler;
final Iterator eventSubscribers = subscribers.getSubscribers(event);
if (eventSubscribers.hasNext()) {
// Just in case...
catchableExceptionHandler.reset();
RuntimeException guavaException = null;
final Exception subscriberException;
try {
dispatcher.dispatch(event, eventSubscribers);
} catch (final RuntimeException e) {
guavaException = e;
} finally {
// This works because we are both using the immediate dispatcher and the direct executor
// Note: we always want to dequeue here to avoid any memory leaks
subscriberException = catchableExceptionHandler.caughtException();
}
if (guavaException != null) {
throw guavaException;
}
if (subscriberException != null) {
throw new EventBusException(subscriberException);
}
} 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 "EventBus {" +
"identifier='" + identifier + '\'' +
'}';
}
}