EventBus 3.0 从入门到精通——使用详解（二）

文章索引：
EventBus 3.0 从入门到精通——初识EventBus
EventBus 3.0 从入门到精通——EventBus的应用场景
EventBus 3.0 从入门到精通——使用详解（一）
EventBus 3.0 从入门到精通——使用详解（二）

本文参考EventBus官网，有兴趣的朋友可以直接上官网阅读：http://greenrobot.org/eventbus/documentation/

黏性事件

如果你对一个已经发布的事件包含的信息感兴趣。例如，一个初始化完成的事件，或者你有一些传感器和本地数据并且你想要获取更多的历史数据。你可以使用粘性事件来代替自己去捕获这些事件。EventBus在内存中以某种类型保存粘性事件。直到粘性事件可以被发送给订阅者或者有一个明确的反馈。因此，你不需要为已经发布出去的数据做特殊处理。

粘性事件例子

一般情况下，粘性事件是短时间内被发布的一个事件。

EventBus.getDefault().postSticky(new MessageEvent("Hello everyone!"));

以上代码执行之后，如果一个新的Activity被开启。所有的粘性事件订阅者都将会立刻获得事先发布的粘性事件。

@Override
public void onStart() {
    super.onStart();
    EventBus.getDefault().register(this);
}

// UI updates must run on MainThread
@Subscribe(sticky = true, threadMode = ThreadMode.MAIN)
public void onEvent(MessageEvent event) {   
    textField.setText(event.message);
}

@Override
public void onStop() {
    EventBus.getDefault().unregister(this);    
    super.onStop();
}

手动添加和移除粘性事件

正如你看到的，当订阅者注册后最近的粘性事件就会被自动发送给订阅者。但有些时候手动检查粘性事件会更方便一些。并且有时候当我们不再需要接收粘性事件的时候，移除粘性事件也是必要的。例如：

MessageEvent stickyEvent = EventBus.getDefault().getStickyEvent(MessageEvent.class);
// Better check that an event was actually posted before
if(stickyEvent != null) {
    // "Consume" the sticky event
    EventBus.getDefault().removeStickyEvent(stickyEvent);
    // Now do something with it
}

方法removeStickyEvent 是重载的：当你在类中执行它的时候，会返回曾经获取的粘性事件。使用这个特性，我们可以改进以前的工作（修改已经处理的事件）。

MessageEvent stickyEvent = EventBus.getDefault().removeStickyEvent(MessageEvent.class);
// Better check that an event was actually posted before
if(stickyEvent != null) {
    // Now do something with it
}

优先级和事件取消

大多数使用EventBus的场景是不需要优先级和事件取消的。它们会被使用在一些特殊场景。例如，一个事件在App处于前景操作和用户不可见的情况下触发不同的UI逻辑。

订阅者优先级

在注册期间你可能会改变事件传送给订阅者的优先级。

@Subscribe(priority = 1);
public void onEvent(MessageEvent event) {
    ...
}

在同样的传送线程内部，高优先级的订阅者会比低优先级的订阅者早收到事件。默认的优先级是0.
注意：优先级不会影响到不同线程模式之间的传递优先级。

取消线程传递

你可以在订阅者的事件处理方法中调用cancelEventDelivery(Object event) 方法取消一个线程的传递。该线程之后的传递会被取消，之后的订阅者就不会收到事件了。

// Called in the same thread (default)
@Subscribe
public void onEvent(MessageEvent event){
    // Process the event
    ...
    // Prevent delivery to other subscribers
    EventBus.getDefault().cancelEventDelivery(event) ;
}

一般事件会在高级别的订阅者那里取消。事件处理方法和发布事件是同一个线程的时候是禁止取消事件的（ThreadMode.PostThread）。

订阅索引

订阅索引是一个EventBus3的新特性。它是一个提升订阅者注册速度的可选项。订阅索引可以在运行时通过EventBus的注解处理器创建。索引不是必须的，在Android系统上推荐使用索引来提升性能。

使用索引的前提条件

注意：只有订阅者和事件是public的的情况下@Subscriber 注解注释的方法才能够使用索引。 并且由于Java注解处理器自身的技术局限性。@Subscribe 注解不能都分辨出匿名类。当EventBus不能都使用索引时，它会在运行时自动退回到反射模式。因此它还能继续工作，只是有一点点慢而已。

怎样生成一个索引

使用注解处理器

如果您的Android Gradle Plugin 版本是 2.2.0 或者更高可以直接使用，否则您需要使用android-apt来配置。
你需要通过annotationProcessor 属性将EventBus的注解处理器添加到build中，用来开启索引生成。并且需要设置eventBusIndex 参数，来指定有资格生成索引的所有类。例如，添加以下部分配置到你的Gradle build 脚本中。

android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                arguments = [ eventBusIndex : 'com.example.myapp.MyEventBusIndex' ]
            }
        }
    }
}

dependencies {
    compile 'org.greenrobot:eventbus:3.0.0'
    annotationProcessor 'org.greenrobot:eventbus-annotation-processor:3.0.1'
}

使用kapt

如果你想要在Kotlin代码中使用EventBus。你就需要使用kapt 代替 annotationProcessor。

apply plugin: 'kotlin-kapt' // ensure kapt plugin is applied

dependencies {
    compile 'org.greenrobot:eventbus:3.0.0'
    kapt 'org.greenrobot:eventbus-annotation-processor:3.0.1'
}

kapt {
    arguments {
        arg('eventBusIndex', 'com.example.myapp.MyEventBusIndex')
    }
}

使用android-apt

如果以上配置在你的项目中都没有生效，也可以使用android-apt 这个Gradle插件来添加EventBus注解处理器。添加如下代码到你的build.gradle中：

buildscript {
    dependencies {
        classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8'
    }
}

apply plugin: 'com.neenbedankt.android-apt'

dependencies {
    compile 'org.greenrobot:eventbus:3.0.0'
    apt 'org.greenrobot:eventbus-annotation-processor:3.0.1'
}

apt {
    arguments {
        eventBusIndex "com.example.myapp.MyEventBusIndex"
    }
}

怎样使用索引

在项目成功编译之后，通过eventBusIndex 属性指定的类就会生成索引。然后使用EventBus设置如下代码：

EventBus eventBus = EventBus.builder().addIndex(new MyEventBusIndex()).build();

或者你想始终使用默认的实例在项目中：

EventBus.builder().addIndex(new MyEventBusIndex()).installDefaultEventBus();
// Now the default instance uses the given index. Use it like this:
EventBus eventBus = EventBus.getDefault();

索引Libraries

library可以使用同样的原理设置索引。使用如下方法，你可以在EventBus中设置多个索引类。

EventBus eventBus = EventBus.builder()
    .addIndex(new MyEventBusAppIndex())
    .addIndex(new MyEventBusLibIndex()).build();

ProGuard

你可以在ProGuard配置中添加如下配置，防止订阅者被移除。

-keepattributes *Annotation*
-keepclassmembers class ** {
    @org.greenrobot.eventbus.Subscribe <methods>;
}
-keep enum org.greenrobot.eventbus.ThreadMode { *; }

# Only required if you use AsyncExecutor
-keepclassmembers class * extends org.greenrobot.eventbus.util.ThrowableFailureEvent {
    <init>(java.lang.Throwable);
}

注意：无论你是否使用subscriber index都需要以上配置。

AsyncExecutor

AsyncExecutor就像一个线程池，但是有异常处理。当运行失败的时候AsyncExecutor会把异常包裹在一个事件里发布出去。
免责声明：AsyncExecutor 是一个非核心的公共类，它可能会在后台线程中保存一些你的错误处理代码。但是它不是EventBus核心类。
通常情况下，你可以调用AsyncExecutor.create() 创建一个实例并在Application范围内保持它。之后可以创建一个实现了RunnableEx 接口的类并把它的对象传入AsyncExecutor 的执行方法用来执行一些事情。不像Runnable RunnableEx 会抛出异常。如果一个RunnableEx 抛出一个异常，它会被捕获并包装成一个ThrowableFailureEvent 并被发布出去。
执行的例子：

AsyncExecutor.create().execute(
    new AsyncExecutor.RunnableEx() {
        @Override
        public void run() throws LoginException {
            // No need to catch any Exception (here: LoginException)
            remote.login();
            EventBus.getDefault().postSticky(new LoggedInEvent());
        }
    }
);

接收部分的例子：

@Subscribe(threadMode = ThreadMode.MAIN)
public void handleLoginEvent(LoggedInEvent event) {
    // do something
}

@Subscribe(threadMode = ThreadMode.MAIN)
public void handleFailureEvent(ThrowableFailureEvent event) {
    // do something
}

AsyncExecutor Builder

如果你想要定制AsyncExecutor的实例，可以通过调用静态方法AsyncExecutor.builder()。这个方法会返回一个Builder，这个builder可以定制EventBus实例、线程池、失败事件的类。例如：失败事件可以只关联具体的Activity对象或者类。如果你自动以的失败事件实现了HasExecutionScope 接口，AsyncExecutor 会自动设定事件执行范围。像这样你的订阅者能够查询到失败事件并做出响应。