org.scijava.event
Class DefaultEventService

java.lang.Object
  org.scijava.AbstractContextual
      org.scijava.plugin.AbstractRichPlugin
          org.scijava.service.AbstractService
              org.scijava.event.DefaultEventService

All Implemented Interfaces:

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

public class DefaultEventService
extends AbstractService
implements EventService

Default service for publishing and subscribing to SciJava events.

Author:

Curtis Rueden, Grant Harris

Field Summary

static double

PRIORITY The default event service's priority.

Constructor Summary

DefaultEventService()

Method Summary

void	dispose() Performs any needed cleanup of the object's services, in preparation for the object being retired (e.g., to make garbage collection possible).
<E extends SciJavaEvent> List<EventSubscriber<E>>	getSubscribers(Class<E> c) Gets a list of all subscribers to the given event class (and subclasses thereof).
void	initialize() Performs any needed initialization when the service is first loaded.
<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 class org.scijava.service.AbstractService

getContext, registerEventHandlers, setContext, toString

Methods inherited from class org.scijava.plugin.AbstractRichPlugin

compareTo, getInfo, getPriority, setInfo, setPriority

Methods inherited from class org.scijava.AbstractContextual

context

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.scijava.service.Service

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

Field Detail

PRIORITY

public static final double PRIORITY

The default event service's priority.

It is paramount that the event service be created and initialized before other services. Any service created before the event service may not have its event handling methods registered correctly.

Alternative event service implementations that wish to prioritize themselves above this one can still ensure preferential usage via priority = DefaultEventService.PRIORITY + 1 or similar.

See Also:

Constant Field Values

Constructor Detail

DefaultEventService

public DefaultEventService()

Method Detail

publish

public <E extends SciJavaEvent> void publish(E e)

Description copied from interface: EventService

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

Note that with EventService.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. @{code imagej.module.event.ModulesUpdatedEvent} is published with EventService.publish(E).
2. imagej.menu.DefaultMenuService receives the event and handles it, publishing imagej.menu.event.MenusUpdatedEvent in response.
3. A third party that subscribes to both imagej.module.event.ModulesUpdatedEvent and imagej.menu.event.MenusUpdatedEvent will receive the latter before the former.

That said, the behavior of EventService.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 EventService.publish(E) and EventService.publishLater(E) may result in event delivery in an unintuitive order.

Specified by:

publish in interface EventService

publishLater

public <E extends SciJavaEvent> void publishLater(E e)

Description copied from interface: EventService

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 EventService.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. imagej.module.event.ModulesUpdatedEvent is published with EventService.publishLater(E).
2. imagej.menu.DefaultMenuService receives the event and handles it, publishing imagej.menu.event.MenusUpdatedEvent in response.
3. A third party that subscribes to both imagej.module.event.ModulesUpdatedEvent and imagej.menu.event.MenusUpdatedEvent will receive the former first, since it was already queued by the time the latter was published.

Specified by:

publishLater in interface EventService

subscribe

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

Description copied from interface: EventService

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.

Specified by:

subscribe in interface EventService

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

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

Description copied from interface: EventService

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

Specified by:

unsubscribe in interface EventService

getSubscribers

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

Description copied from interface: EventService

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

Specified by:

getSubscribers in interface EventService

initialize

public void initialize()

Description copied from interface: Service

Performs any needed initialization when the service is first loaded.

NB: This method is not intended to be called directly. It is called by the service framework itself (specifically by the ServiceHelper) when initializing the service. It should not be called a second time.

Specified by:

initialize in interface Service

Overrides:

initialize in class AbstractService

dispose

public void dispose()

Description copied from interface: Disposable

Performs any needed cleanup of the object's services, in preparation for the object being retired (e.g., to make garbage collection possible).

Specified by:

dispose in interface Disposable

Overrides:

dispose in class AbstractService