de.aristaflow.adept2.core.eventmanager.common

Class AbstractActivityEventHandler

java.lang.Object

de.aristaflow.adept2.core.eventmanager.common.AbstractEventHandler

de.aristaflow.adept2.core.eventmanager.common.AbstractActivityEventHandler

All Implemented Interfaces:

ActivityEventHandler, EventHandler

Direct Known Subclasses:

FileEventActivityHandler, MailEventActivityHandler

public abstract class AbstractActivityEventHandler
extends AbstractEventHandler
implements ActivityEventHandler

This class provides the basic means for an activity event handler, that is, providing the attributes of an EventHandler as well as declining all signals sent while the handler is executing an activity. Additionally it provides simple data structures for the session contexts of the activities that await an event.

Author:

Ulrich Kreher

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.concurrent.ConcurrentMap<java.lang.String,EBPInstanceReference>	contexts All activities that are currently registered for event handling indexed by the source IDs.
protected ActivityEventManager	eventManager The event manager for communicating with the runtime service.

Fields inherited from class de.aristaflow.adept2.core.eventmanager.common.AbstractEventHandler

consuming, critical, exclusive, id, interruptible, logger

Constructor Summary

Constructors

Constructor and Description
AbstractActivityEventHandler(Registry registry, boolean exclusive, boolean consuming, boolean critical, ActivityEventManager eventManager) Creates a new event handler having the designated ID and the designated flags.
AbstractActivityEventHandler(java.lang.String id, boolean exclusive, boolean consuming, boolean critical, ActivityEventManager eventManager) Creates a new event handler having the designated ID and the designated flags.

Method Summary

Modifier and Type	Method and Description
protected abstract boolean	canHandle(Event event, boolean consumed) Gets whether the designated event can be handled by this (sub-)class.
boolean	close(java.lang.String sessionID) Instructs the activity handler to close the activity that is currently running with the designated session ID.
boolean	handleEvent(Event eve, boolean consumed) This method actually processes an event.
void	init(java.lang.String sourceID, SimpleSessionContext sessionContext) Initialises the handling of an event for the activity identified by the designated session context.
boolean	kill(java.lang.String sessionID) Instructs the activity handler to kill the activity that is currently running with the designated session ID.
protected abstract boolean	processEvent(Event event, ActivityInstance activity, DataContext dataContext) Processes the designated event for the designated activity instance.
void	remove(java.lang.String sourceID) Removes a registered source from this activity event handler.
boolean	reset(java.lang.String sessionID) Instructs the activity handler to reset the activity that is currently running with the designated session ID.
boolean	signal(java.lang.String sessionID, int signal) Signals the designated signal to the activity that is currently running with the designated session ID.
boolean	suspend(java.lang.String sessionID) Instructs the activity handler to suspend the activity that is currently running with the designated session ID.

Methods inherited from class de.aristaflow.adept2.core.eventmanager.common.AbstractEventHandler

getID, isConsuming, isCritical, isExclusive, isInterruptible

Methods inherited from class java.lang.Object

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

Methods inherited from interface de.aristaflow.adept2.model.events.handler.EventHandler

getID, isConsuming, isExclusive, isInterruptible

Field Detail

contexts

protected final java.util.concurrent.ConcurrentMap<java.lang.String,EBPInstanceReference> contexts

All activities that are currently registered for event handling indexed by the source IDs.

eventManager

protected final ActivityEventManager eventManager

The event manager for communicating with the runtime service.

Constructor Detail

AbstractActivityEventHandler

public AbstractActivityEventHandler(java.lang.String id,
                                    boolean exclusive,
                                    boolean consuming,
                                    boolean critical,
                                    ActivityEventManager eventManager)

Creates a new event handler having the designated ID and the designated flags. If the handler is consuming, it will also be exclusive.

Parameters:

id - The ID of this handler (usually the plugin ID).

exclusive - Whether this handler needs to handle events exclusively.

consuming - Whether this handler may consume events. If the handler is consuming, it is also exclusive.

critical - Whether this handler is critical. If the handler is critical, it will also be exclusive.

eventManager - The event manager for communicating with the runtime service.

AbstractActivityEventHandler

public AbstractActivityEventHandler(Registry registry,
                                    boolean exclusive,
                                    boolean consuming,
                                    boolean critical,
                                    ActivityEventManager eventManager)

Creates a new event handler having the designated ID and the designated flags. If the handler is consuming, it will also be exclusive.

Parameters:

registry - The registry to get the ID of this handler (the simple name of the plugin instance).

exclusive - Whether this handler needs to handle events exclusively.

consuming - Whether this handler may consume events. If the handler is consuming, it is also exclusive.

critical - Whether this handler is critical. If the handler is critical, it will also be exclusive.

eventManager - The event manager for communicating with the runtime service.

Method Detail

init

public void init(java.lang.String sourceID,
                 SimpleSessionContext sessionContext)

Description copied from interface: ActivityEventHandler

Initialises the handling of an event for the activity identified by the designated session context. The activity handler thus prepares itself for handling the corresponding event. When handling the event, the handler relates the event to the appropriate activity and provides the required information from the event to the activity. After handling has completed, the handler may expect the activity to be terminated and therefore drop its session context.
This method needs to be synchronised appropriately since this method is called asynchronously.

Specified by:

init in interface ActivityEventHandler

Parameters:

sourceID - The ID of the source that waits for an event of the activity of the designated session context.

sessionContext - The session context for the activity that is to be executed and terminated as soon as the appropriate event is handled.

See Also:

ExecutableComponent.init(de.aristaflow.adept2.model.runtimeenvironment.SessionContext)

canHandle

protected abstract boolean canHandle(Event event,
                                     boolean consumed)

Gets whether the designated event can be handled by this (sub-)class. This should for instance check for the event type as well as whether consumed events can be handled.

Parameters:

event - The event which is about to be handled.

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

processEvent

protected abstract boolean processEvent(Event event,
                                        ActivityInstance activity,
                                        DataContext dataContext)
                                 throws ApplicationEnvironmentException,
                                        ApplicationFailedException

Processes the designated event for the designated activity instance. Usually this requires setting the output parameters in the designated data context appropriately based on the event.

Parameters:

event - The event to be processed.

activity - The activity for which to process event. This also provides the configuration of the activity and also the defined output parameters.

dataContext - The data context to write the values of the output parameters to.

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:

ApplicationEnvironmentException - If the designated activity or the data context do not have the values expected for processing the event, for instance an output parameter is missing.

ApplicationFailedException - If processing the event fails, an ApplicationFailedException will be thrown.

handleEvent

public boolean handleEvent(Event eve,
                           boolean consumed)
                    throws EventHandlingException

Description copied from interface: EventHandler

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!

Specified by:

handleEvent in interface EventHandler

Parameters:

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

remove

public void remove(java.lang.String sourceID)

Description copied from interface: ActivityEventHandler

Removes a registered source from this activity event handler. This is used in case the activity is for some reason discarded. The source ID is that of the registered session context used in ActivityEventHandler.init(String, SimpleSessionContext).
This method will only be called for exceptional cases. Implementations have to take care of removal after a successful event handling themselves.

Specified by:

remove in interface ActivityEventHandler

Parameters:

sourceID - The ID of the source for a registered activity that is to be removed and no event for it should be handled.

reset

public boolean reset(java.lang.String sessionID)

Description copied from interface: ActivityEventHandler

Instructs the activity handler to reset the activity that is currently running with the designated session ID. The session ID is that of the current execution session and usually not the one the activity has been registered with.
Like an ExecutableComponent the activity handler does not need to reset the activity but can react arbitrarily to this request. However, unlike ExecutableComponent, activity event handlers need to be synchronised appropriately since this method is called asynchronously.

Specified by:

reset in interface ActivityEventHandler

Parameters:

sessionID - The ID of the execution session which to close.

Returns:

Whether the activity handler is about to react to this reset request.

See Also:

ExecutableComponent.reset()

signal

public boolean signal(java.lang.String sessionID,
                      int signal)

Description copied from interface: ActivityEventHandler

Signals the designated signal to the activity that is currently running with the designated session ID. The session ID is that of the current execution session and usually not the one the activity has been registered with.
Like an ExecutableComponent the activity handler does not need to signal the activity but can react arbitrarily to this request. However, unlike ExecutableComponent, activity event handlers need to be synchronised appropriately since this method is called asynchronously.

Specified by:

signal in interface ActivityEventHandler

Parameters:

sessionID - The ID of the execution session which to signal.

signal - The code that specifies the type of the signaled event.

Returns:

Whether the activity handler is about to react to this signal request.

See Also:

ExecutableComponent.signal(int)

close

public boolean close(java.lang.String sessionID)

Description copied from interface: ActivityEventHandler

Instructs the activity handler to close the activity that is currently running with the designated session ID. The session ID is that of the current execution session and usually not the one the activity has been registered with.
Like an ExecutableComponent the activity handler does not need to close the activity but can react arbitrarily to this request. However, unlike ExecutableComponent, activity event handlers need to be synchronised appropriately since this method is called asynchronously.

Specified by:

close in interface ActivityEventHandler

Parameters:

sessionID - The ID of the execution session which to close.

Returns:

Whether the activity handler is about to react to this close request.

See Also:

ExecutableComponent.close()

suspend

public boolean suspend(java.lang.String sessionID)

Description copied from interface: ActivityEventHandler

Instructs the activity handler to suspend the activity that is currently running with the designated session ID. The session ID is that of the current execution session and usually not the one the activity has been registered with.
Like an ExecutableComponent the activity handler does not need to suspend the activity but can react arbitrarily to this request. However, unlike ExecutableComponent, activity event handlers need to be synchronised appropriately since this method is called asynchronously.

Specified by:

suspend in interface ActivityEventHandler

Parameters:

sessionID - The ID of the execution session which to close.

Returns:

Whether the activity handler is about to react to this suspend request.

See Also:

ExecutableComponent.suspend()

kill

public boolean kill(java.lang.String sessionID)

Description copied from interface: ActivityEventHandler

Instructs the activity handler to kill the activity that is currently running with the designated session ID. The session ID is that of the current execution session and usually not the one the activity has been registered with.
Like an ExecutableComponent the activity handler does not need to kill the activity but can react arbitrarily to this request. However, unlike ExecutableComponent, activity event handlers need to be synchronised appropriately since this method is called asynchronously.

Specified by:

kill in interface ActivityEventHandler

Parameters:

sessionID - The ID of the execution session which to close.

Returns:

Whether the activity handler is about to react to this kill request.

See Also:

ExecutableComponent.kill()