org.intelligentsia.eventbus

Class BasicEventBus

java.lang.Object

org.intelligentsia.eventbus.BasicEventBus

All Implemented Interfaces:

EventBus

public final class BasicEventBus
extends Object
implements EventBus

A simple Event Bus implementation which receives events or messages from various sources and distributes them to all subscribers of the event type. This is highly useful for programs which are event driven. Swing applications in particular can benefit from an event bus architecture, as opposed to the traditional event listener architecture it employs.

The BasicEventBus class is thread safe and uses a background thread to notify the subscribers of the event. The subscribers are notified in a serial fashion, and only one event will be published at a time. Though, the publish(Object) method is done in a non-blocking way.

Subscribers subscribe to the EventBus using the subscribe(Object) method. A specific subscriber type is not required, but the subscriber will be reflected to find all methods annotated with the EventHandler annotations. These methods will be invoked as needed by the event bus based on the type of the first parameter to the annotated method.

An event handler can indicate that it can veto events by setting the EventHandler.canVeto() value to true. This will inform the EventBus of the subscriber's desire to veto the event. A vetoed event will not be sent to the regular subscribers.

During publication of an event, all veto EventHandler methods will be notified first and allowed to throw a VetoException indicating that the event has been vetoed and should not be published to the remaining event handlers. If no vetoes have been made, the regular subscriber handlers will be notified of the event.

Subscribers are stored using a WeakReference such that a memory leak can be avoided if the client fails to unsubscribe at the end of the use. However, calling the unsubscribe(Object) method is highly recommended none-the-less.

Author:

Adam Taft, Jerome Guibert

Constructor Summary

Constructors

Constructor and Description
BasicEventBus() Default constructor sets up the executorService property to use the Executors.newCachedThreadPool() implementation.
BasicEventBus(ExecutorService executorService, boolean waitForHandlers)

Method Summary

Methods

Modifier and Type	Method and Description
boolean	hasPendingEvents() Returns if the event bus has pending events.
void	publish(Object event) Publish the specified event to the event bus.
void	shutdown(long timeout, TimeUnit unit) Shutdown underlaying events and wait until terminaison or time out occurs.
void	subscribe(Object subscriber) Subscribe the specified instance as a potential event subscriber.
void	unsubscribe(Object subscriber) Unsubscribe the specified subscriber from receiving future published events.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicEventBus

public BasicEventBus()

Default constructor sets up the executorService property to use the Executors.newCachedThreadPool() implementation. The configured ExecutorService will have a custom ThreadFactory such that the threads returned will be daemon threads (and thus not block the application from shutting down).

BasicEventBus

public BasicEventBus(ExecutorService executorService,
             boolean waitForHandlers)

Method Detail

subscribe

public void subscribe(Object subscriber)

Subscribe the specified instance as a potential event subscriber. The subscriber must annotate a method (or two) with the EventHandler annotation if it expects to receive notifications.

Note that the EventBus maintains a WeakReference to the subscriber, but it is still adviced to call the unsubscribe(Object) method if the subscriber does not wish to receive events any longer.

Specified by:

subscribe in interface EventBus

Parameters:

subscriber - The subscriber object which will receive notifications on EventHandler annotated methods.

unsubscribe

public void unsubscribe(Object subscriber)

Unsubscribe the specified subscriber from receiving future published events.

Specified by:

unsubscribe in interface EventBus

Parameters:

subscriber - The object to unsubcribe from future events.

publish

public void publish(Object event)

Publish the specified event to the event bus. Based on the type of the event, the EventBus will publish the event to the subscribing objects.

Specified by:

publish in interface EventBus

Parameters:

event - The event to publish on the event bus.

hasPendingEvents

public boolean hasPendingEvents()

Returns if the event bus has pending events.

Specified by:

hasPendingEvents in interface EventBus

Returns:

Returns true if the event bus has pending events to publish.

shutdown

public void shutdown(long timeout,
            TimeUnit unit)
              throws InterruptedException

Shutdown underlaying events and wait until terminaison or time out occurs.

Parameters:

timeout -

unit -

Throws:

InterruptedException