io.divide.otto

Class Bus

java.lang.Object

io.divide.otto.Bus

public class Bus
extends java.lang.Object

Dispatches events to listeners, and provides ways for listeners to register themselves.

The Bus 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 Android in-process event distribution using explicit registration or listeners. It is not a general-purpose publish-subscribe system, nor is it intended for interprocess communication.

Receiving Events

To receive events, an object should:

1. Expose a public method, known as the event handler, which accepts a single argument of the type of event desired;
2. Mark it with a Subscribe annotation;
3. Pass itself to an Bus instance's register(Object) method.

Posting Events

To post an event, simply provide the event object to the post(Object) method. The Bus 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 handler for any type to which the event is assignable. This includes implemented interfaces, all superclasses, and all interfaces implemented by superclasses.

When post is called, all registered handlers for an event are run in sequence, so handlers 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.

Handler Methods

Event handler methods must accept only one argument: the event.

Handlers should not, in general, throw. If they do, the Bus will wrap the exception and re-throw it.

The Bus by default enforces that all interactions occur on the main thread. You can provide an alternate enforcement by passing a ThreadEnforcer to the constructor.

Producer Methods

Producer methods should accept no arguments and return their event type. When a subscriber is registered for a type that a producer is also already registered for, the subscriber will be called with the return value from the producer.

Dead Events

If an event is posted, but no registered handlers 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 DeadEvent and reposted.

This class is safe for concurrent use.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_IDENTIFIER

Constructor Summary

Constructors

Constructor and Description
Bus() Creates a new Bus named "default" that enforces actions on the main thread.
Bus(java.lang.String identifier) Creates a new Bus with the given identifier that enforces actions on the main thread.
Bus(ThreadEnforcer enforcer) Creates a new Bus named "default" with the given enforcer for actions.
Bus(ThreadEnforcer enforcer, java.lang.String identifier) Creates a new Bus with the given enforcer for actions and the given identifier.
Bus(ThreadEnforcer enforcer, java.lang.String identifier, HandlerFinder handlerFinder) Test constructor which allows replacing the default HandlerFinder.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	dispatch(java.lang.Object event, EventHandler wrapper) Dispatches event to the handler in wrapper.
protected void	dispatchQueuedEvents() Drain the queue of events to be dispatched.
protected void	enqueueEvent(java.lang.Object event, EventHandler handler) Queue the event for dispatch during dispatchQueuedEvents().
void	post(java.lang.Object event) Posts an event to all registered handlers.
void	register(java.lang.Object object) Registers all handler methods on object to receive events and producer methods to provide events.
java.lang.String	toString()
void	unregister(java.lang.Object object) Unregisters all producer and handler methods on a registered object.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_IDENTIFIER

public static final java.lang.String DEFAULT_IDENTIFIER

See Also:

Constant Field Values

Constructor Detail

Bus

public Bus()

Creates a new Bus named "default" that enforces actions on the main thread.

Bus

public Bus(java.lang.String identifier)

Creates a new Bus with the given identifier that enforces actions on the main thread.

Parameters:

identifier - a brief name for this bus, for debugging purposes. Should be a valid Java identifier.

Bus

public Bus(ThreadEnforcer enforcer)

Creates a new Bus named "default" with the given enforcer for actions.

Parameters:

enforcer - Thread enforcer for register, unregister, and post actions.

Bus

public Bus(ThreadEnforcer enforcer,
   java.lang.String identifier)

Creates a new Bus with the given enforcer for actions and the given identifier.

Parameters:

enforcer - Thread enforcer for register, unregister, and post actions.

identifier - A brief name for this bus, for debugging purposes. Should be a valid Java identifier.

Bus

public Bus(ThreadEnforcer enforcer,
   java.lang.String identifier,
   HandlerFinder handlerFinder)

Test constructor which allows replacing the default HandlerFinder.

Parameters:

enforcer - Thread enforcer for register, unregister, and post actions.

identifier - A brief name for this bus, for debugging purposes. Should be a valid Java identifier.

handlerFinder - Used to discover event handlers and producers when registering/unregistering an object.

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

register

public void register(java.lang.Object object)

Registers all handler methods on object to receive events and producer methods to provide events.

If any subscribers are registering for types which already have a producer they will be called immediately with the result of calling that producer.

If any producers are registering for types which already have subscribers, each subscriber will be called with the value from the result of calling the producer.

Parameters:

object - object whose handler methods should be registered.

Throws:

java.lang.NullPointerException - if the object is null.

unregister

public void unregister(java.lang.Object object)

Unregisters all producer and handler methods on a registered object.

Parameters:

object - object whose producer and handler methods should be unregistered.

Throws:

java.lang.IllegalArgumentException - if the object was not previously registered.

java.lang.NullPointerException - if the object is null.

post

public void post(java.lang.Object event)

Posts an event to all registered handlers. This method will return successfully after the event has been posted to all handlers, and regardless of any exceptions thrown by handlers.

If no handlers have been subscribed for event's class, and event is not already a DeadEvent, it will be wrapped in a DeadEvent and reposted.

Parameters:

event - event to post.

Throws:

java.lang.NullPointerException - if the event is null.

enqueueEvent

protected void enqueueEvent(java.lang.Object event,
                EventHandler handler)

Queue the event for dispatch during dispatchQueuedEvents(). Events are queued in-order of occurrence so they can be dispatched in the same order.

dispatchQueuedEvents

protected void dispatchQueuedEvents()

Drain the queue of events to be dispatched. As the queue is being drained, new events may be posted to the end of the queue.

dispatch

protected void dispatch(java.lang.Object event,
            EventHandler wrapper)

Dispatches event to the handler in wrapper. This method is an appropriate override point for subclasses that wish to make event delivery asynchronous.

Parameters:

event - event to dispatch.

wrapper - wrapper that will call the handler.