以下内容直接翻译了EventBus的注释:
com.google.common.eventbus.EventBus介绍:
首先这个类是线程安全的,
分发事件到监听器,并提供相应的方式让监听器注册它们自己。
EventBus允许组件之间进行 “发布-订阅” 式的通信,而不需要这些组件彼此知道对方。EventBus是专门设计用来替代传统的Java进程内的使用显示注册方式的事件发布模式。EventBus不是一个通用的发布-订阅系统,也不是用于进程间通信。
接收事件
一个对象接收事件时,将这样做:
- 暴露一个public方法 ,称之为事件订阅者(subscriber),这个方法接收一个参数,参数的类型是事件期望的类型。
- 用@Subscribe注解标计这个方法
- 通过一个EventBus实例的register(Object)方法注册自己
提交事件
提交事件时,将简单的把事件对象作为参数去调用 EventBus实例的pose(Object)方法。EventBus实例将根据事件对象的类型决定如何路由这个事件对象给所有已注册的监听器。
事件的路由是基于事件对象的类型—— 一个事件将被交付给可以被分配的任意的订阅者。这个包括事件对象实现的接口,事件对象的所有的父类,所有被父类实现的接口。
当post方法被调用后,所有对这个事件进行注册的订阅者会按顺序进行消费, 所以订阅者会快速合理地运行。如果一个事件可能触发一个扩展的过程(比如数据库负载),生成一个线程或队列之后处理。(一种方便的方法,使用一个AsyncEventBus)。
订阅方法
事件订阅者的方法必需只能接受一个参数:事件对象。
订阅者方法如果抛出异常,EventBus实例将捕获和记录异常。很少有方案这样去处理错误,只是在开发时可用于帮助我们发现问题时会这样做。
EventBus实例保证在同时不会有多个线程调用,除非这个方法通过@AllowConcurrentEvents注解明确允许。如果这个注解没有出现,订阅者方法也无需担心方法被重入,除非在EventBus实例之外有代码调用该方法。
死事件
如果一个事件被提交了,但是没有相应的订阅者接受它,就可以认为这是一个死事件。然后会给系统一个机会来处理这个死事件。可以通过包装一个类DeadEvent的实例来处理这个死事件。然后可以写一个类专门负责订阅死事件。
如果一个订阅者监听的事件对象是所有事件的父类,比如这个事件订阅了一个Object的事件对象,那么将不会出现死事件。
原文如下:
Dispatches events to listeners, and provides ways for listeners to register themselves.
The EventBus 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 Java in-process event distribution using explicit registration. It is not a general-purpose publish-subscribe system, nor is it intended for interprocess communication.
Receiving Events
To receive events, an object should:
- Expose a public method, known as the event subscriber, which accepts a single argument of the type of event desired;
- Mark it with a
Subscribe
annotation; - Pass itself to an EventBus instance's
register(Object)
method.
Posting Events
To post an event, simply provide the event object to the post(Object)
method. The EventBus 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 subscriber 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 subscribers for an event are run in sequence, so subscribers 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. (For a convenient way to do this, use an AsyncEventBus
.)
Subscriber Methods
Event subscriber methods must accept only one argument: the event.
Subscribers should not, in general, throw. If they do, the EventBus will catch and log the exception. This is rarely the right solution for error handling and should not be relied upon; it is intended solely to help find problems during development.
The EventBus guarantees that it will not call a subscriber method from multiple threads simultaneously, unless the method explicitly allows it by bearing the AllowConcurrentEvents
annotation. If this annotation is not present, subscriber methods need not worry about being reentrant, unless also called from outside the EventBus.
Dead Events
If an event is posted, but no registered subscribers 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.
If a subscriber for a supertype of all events (such as Object) is registered, no event will ever be considered dead, and no DeadEvents will be generated. Accordingly, while DeadEvent extends Object
, a subscriber registered to receive any Object will never receive a DeadEvent.