org.timothyb89.eventbus

Class EventBus

java.lang.Object

org.timothyb89.eventbus.EventBus

public class EventBus
extends Object

Defines an event bus that handles the dispatching of events to client classes. The owner class can define "buckets" or queues for subclasses of Event, which may then be joined by client classes. The owner can then push an instance of the Event to the bus using push(Event) which will notify all registered classes listening for that event type, or any of its superclasses.

This implementation allows for inherited and overridden event types, assuming that each superclass has defined a queue specifically for that type. When listeners are registered, they are added to all queues 'compatible' with their event type, meaning that they will be placed into the event queue for their direct event type, and any assignable superclasses. Then, when an event is pushed to the queue, only the queue for that exact type is notified. This ensures that listeners will only ever receive a single notification for events compatible via multiple superclasses.

Definition of listeners requires the EventHandler annotation. When some client class calls register(Object), all methods with an @EventHandler annotation are scanned and added to the appropriate event queues.

@EventHandler takes an optional priority parameter. Events with a higher priority (defined either as an integer or preferably using a constant in EventPriority) will be notified before events with a lower (more negative) priority.

Events may also be 'vetoed', in the sense that an event at a higher priority may prevent handlers further down in the queue from being executed. While useful, this should be used with caution to ensure potentially important events may still get an opportunity to be notified.

Author:

timothyb89

Constructor Summary

Constructors

Constructor and Description
EventBus()

Method Summary

Methods

Modifier and Type	Method and Description
void	add(Class<? extends Event> clazz) Defines a new event type.
void	deregister(Object o) Removes the given object from all event queues that it may be a member of.
EventQueueDefinition	getQueueForClass(Class<? extends Event> clazz) Gets the EventQueueDefinition for the given class.
void	push(Event event) Pushes the given event to the message bus.
void	push(Event event, int priority) Pushes the given event to the bus, but only notifies those with a priority flag greater than or equal to the given priority.
void	register(Object o) Attempts to register all methods of the given object annotated with EventHandler to receive events from this bus.
protected void	registerMethod(Object o, Method m, int priority, boolean vetoable) Registers the given method to the event bus.
void	remove(Class<? extends Event> clazz) Removes the event queue for the given class.

Methods inherited from class java.lang.Object

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

Constructor Detail

EventBus

public EventBus()

Method Detail

add

public void add(Class<? extends Event> clazz)

Defines a new event type. A new event queue will be added for the provided class, and future invocations of push(Event) will notify registered listeners.

Note that this class is not thread-safe; add() and remove() may cause a ConcurrentModificationException when used concurrently.

Parameters:

clazz - the event class to register

getQueueForClass

public EventQueueDefinition getQueueForClass(Class<? extends Event> clazz)

Gets the EventQueueDefinition for the given class. If no event queue has been created for the given class, null is returned. Note that this will not return superclasses of the given class, only exact matches.

Parameters:

clazz - The class to search for

Returns:

the event queue for the given class

remove

public void remove(Class<? extends Event> clazz)

Removes the event queue for the given class. If no queue for the given class is found, the method fails silently.

Parameters:

clazz - the class for which to remove the queue

push

public void push(Event event)

Pushes the given event to the message bus. This will notify listeners in order of their priority; any handler that throws an EventVetoException will cause handlers further down in the queue to be skipped. Specifically, this notifies the event queue that exactly matches the class (as handlers are added to superclass queues at registration time)

If no queue exists for the given event type, no listeners will be notified and the method will fail silently.

Unlike add(Class) and remove(Class), this method is thread-safe and can be safely used concurrently.

Parameters:

event - the event to push

push

public void push(Event event,
        int priority)

Pushes the given event to the bus, but only notifies those with a priority flag greater than or equal to the given priority. Note that the default priority is EventPriority.NORMAL (0).

Parameters:

event - the event to push

priority - the minimum event priority

See Also:

push(Event), EventPriority

registerMethod

protected void registerMethod(Object o,
                  Method m,
                  int priority,
                  boolean vetoable)

Registers the given method to the event bus. The object is assumed to be of the class that contains the given method.

The method parameters are checked and added to the event queue corresponding to the Event used as the first method parameter. In other words, if passed a reference to the following method:

public void xyzHandler(XYZEvent event) { ... }

... xyzHandler will be added to the event queue for XYZEvent assuming that XYZEvent extends Event and an event queue has been created for that event type.

Parameters:

o - an instance of the class containing the method m

m - the method to register

priority - the event priority

vetoable - vetoable flag

register

public void register(Object o)

Attempts to register all methods of the given object annotated with EventHandler to receive events from this bus. Only methods that are annotated with @EventHandler and accept a single parameter of an event type emitted from this bus (that is, previously added with add(java.lang.Class)) will be registered.

The EventScanMode annotation may be used to control the behavior and degree of scanning. By default the scan mode is EventScanType.FAST and will scan all public methods for the EventHandler annotation, including methods inherited from some superclass. However, private fields will not be scanned.

EventScanType.EXTENDED additionally scans and registers private methods defined directly in the given object, but does not scan private fields in superclasses. This incurs a higher runtime cost at registration time as more methods are scanned.

The final scanning type, EventScanType.FULL, scans all public methods (as with the FAST type), direct private members (as with EXTENDED), and private members defined in any superclass. This will incur the highest runtime cost, but will preserve any event-related functionality.

Parameters:

o - the object to process

See Also:

EventBus#registerMethod(Object, Method, int)

deregister

public void deregister(Object o)

Removes the given object from all event queues that it may be a member of. The object will immediately stop receiving events from this EventBus.

Parameters:

o - the object to remove