Bus (Otto 1.3.8 API)

java.lang.Object
- com.squareup.otto.Bus

```
public class Bus
extends 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.
Author:

Cliff Biffle, Jake Wharton

Field Summary

Fields
Modifier and Type Field and Description

static String DEFAULT_IDENTIFIER

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_IDENTIFIER`

Constructor Summary

Constructors
Constructor and Description
`Bus()` Creates a new Bus named "default" that enforces actions on the main thread.
`Bus(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, String identifier)` Creates a new Bus with the given `enforcer` for actions and the given `identifier`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`dispatch(Object event, com.squareup.otto.EventHandler wrapper)` Dispatches `event` to the handler in `wrapper`.
`protected void`	`dispatchQueuedEvents()` Drain the queue of events to be dispatched.
`protected void`	`enqueueEvent(Object event, com.squareup.otto.EventHandler handler)` Queue the `event` for dispatch during `dispatchQueuedEvents()`.
`void`	`post(Object event)` Posts an event to all registered handlers.
`void`	`register(Object object)` Registers all handler methods on `object` to receive events and producer methods to provide events.
`String`	`toString()`
`void`	`unregister(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 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(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,
           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.
- Method Detail
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - register
```
public void register(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:
    
    NullPointerException - if the object is null.
  - unregister
```
public void unregister(Object object)
```
    Unregisters all producer and handler methods on a registered object.
    
    Parameters:
    
    object - object whose producer and handler methods should be unregistered.
    
    Throws:
    
    IllegalArgumentException - if the object was not previously registered.
    
    NullPointerException - if the object is null.
  - post
```
public void post(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:
    
    NullPointerException - if the event is null.
  - enqueueEvent
```
protected void enqueueEvent(Object event,
                            com.squareup.otto.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(Object event,
                        com.squareup.otto.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.

Class Bus

Receiving Events

Posting Events

Handler Methods

Producer Methods

Dead Events

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_IDENTIFIER

Constructor Detail

Bus

Bus

Bus

Bus

Method Detail

toString

register

unregister

post

enqueueEvent

dispatchQueuedEvents

dispatch