Package 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, Identifiable, Initializable, Locatable, Logged, HasPluginInfo, RichPlugin, SciJavaPlugin, Prioritized, SciJavaService, Service, Versioned

public class DefaultEventService
extends AbstractService
implements EventService

Default service for publishing and subscribing to SciJava events.

Author:

Curtis Rueden, Grant Harris

Field Summary

Fields

Modifier and Type	Field	Description
static double	PRIORITY	The default event service's priority.

Constructor Summary

Constructors

Constructor	Description
DefaultEventService()

Method Summary

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

Methods inherited from class org.scijava.plugin.AbstractRichPlugin

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

context, getContext, setContext

Methods inherited from interface org.scijava.plugin.HasPluginInfo

getInfo, setInfo

Methods inherited from interface org.scijava.Locatable

getLocation

Methods inherited from interface org.scijava.Prioritized

compareTo, getPriority, setPriority

Methods inherited from interface org.scijava.plugin.RichPlugin

getIdentifier, log

Methods inherited from interface org.scijava.service.Service

registerEventHandlers

Methods inherited from interface org.scijava.Versioned

getVersion

Field Detail

PRIORITY

public static final double PRIORITY

The default event service's priority.

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. ModulesUpdatedEvent is published with EventService.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 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. ModulesUpdatedEvent is published with EventService.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.

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)

subscribe

public void subscribe(EventSubscriber<?> subscriber)

Description copied from interface: EventService

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

Specified by:

subscribe in interface EventService

Parameters:

subscriber - the event subscriber to register

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 Initializable

Specified by:

initialize in interface Service

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