Event Bus

Overview

This post describes greenrobot's EventBus, the event bus that we use in our application.

Background

Events are a way of passing messages between different components in an application. In Android, there are several traditional ways to accomplish this--each with its own significant drawbacks:

1. Intents and BroadcastReceivers

   To use Intents to pass messages, every component that wants receive messages must register a BroadcastReceiver--which is a lot of work. Furthermore, Intents contain no type information, meaning that the messages passed can only be simple key-value pairs.

2. Callback listeners

   In order to use listeners, every component that wants to send messages must probably implement listener registering and unregistering. Furthermore, every component that wants to receive messages must implement the correct listener interface and be sure to unregister itself before it goes out of scope (or run the risk of memory leaks.

3. Using global state

   The final option you have is to use global state, such as by storing it in the Application object. This isn't strictly message passing and has a lot of overhead: You still need some sort of signaling mechanism and the Application class can get extremely bloated.

Events help address these issues.

Usage

Events are messages that are routed by an event bus that's shared by application components. Components wanting to receive messages subscribe to the event bus; components wanting to send messages post to it.

Subscribing

In order to subscribe to the event bus, a component must have a method named onEvent for each event type it cares about:

  public void onEvent(MyEvent event) {
    ...
  }

The component must also register for the event bus when it is ready to handle messages (typically during an Activity's onResume() method):

  @Override
  protected void onResume() {
    ...
    EventBus.getDefault().register(this);
  }

and unregister when it is no longer able to handle messages (typically during the onPause() method):

  @Override
  protected void onPause() {
    ...
    EventBus.getDefault().unregister(this);
  }

By default, you'll be called back on the calling thread. If you need to be called on the main thread, you'll subscribe with a method called onEventMainThread:

  public void onEventMainThread(MyEvent event) {
    ...
  }

Posting

Posting is even easier:

    public void myMethod() {
      ...
      EventBus.getDefault().post(new MyEvent());
    }

Posting Stickily

Because your component might not always be ready to handle events (e.g., when an Activity is paused), you might miss some. To handle this, you can post events stickily, which stay around until another event of the same type is posted:

    public void myMethod() {
      ...
      EventBus.getDefault().postSticky(new MyEvent());
    }

The subscriber must explicitly register for sticky events:

  @Override
  protected void onResume() {
    ...
    EventBus.getDefault().registerSticky(this);
  }

More Info

If you want to learn more about EventBus, read through the official HOWTO on GitHub.