Package org.jgrapes.core

Class Event<T>

java.lang.Object
org.jgrapes.core.internal.EventBase<T>
org.jgrapes.core.Event<T>
Type Parameters:
T - the result type of the event. Use Void if handling the event does not produce a result
All Implemented Interfaces:
Future<T>, Associator, Eligible
Direct Known Subclasses:
ActionEvent, Attached, Close, Closed, CompletionEvent, ConfigurationUpdate, DataInput, Detached, DiscardSession, Error, FileChanged, HalfClosed, Handler.NoEvent, IOEvent, KeyValueStoreQuery, KeyValueStoreUpdate, MailFoldersUpdated, MessageReceived, NamedEvent, NioRegistration, Opened, OpenFile, Opening, OpenMailConnection, OpenSocketConnection, Purge, SendMailMessage, Start, StartProcess, Stop, UpdateMailFolders, Upgraded, WatchFile
public class Event<T> extends EventBase<T>
This class is the base class for all events.

By default (i.e. as implemented by this class), the event’s kind is represented by its Java class and the eligibility is based on the “is a” relationship between classes. An event is eligible if its class is equal to or a super class of the class used as criterion. This default behavior can be changed by overriding the methods from Eligible. See NamedEvent as an example.

  • Constructor Details

    • Event

      public Event(Channel... channels)
      Creates a new event.

      Passing channels is equivalent to first creating the event and then calling setChannels(Channel...) with the given channels.

      Parameters:
      channels - the channels to set

  • Method Details

    • defaultCriterion

      public Object defaultCriterion()
      Returns the class of this event as representation of its kind.
      Returns:
      the class of this event
      See Also:

    • isEligibleFor

      public boolean isEligibleFor(Object criterion)
      Returns true if the criterion is of the same class or a base class of this event’s class.
      Parameters:
      criterion - the criterion
      Returns:
      true if this meets the criterion
      See Also:

    • processedBy

      public Optional<EventPipeline> processedBy()
      Return the event pipeline that currently processes the event (if any).
      Overrides:
      processedBy in class EventBase<T>
      Returns:
      the event pipeline if the event is being processed

    • handlingError

      protected void handlingError(EventPipeline eventProcessor, Throwable throwable)
      Implements the default behavior for handling events thrown by a handler.

      Fires a handling error event for this event and the given throwable.

      Specified by:
      handlingError in class EventBase<T>
      Parameters:
      eventProcessor - the manager that has invoked the handler
      throwable - the exception that has been thrown by the handler
      See Also:

    • setChannels

      public Event<T> setChannels(Channel... channels)
      Sets the channels that the event is fired on if no channels are specified explicitly when firing the event (see Manager.fire(Event, Channel...)).
      Parameters:
      channels - the channels to set
      Returns:
      the object for easy chaining
      Throws:
      IllegalStateException - if the method is called after this event has been fired

    • channels

      public Channel[] channels()
      Returns the channels associated with the event.

      Before an event has been fired, this returns the channels set with setChannels(Channel[]). After an event has been fired, this returns the channels that the event has effectively been fired on (see Manager.fire(Event, Channel...)).

      Specified by:
      channels in class EventBase<T>
      Returns:
      the channels (never null, but may be empty)

    • channels

      public <C> C[] channels(Class<C> type)
      Returns the subset of channels that are assignable to the given type.
      Type Parameters:
      C - the given type’s class
      Parameters:
      type - the class to look for
      Returns:
      the filtered channels
      See Also:

    • forChannels

      public <E extends EventBase<?>, C extends Channel> void forChannels(Class<C> type, BiConsumer<E,C> handler)
      Execute the given handler for all channels of the given type.
      Type Parameters:
      E - the type of the event
      C - the type of the channel
      Parameters:
      type - the channel type
      handler - the handler

    • completionEvents

      public Set<Event<?>> completionEvents()
      Returns the events to be thrown when this event has completed (see isDone()).
      Returns:
      the completed events

    • addCompletionEvent

      public Event<T> addCompletionEvent(Event<?> completionEvent)
      Adds the given event to the events to be thrown when this event has completed (see Future.isDone()).

      Such an event is called a “completion event”.

      Completion events are considered to be caused by the event that caused the completed event. If an event e1 caused an event e2 which has a completion event e2c, e1 is only put in state completed when e2c has been handled.

      Completion events are handled by the same EventProcessor as the event that has been completed.

      Specified by:
      addCompletionEvent in class EventBase<T>
      Parameters:
      completionEvent - the completion event to add
      Returns:
      the object for easy chaining
      See Also:

    • setRequiresResult

      public Event<T> setRequiresResult(boolean value)
      Description copied from class: EventBase
      See setRequiresResult(boolean).
      Overrides:
      setRequiresResult in class EventBase<T>

    • isDone

      public boolean isDone()
      Check if this event has completed.

      An event is completed if

      • all its handlers have been invoked (or the event has been stopped or cancelled),
      • all events caused by it have completed,
      • no CompletionLocks remain, and
      • a result has been set (only required if setRequiresResult(boolean) has been called with true).
      Returns:
      the completed state

    • handled

      protected void handled()
      Invoked after all handlers for the event have been executed.

      May be overridden by derived classes to cause some immediate effect (instead of e.g. waiting for the completion event). The default implementation does nothing. This method is invoked by the event handler thread and must not block.

      Specified by:
      handled in class EventBase<T>

    • suspendHandling

      public void suspendHandling()
      Suspend the invocation of the remaining handlers for this event.

      May only be called in a handler for the event. Must be balanced by an invocation of EventBase.resumeHandling().

      Overrides:
      suspendHandling in class EventBase<T>

    • suspendHandling

      public void suspendHandling(Runnable whenResumed)
      Suspend the invocation of the remaining handlers for this event.

      May only be called in a handler for the event. Must be balanced by an invocation of EventBase.resumeHandling().

      Overrides:
      suspendHandling in class EventBase<T>
      Parameters:
      whenResumed - some function to be executed when handling is resumed

    • resumeHandling

      public void resumeHandling()
      Resume the invocation of handlers for this event.
      Overrides:
      resumeHandling in class EventBase<T>
      See Also:

    • stop

      public Event<T> stop()
      Can be called during the execution of an event handler to indicate that the event should not be processed further.

      All remaining handlers for this event will be skipped.

      Returns:
      the object for easy chaining

    • isStopped

      public boolean isStopped()
      Returns true if stop() has been called.
      Specified by:
      isStopped in class EventBase<T>
      Returns:
      the stopped state

    • cancel

      public boolean cancel(boolean mayInterruptIfRunning)
      Prevents the invocation of further handlers (like stop() and (in addition) the invocation of any added completed events.
      Parameters:
      mayInterruptIfRunning - ignored
      Returns:
      false if the event has already been completed
      See Also:

    • isCancelled

      public boolean isCancelled()

    • setResult

      public Event<T> setResult(T result)
      Sets the result of handling this event.

      If this method is invoked more then once, the various results are collected in a list. This can happen if the event is handled by several components.

      Parameters:
      result - the result to set
      Returns:
      the object for easy chaining

    • currentResults

      protected List<T> currentResults()
      Allows access to the intermediate result before the completion of the event.
      Specified by:
      currentResults in class EventBase<T>
      Returns:
      the intermediate results (which may be an empty list)

    • tieTo

      public Event<T> tieTo(Event<T> other)
      Tie the result of this event to the result of the other event.

      Changes of either event’s results will subsequently be applied to both events.

      This is useful when an event is replaced by another event during handling like: fire((new Event()).tieTo(oldEvent.stop()))

      Parameters:
      other - the event to tie to
      Returns:
      the object for easy chaining

    • get

      public T get() throws InterruptedException
      Waits for the event to be completed (see isDone()) and returns the first (or only) result.
      Throws:
      InterruptedException
      See Also:

    • get

      public T get(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException
      Causes the invoking thread to wait until the processing of the event has been completed (see isDone()) or the given timeout has expired and returns the first (or only) result.
      Returns:
      the result
      Throws:
      InterruptedException
      TimeoutException
      See Also:

    • results

      public List<T> results() throws InterruptedException
      Waits for the event to be completed (see isDone()) and returns the list of results (which may be empty if the event’s result type is Void).
      Returns:
      the results
      Throws:
      InterruptedException
      See Also:

    • results

      public List<T> results(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException
      Causes the invoking thread to wait until the processing of the event has been completed (see isDone()) or given timeout has expired and returns the list of results (which may be empty if the event’s result type is Void).
      Returns:
      the results
      Throws:
      InterruptedException
      TimeoutException
      See Also:

    • setAssociated

      public <A extends Associator> A setAssociated(Object by, Object with)
      Description copied from interface: Associator
      Establishes a “named” association to an associated object.

      Note that anything that represents an id can be used as value for parameter name, it does not necessarily have to be a string.

      Passing null as parameter with clears the association.

      Type Parameters:
      A - the associator’s type
      Parameters:
      by - the “name”
      with - the object to be associated
      Returns:
      the sub channel for easy chaining

    • associated

      public <V> Optional<V> associated(Object by, Class<V> type)
      Description copied from interface: Associator
      Retrieves the associated object following the association with the given “name”.

      This general version of the method supports the retrieval of values of arbitrary types associated by any “name” types.

      Type Parameters:
      V - the type of the value to be retrieved
      Parameters:
      by - the “name”
      type - the type of the value to be retrieved
      Returns:
      the associate with the given type, if any

    • toString

      public String toString()
      Overrides:
      toString in class Object