xyz.justblink.eventbus

Class EventBus

java.lang.Object

xyz.justblink.eventbus.EventBus

Direct Known Subclasses:

AsyncEventBus

public class EventBus
extends Object

This will dispatch event to its subscribers and provides a way to register objects themselves as subscribers.

This is implemented by mimicking features of Google's Guava EventBus. The EventBus makes use of a publisher-subscriber style event handling mechanism. This features enables components to have a loose coupling between them. That is, components which initiate the event and the components which receives the events don't have to be aware of each other. This is intended for communication only within the particular process (Not for inter-process communication).

Receive events

To receive events, an object should satisfy following conditions:

1. Expose a public method which one accepts only one argument of the type of the desired event
2. Mark it with Subscribe annotation
3. Pass itself to EventBus instance's register(Object) method

Posting events

Pass the desired event to EventBus instance's post(Object) method.

Currently this will only dispatch the event to the subscribers with exact class match. (Not for subscribers of superclasses and interfaces which that class implements)

When an event is posted to bus, it will begin calling subscribers in sequence. Because of that, subscriber methods should be quick. If you want a subscriber method to run for a long time, spawn it in a different thread. You can use AsyncEventBus for this purpose

More about subscriber methods

Subscribers should not generally throw. It should be handled by try catch. Default behavior is just to log it.

The EventBus guarantees that it will not call a subscriber method from multiple threads simultaneously, unless the method explicitly allows it by bearing the AcceptConcurrentEvents annotation. If this annotation is not present, subscriber methods need not worry about being reentrant, unless also called from outside the EventBus.

To override this behavior (allow subscriber method to be reentrant), provide Dispatcher.immediateDispatcher() as the dispatcher of choice.

Dead Events

If there are no subscribers for an event posted, it it considered as dead. They are posted again by wrapping inside a DeadEvent and can be caught by subscribing to Dead Events

This class is thread safe

Author:

Kasun Piyumal

Constructor Summary

Constructors

Constructor and Description
EventBus() Creates an EventBus named "default"
EventBus(Dispatcher dispatcher) Creates a new EventBus with provided Dispatcher
EventBus(String identifier) Creates a new EventBsus with identifier
EventBus(SubscriberExceptionHandler exceptionHandler) Creates a new EventBus with provided SubscriberExceptionHandler
EventBus(SubscriberExceptionHandler exceptionHandler, Dispatcher dispatcher) Creates a new EventBus with provided SubscriberExceptionHandler and Dispatcher

Method Summary

Modifier and Type	Method and Description
String	getIdentifier()
void	post(Object event)
void	register(Object object)
void	unregister(Object object)

Methods inherited from class java.lang.Object

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

Constructor Detail

EventBus

public EventBus()

Creates an EventBus named "default"

EventBus

public EventBus(String identifier)

Creates a new EventBsus with identifier

Parameters:

identifier - name for the bus, can be useful in logging if there are multiple buses

EventBus

public EventBus(SubscriberExceptionHandler exceptionHandler)

Creates a new EventBus with provided SubscriberExceptionHandler

Parameters:

exceptionHandler - Handler for exceptions thrown by subscribers methods

EventBus

public EventBus(Dispatcher dispatcher)

Creates a new EventBus with provided Dispatcher

Parameters:

dispatcher - Dispatcher of choice for the bus. Be careful when using this, because methods may need to be reentrant for some dispatchers

EventBus

public EventBus(SubscriberExceptionHandler exceptionHandler,
                Dispatcher dispatcher)

Creates a new EventBus with provided SubscriberExceptionHandler and Dispatcher

Parameters:

exceptionHandler - Handler for exceptions thrown by subscribers methods

dispatcher - Dispatcher of choice for the bus. Be careful when using this, because methods may need to be reentrant for some dispatchers

Method Detail

getIdentifier

public String getIdentifier()

register

public void register(Object object)

unregister

public void unregister(Object object)

post

public void post(Object event)