org.scijava.event
Interface EventService

All Superinterfaces:

Comparable<Prioritized>, Contextual, Disposable, HasPluginInfo, Prioritized, RichPlugin, SciJavaPlugin, SciJavaService, Service

All Known Implementing Classes:

DefaultEventService

public interface EventService
extends SciJavaService

Interface for the event handling service.

Author:

Curtis Rueden, Grant Harris

Method Summary

<E extends SciJavaEvent> List<EventSubscriber<E>>	getSubscribers(Class<E> c) Gets a list of all subscribers to the given event class (and subclasses thereof).
<E extends SciJavaEvent> void	publish(E e) Publishes the given event immediately, reporting it to all subscribers.
<E extends SciJavaEvent> void	publishLater(E e) Queues the given event for publication, typically on a separate thread (called the "event dispatch thread").
List<EventSubscriber<?>>	subscribe(Object o) Subscribes all of the given object's @EventHandler annotated methods.
void	unsubscribe(Collection<EventSubscriber<?>> subscribers) Removes all the given subscribers; they will no longer be notified when events are published.

Methods inherited from interface org.scijava.service.Service

initialize, registerEventHandlers

Methods inherited from interface org.scijava.Contextual

context, getContext, setContext

Methods inherited from interface org.scijava.Prioritized

getPriority, setPriority

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface org.scijava.plugin.HasPluginInfo

getInfo, setInfo

Methods inherited from interface org.scijava.Disposable

dispose

Method Detail

publish

<E extends SciJavaEvent> void publish(E e)

Publishes the given event immediately, reporting it to all subscribers. Does not return until all subscribers have handled the event.

Note that with publish(E), in the case of multiple events published in a chain to multiple subscribers, the delivery order will resemble that of a stack. For example:

1. ModulesUpdatedEvent is published with publish(E).
2. DefaultMenuService receives the event and handles it, publishing MenusUpdatedEvent in response.
3. A third party that subscribes to both ModulesUpdatedEvent and MenusUpdatedEvent will receive the latter before the former.

That said, the behavior of publish(E) depends on the thread from which it is called: if called from a thread identified as a dispatch thread by ThreadService.isDispatchThread(), it will publish immediately; otherwise, it will be queued for publication on a dispatch thread, and block the calling thread until publication is complete. This means that a chain of events published with a mixture of publish(E) and publishLater(E) may result in event delivery in an unintuitive order.

publishLater

<E extends SciJavaEvent> void publishLater(E e)

Queues the given event for publication, typically on a separate thread (called the "event dispatch thread"). This method returns immediately, before subscribers have fully received the event.

Note that with publishLater(E), in the case of multiple events published in a chain to multiple subscribers, the delivery order will resemble that of a queue. For example:

1. ModulesUpdatedEvent is published with publishLater(E).
2. DefaultMenuService receives the event and handles it, publishing MenusUpdatedEvent in response.
3. A third party that subscribes to both ModulesUpdatedEvent and MenusUpdatedEvent will receive the former first, since it was already queued by the time the latter was published.

subscribe

List<EventSubscriber<?>> subscribe(Object o)

Subscribes all of the given object's @EventHandler annotated methods.

This allows a single class to subscribe to multiple types of events by implementing multiple event handling methods and annotating each one with the EventHandler annotation.

Note that it is not necessary to store a copy of the event subscribers (because the event service is expected to hold a weak mapping between the event handler object and the subscribers) unless the subscribers need to be unsubscribed explicitly.

Most users will want to extend AbstractContextual, or call Context.inject(Object), instead of subscribing to the event service explicitly.

Parameters:

o - the event handler object containing the EventHandler annotated methods

Returns:

The list of newly created EventSubscribers, weakly subscribed to the event service.

See Also:

AbstractContextual, Context.inject(Object)

unsubscribe

void unsubscribe(Collection<EventSubscriber<?>> subscribers)

Removes all the given subscribers; they will no longer be notified when events are published.

getSubscribers

<E extends SciJavaEvent> List<EventSubscriber<E>> getSubscribers(Class<E> c)

Gets a list of all subscribers to the given event class (and subclasses thereof).