de.aristaflow.adept2.model.events.handler

Interface EventHandler

All Known Subinterfaces:

ActivityEventHandler, SharingSource<T>

All Known Implementing Classes:

AbstractActivityEventHandler, AbstractEventHandler, AbstractSharingActEventSource, FileEventActivityHandler, FileMarkHandler, InstanceStartEventHandler, InstanceStartEventHandler, MailEventActivityHandler, MailFlagHandler, MarkInstanceStartEventHandler

public interface EventHandler

An EventHandler listens to an event and processes it as soon as the event occurs. Event handlers usually can only process specific events. Therefore they are registered at specific event sources for specific event types. There may be several event handlers registered at a event source. To improve event processing, event handling may take place concurrently, that is several registered event handler receive and handle the same event at once. This requires the event handler to process appropriately and the event itself to be concurrently accessible. An event handler can be exclusive which prevents concurrent processing and uses sequential processing instead.
Handling events may render the events non-usable, for instance the data of the event can only be used once or the data is changed while handling. Such a handler is a consuming handler. Obviously a consuming handler is also an exclusive handler. When consuming an event, the handler needs to indicate this to the following event handler. Otherwise they may not need to detect that the data of the event has been changed.

Each event handler has an ID which uniquely (with respect to an event manager) identifies this handler. Usually an event handler is loaded as plugin of an event manager. In this case the handler ID should correspond to the simple instance name of the plugin.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
java.lang.String	getID() Gets the ID of this event handler.
boolean	handleEvent(Event event, boolean consumed) This method actually processes an event.
boolean	isConsuming() Gets whether this event handler is consuming and therefore may change or consume an event while processing it.
boolean	isExclusive() Gets whether this event handler is exclusive and thus no concurrent event handling should take place while this handler is processing an event.
boolean	isInterruptible() Whether this event handler can be interrupted while handling an event.

Method Detail

getID

java.lang.String getID()

Gets the ID of this event handler. This uniquely identifies the handler with respect to the corresponding event manager. If the event handler is loaded as plugin of the event manager, the ID should correspond to the simple plugin instance name.

Returns:

The ID of this event handler which uniquely identifies the handler with respect to the corresponding event manager.

isExclusive

boolean isExclusive()

Gets whether this event handler is exclusive and thus no concurrent event handling should take place while this handler is processing an event.
In case of a consuming handler, exclusive handling is always implicitly presumed.

Returns:

Whether this event handler is exclusive and thus no concurrent event handling should take place while this handler is processing an event.

isConsuming

boolean isConsuming()

Gets whether this event handler is consuming and therefore may change or consume an event while processing it. This does not indicate that all events will be consumed when handled.
A consuming handler is always exclusive.

Returns:

Whether this event handler is consuming and thus may change or consume an event while processing it.

isInterruptible

boolean isInterruptible()

Whether this event handler can be interrupted while handling an event. If so, it must expect an interrupt any time. If not, it has to be aware that the event may have been cancelled while handling.
This must not change at any time.

Returns:

Whether this event handler can be interrupted while handling an event.

handleEvent

boolean handleEvent(Event event,
                    boolean consumed)
             throws EventHandlingException

This method actually processes an event. What is done depends on the implementation of the event handler. Some restrictions may apply depending on the produced event. Only events will be received for which the event handler is registered. However, to improve robustness, an event handler should check the event before processing. If it cannot handle the provided event, this method should just return.
Event handling is usually synchronously, that is, this method will only be executed by one thread at a time. If another event of the same type occurs while still handling the previous event, the second event will be suspended until the previous event has been completely handled. There is no need to start a separate thread while handling to improve performance. But it is not forbidden to do so. Handling that takes place in a new thread is not exclusive any more and therefore must not consume the event!

Parameters:

event - The event that occurred and for which this event handler is registered.

consumed - Whether the event has been consumed by a previous event handler.

Returns:

Whether the event has been consumed (that is changed) while handling it. If the event has been consumed before the current handing, it will have to remain consumed (implementations must return true).

Throws:

EventHandlingException - If there have been problems handling the event, an EventHandlingException may be thrown. If this is critical, the event handling for the current event will stop. If it is non-critical, other event handlers will also get the event for handling it.
If event handling fails, the corresponding event handler needs to roll back its changes, especially a consuming event handler.