org.scijava.event

Interface EventService

All Superinterfaces:

Comparable<Prioritized>, Contextual, Disposable, HasPluginInfo, Identifiable, Initializable, Locatable, Logged, Prioritized, RichPlugin, SciJavaPlugin, SciJavaService, Service, Versioned

All Known Implementing Classes:

DefaultEventService

public interface EventService
extends SciJavaService

Interface for the event handling service.

Author:

Curtis Rueden, Grant Harris

Method Summary

Modifier and Type	Method and Description
<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").
void	subscribe(EventSubscriber<?> subscriber) Subscribes the given EventSubscriber to its associated event class.
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.plugin.RichPlugin

getIdentifier, log

Methods inherited from interface org.scijava.Contextual

context, getContext, setContext

Methods inherited from interface org.scijava.Prioritized

compareTo, getPriority, setPriority

Methods inherited from interface org.scijava.plugin.HasPluginInfo

getInfo, setInfo

Methods inherited from interface org.scijava.Locatable

getLocation

Methods inherited from interface org.scijava.Versioned

getVersion

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)

subscribe

void subscribe(EventSubscriber<?> subscriber)

Subscribes the given EventSubscriber to its associated event class. Its EventSubscriber.onEvent(E) method will be called whenever an event of the matching type is published.

Important note: The event service does not keep a strong reference to the subscriber! If you use this method, you are also responsible for keeping a reference to the subscriber, or else it is likely to be garbage collected, and thus no longer respond to events as intended. One simple way to force a strong reference to exist is to add it to SciJava's ObjectService via ObjectService.addObject(java.lang.Object).

Parameters:

subscriber - the event subscriber to register

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).