com.ekuefler.supereventbus
Class EventBus

java.lang.Object
  com.ekuefler.supereventbus.EventBus

public class EventBus
extends Object

An event bus implementation for GWT that is significantly more powerful than the built-in EventBus. Features provided by this event bus over the built-in one include the following:

1. Declarative handler registration - instead of using events to register individual handlers, methods can be annotated with Subscribe and are all automatically registered in a single bind step.
2. Flexible typing - with GWT's event bus, all events must extend GwtEvent and implement associated boilerplate. With SuperEventBus, any object can be fired on the bus, even primitive types.
3. Polymorphism - GWT's event type are monomorphic, which means that a handler for MyEvent would never see any subclasses of MyEvent. In contrast, SuperEventBus treats events polymorphically, so a handler for MyEvent would see any subclass of MyEvent. This allows you to define hierarchies of events and handle them together, define tagging interfaces to mark groups of events that should be handled in the same way, or event define a handle for Object to handle all events fired by the system. It is also possible to handle multiple events of unrelated types with the same handler method (see below).
4. Better-behaved event dispatch - Using the GWT event bus, firing an event from another event handler will cause that new event to be processed before processing of the original event completes. This means that other components listening for both events will see them in an undefined order. SuperEventBus uses a queue to dispatch events, so if event A is fired before event B, handlers we always receive event A before receiving event B.
5. Handler priorities - handlers on the GWT event bus are always invoked in an undefined order. With SuperEventBus, you can use the WithPriority annotation to force some handlers to be run before other handlers.
6. Filtering - handlers on the GWT event bus will always be invoked whenever they are registered. With SuperEventBus, you can use the When annotation to conditionally disable certain handlers, based on either properties of the handler or based on the event being handled.
7. Handling events with unrelated types - Standard polymorphism is usually powerful enough to express event handlers that should work on multiple types of events, but occasionally it is necessary to handle multiple events of unrelated types using the same method. SuperEventBus allows this via the MultiEvent class and EventTypes annotation, which allow events of several specified types to be wrapped and passed to a single method.
8. DeadEvent - in order to help identify misconfiguration issues, SuperEventBus automatically posts a DeadEvent whenever an event is fired that has no handlers. The application can subscribe to this event in order to log it or report an error.

To register handlers on the event bus, you must first declare an EventRegistration interface for the type of the handler like this:

 interface MyRegistration extends EventRegistration<TestOwner> {}
 

This is necessary so that the GWT compiler can generate dispatch code specific to the handler class - you should not implement this interface yourself. Once this interface is defined, you can register an object to listen on the event bus like this:

 eventBus.register(this, MyRegistration.class);
 

This will cause all Subscribe-annotated methods on the current object to be invoked whenever an appropriate event is fired. Methods annotated with Subscribe must take a single argument, which specifies the type of event to handle. An event can be any Java object, and a handler for a given type will be invoked whenever an object of that type or its subclasses is posted on the event bus. To post an object to an event bus, simply call

 eventBus.post(new MyEvent("some data"));
 

Author:

ekuefler@gmail.com (Erik Kuefler)

Constructor Summary

EventBus()
Creates a new event bus.

Method Summary

void	addExceptionHandler(ExceptionHandler exceptionHandler) Adds an exception handler to be notified whenever an exception occurs while dispatching an event.
<T> void	post(T event) Posts the given event to all handlers registered on this event bus.
<T> void	register(T owner, Class<? extends EventRegistration<T>> registrationClass) Registers all Subscribe-annotated in the given object on the event bus.
void	unregister(Object owner) Unregisters all event handlers on the given object.

Methods inherited from class java.lang.Object

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

Constructor Detail

EventBus

public EventBus()

Creates a new event bus. In dev mode, any exceptions that occur while dispatching events will be logged with GWT.log(java.lang.String). In prod mode, exceptions are silently ignored unless a handler is added via addExceptionHandler(com.ekuefler.supereventbus.ExceptionHandler).

Method Detail

post

public <T> void post(T event)

Posts the given event to all handlers registered on this event bus. This method will return after the event has been posted to all handlers and will never throw an exception. After the event has been posted, any exceptions thrown by handlers of the event are collected and passed to each exception handler registered via addExceptionHandler(ExceptionHandler).

Parameters:

event - event object to post to all handlers

register

public <T> void register(T owner,
                         Class<? extends EventRegistration<T>> registrationClass)

Registers all Subscribe-annotated in the given object on the event bus. Any methods annotated with Subscribe must take a single argument specifying the event to handle. After an object has been registered, whenever an event is posted on the event bus via post(T), all handlers on that object for that event's type or its supertypes will be invoked with that event.

Parameters:

owner - object to scan for Subscribe-annotated methods to register

registrationClass - the class object of a registration interface for the given owner

unregister

public void unregister(Object owner)

Unregisters all event handlers on the given object. After unregistering, Subscribe- annotated methods on that object will never be invoked when an event is posted (unless the object is registered again). This given object must have already been registered on the event bus.

Parameters:

owner - object whose handlers should be disabled. Must already have been registered via a call to register(T, java.lang.Class>).

Throws:

IllegalArgumentException - if the given object was never registered on this event bus

addExceptionHandler

public void addExceptionHandler(ExceptionHandler exceptionHandler)

Adds an exception handler to be notified whenever an exception occurs while dispatching an event. Exception handlers are invoked only after all handlers have had a chance to process an event - at that point, every exception that occurred during dispatch is wrapped in an EventBusException and posted to every exception handler.

Parameters:

exceptionHandler - handler to be notified when exceptions occur