Package org.scijava.event

Interface EventService

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