de.aristaflow.adept2.core.runtimemanager.executionenvironments

Class ExecutionEnvironment

java.lang.Object

de.aristaflow.adept2.core.runtimemanager.executionenvironments.ExecutionEnvironment

All Implemented Interfaces:

ExecutableComponent

Direct Known Subclasses:

IDExecutionEnvironment, NullExecution, SystemExecutionEnvironment

public abstract class ExecutionEnvironment
extends java.lang.Object
implements ExecutableComponent

This abstract execution environment is for easy development of new execution environments. It provides default implementations for most of the methods of ExecutableComponent: state changes are refused or ignored except run() which has to be provided by subclasses. Transaction handling is also refused.
Additionally this execution environment provides methods for retrieval of input parameter types and values as well as writing the values of output parameters. Parameters of user-defined data type are mapped to Objects.

For a convenient access to the activity instance and the data context actData should be used. Do not use it before calling init(SessionContext) on this class. If a subclass needs methods from ActivityData to be overridden, be careful to also override createActivityData(ActivityInstance, DataContext, Logger).

Author:

Markus Lauer, Ulrich Kreher

Nested Class Summary

Nested classes/interfaces inherited from interface de.aristaflow.adept2.model.runtimeenvironment.ExecutableComponent

ExecutableComponent.Signals

Field Summary

Fields

Modifier and Type	Field and Description
protected ActivityData	actData The activity instance and data context wrapper for this execution.
protected ActivityInstance	activityInstance The activity (instance) which is encapsulated by this execution environment.
protected ActivityInstance	localisedActInst The localised activity (instance) which is encapsulated by this execution environment.
protected java.util.logging.Logger	logger The logger for execution environments.
protected SessionContext	sessionContext The session context for this execution.
protected static java.lang.String	SUSPEND_SAVEPOINT The name of the savepoint that will be used to store the state of the environment when suspending.

Fields inherited from interface de.aristaflow.adept2.model.runtimeenvironment.ExecutableComponent

CONF_DATA_DIRECTORY, CONF_LIB_DIRECTORY, CONF_LOG_DIRECTORY, UNLOADING_CLASS_METHOD

Constructor Summary

Constructors

Constructor and Description
ExecutionEnvironment(ActivityInstance activityInstance) Creates a new ExecutionEnvironment for the designated activity.

Method Summary

Modifier and Type	Method and Description
boolean	close() Returns false - overwrite this method to support closing.
void	commit() Throws an IsNotSupportedException - overwrite this method to support committing.
protected ActivityData	createActivityData(ActivityInstance actInst, DataContext dataCont, java.util.logging.Logger adLogger) Creates new activity data based on the designated information.
protected java.io.Serializable	getApplicationState() Gets the application state stored for last savepoint as object.
protected java.io.Serializable	getApplicationState(java.lang.String savepoint) Gets the application state stored for the designated savepoint as object.
protected byte[]	getRawApplicationState() Gets the raw application state stored for last savepoint.
protected byte[]	getRawApplicationState(java.lang.String savepoint) Gets the raw application state stored for designated savepoint as object.
void	init(SessionContext sessContext) Initialises this ExecutionEnvironment by setting the session context, the logger field and the activity data.
void	initResume(java.lang.String savepointId, SessionContext sessContext) Does nothing - overwrite this method to support resuming.
boolean	kill() Returns false - overwrite this method to support killing.
Vote	prepareCommit() Throws an IsNotSupportedException - overwrite this method to support Two-phase-commit.
protected <T extends GUIContext> T	requireGUIContext(java.lang.Class<T> guiContextType) Returns the required GUI context or throws an exception if it is not available.
boolean	reset() Returns false - overwrite this method to support reset.
boolean	rollback() Throws an IsNotSupportedException - overwrite this method to support rolling back.
abstract void	run() Resembles Runnable.run() except that this method is expected to throw exceptions indicating that the environment was unexpected or an internal failure occurred.
protected void	setApplicationState(java.io.Serializable appState) Stores the application state as serialised Java object for the next savepoint.
protected void	setApplicationState(java.lang.String savepoint, java.io.Serializable appState) Stores the application state for the designated savepoint as object.
protected void	setRawApplicationState(byte[] appState) Stores the raw application state for the next savepoint.
protected void	setRawApplicationState(java.lang.String savepoint, byte[] appState) Stores the raw application state for the designated savepoint.
boolean	signal(int signal) Returns false - overwrite this method to support signalling.
boolean	suspend() Returns false - overwrite this method to support suspending.

Methods inherited from class java.lang.Object

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

Field Detail

SUSPEND_SAVEPOINT

protected static final java.lang.String SUSPEND_SAVEPOINT

The name of the savepoint that will be used to store the state of the environment when suspending.

See Also:

Constant Field Values

logger

protected java.util.logging.Logger logger

The logger for execution environments. It is protected for extensibility. Note that this will not be set until initialised.

activityInstance

protected final ActivityInstance activityInstance

The activity (instance) which is encapsulated by this execution environment.

localisedActInst

protected ActivityInstance localisedActInst

The localised activity (instance) which is encapsulated by this execution environment.

sessionContext

protected SessionContext sessionContext

The session context for this execution.

actData

protected ActivityData actData

The activity instance and data context wrapper for this execution.

Constructor Detail

ExecutionEnvironment

public ExecutionEnvironment(ActivityInstance activityInstance)

Creates a new ExecutionEnvironment for the designated activity. The constructor just sets the activity and the logger.

Parameters:

activityInstance - The activity instance for this ExecutionEnvironment.

Method Detail

init

public void init(SessionContext sessContext)

Initialises this ExecutionEnvironment by setting the session context, the logger field and the activity data. These fields are not available before! Therefore you should call this method very early when initialising or initialising for resume.

Initialises and prepares the execution of the application and provides all necessary data which maybe necessary for this. This method or ExecutableComponent.initResume(String, SessionContext) is only called once in the lifetime of an executable component. One of these methods is guaranteed to be called before calling any other method.

When leaving this method the execution has to be completely prepared. This includes for instance the availability of the GUI in the GUI context, which is necessary for Web applications with HTML-UI.

Specified by:

init in interface ExecutableComponent

Parameters:

sessContext - The session context to associate with this ExecutionEnvironment.

initResume

public void initResume(java.lang.String savepointId,
                       SessionContext sessContext)

Does nothing - overwrite this method to support resuming.
Note that this does neither set the session context nor the logger.

Initialises and prepares the resuming of the application and provides all necessary data which maybe necessary for this. This method or ExecutableComponent.init(SessionContext) is only called once in the lifetime of an executable component. One of these methods is guaranteed to be called before calling any other method.

When leaving this method the execution has to be completely prepared for resuming. That is, the state of the application has to be restored. This includes the GUI.

Usually this method will delegate also call ExecutableComponent.init(SessionContext).

Specified by:

initResume in interface ExecutableComponent

Parameters:

savepointId - The identifier of the savepoint at which the application should resume. This must not be null, but it may be the empty string.

sessContext - The session context in which the component is to be executed.

createActivityData

protected ActivityData createActivityData(ActivityInstance actInst,
                                          DataContext dataCont,
                                          java.util.logging.Logger adLogger)

Creates new activity data based on the designated information. Override this factory method if you need to override ActivityData. This method will usually be called just once in an early initialisation phase of an execution environment.

Parameters:

actInst - The activity (instance) which is encapsulated by this execution environment.

dataCont - The context providing the activity data.

adLogger - The logger for logging messages having additional information in case of problems when handling parameters or configuration values.

Returns:

The newly created activity data.

run

public abstract void run()

Description copied from interface: ExecutableComponent

Resembles Runnable.run() except that this method is expected to throw exceptions indicating that the environment was unexpected or an internal failure occurred. Both exceptions as well as RuntimeException will set the corresponding process activity to FAILED.

Specified by:

run in interface ExecutableComponent

close

public boolean close()

Returns false - overwrite this method to support closing.

Instructs the component to terminate. Within this method the component should deallocate all allocated resources.

Specified by:

close in interface ExecutableComponent

Returns:

false

reset

public boolean reset()

Returns false - overwrite this method to support reset.

Instructs the component to reset. This is quite similar to ExecutableComponent.kill() but the application does not fail but terminate normally (by calling RuntimeEnvironment.applicationReset(). The component will be re-initialised and executed again later.

Specified by:

reset in interface ExecutableComponent

Returns:

false

signal

public boolean signal(int signal)

Returns false - overwrite this method to support signalling.

Signals an event to the application.

Specified by:

signal in interface ExecutableComponent

Parameters:

signal - Ignored.

Returns:

false

See Also:

for possible signals. Usually the ones that have corresponding methods, e. g. {@link Signals#SUSPEND} or {@link Signals#CLOSE}, will not be signaled via this method.

suspend

public boolean suspend()

Returns false - overwrite this method to support suspending.

Instructs the component to store its internal state to the data context and to terminate at once. The application should be able to continue its job later when resuming.

Specified by:

suspend in interface ExecutableComponent

Returns:

false

kill

public boolean kill()

Returns false - overwrite this method to support killing.

Enforces the application to abort its execution at once. In the case of running a internal transaction application should abort the transaction and should rollback. Within this method the component should deallocate all allocated resources.

Specified by:

kill in interface ExecutableComponent

Returns:

false

prepareCommit

public Vote prepareCommit()
                   throws IsNotSupportedException

Throws an IsNotSupportedException - overwrite this method to support Two-phase-commit.

Instructs the component to vote for Commit or Abort of the distributed transaction it participates in and to prepare a commit.

Specified by:

prepareCommit in interface ExecutableComponent

Returns:

Nothing, since an IsNotSupportedException is always thrown.

Throws:

IsNotSupportedException - This exception is always thrown.

commit

public void commit()
            throws IsNotSupportedException

Throws an IsNotSupportedException - overwrite this method to support committing.

Instructs the component to commit its modifications not managed by ADEPT.

Specified by:

commit in interface ExecutableComponent

Throws:

IsNotSupportedException - This exception is always thrown.

rollback

public boolean rollback()
                 throws IsNotSupportedException

Throws an IsNotSupportedException - overwrite this method to support rolling back.

Instructs the component to undo all its modifications done within the current transaction. This method has to be implemented in case the application is resettable.

Specified by:

rollback in interface ExecutableComponent

Returns:

Nothing, since an IsNotSupportedException is always thrown.

Throws:

IsNotSupportedException - This exception is always thrown.

getApplicationState

protected java.io.Serializable getApplicationState()
                                            throws java.io.IOException

Gets the application state stored for last savepoint as object. Note that this will only work, if you used setApplicationState(Serializable) or setApplicationState(String, Serializable) for storing the application state.

Returns:

An object representing the application state for the last savepoint. This will be null in case no application state has been stored for the last savepoint (and of course if null has been explicitly stored for the last savepoint).

Throws:

java.io.IOException - If there are problems deserialising the application state, an IOException will be thrown.

getRawApplicationState

protected byte[] getRawApplicationState()

Gets the raw application state stored for last savepoint. Note that this will only work, if you used setRawApplicationState(byte[]) or setRawApplicationState(String, byte[]) for storing the application state.

Returns:

The raw application state for the last savepoint. This will be null in case no application state has been stored for the last savepoint (and of course if null has been explicitly stored for the last savepoint).

getApplicationState

protected java.io.Serializable getApplicationState(java.lang.String savepoint)
                                            throws java.io.IOException

Gets the application state stored for the designated savepoint as object. Note that this will only work, if you used setApplicationState(String, Serializable) for storing the application state.

Parameters:

savepoint - The name of the savepoint for which to retrieve the application state. This allows for several different application states.

Returns:

An object representing the application state for the designated savepoint. This will be null in case no application state has been stored for the designated savepoint (and of course if null has been explicitly stored for the designated savepoint).

Throws:

java.io.IOException - If there are problems deserialising the application state, an IOException will be thrown.

getRawApplicationState

protected byte[] getRawApplicationState(java.lang.String savepoint)

Gets the raw application state stored for designated savepoint as object. Note that this will only work, if you used setRawApplicationState(byte[]) or setRawApplicationState(String, byte[]) for storing the application state.

Parameters:

savepoint - The name of the savepoint for which to retrieve the raw application state. This allows for several different application states.

Returns:

The raw application state for the designated savepoint. This will be null in case no application state has been stored for the designated savepoint (and of course if null has been explicitly stored for the designated savepoint).

setApplicationState

protected void setApplicationState(java.io.Serializable appState)
                            throws java.io.IOException

Stores the application state as serialised Java object for the next savepoint. Use null to remove the state for the next savepoint.

Parameters:

appState - An object representing the application state for the next savepoint. Use null to remove it for the next savepoint.

Throws:

java.io.IOException - If there are problems serialising the application state, an IOException will be thrown.

See Also:

RuntimeEnvironment.setApplicationState(byte[])

setRawApplicationState

protected void setRawApplicationState(byte[] appState)

Stores the raw application state for the next savepoint. Use null to remove the state for the next savepoint.

Parameters:

appState - The raw application state for the next savepoint. Use null to remove it for the next savepoint.

See Also:

RuntimeEnvironment.setApplicationState(byte[])

setApplicationState

protected void setApplicationState(java.lang.String savepoint,
                                   java.io.Serializable appState)
                            throws java.io.IOException

Stores the application state for the designated savepoint as object. Use null to remove the designated savepoint. The savepoint will not be flushed.

Parameters:

savepoint - The savepoint for which to store the application state. This allows for several different application states.

appState - An object representing the application state for the designated savepoint. Use null to remove the designated savepoint.

Throws:

java.io.IOException - If there are problems serialising the application state, an IOException will be thrown.

See Also:

RuntimeEnvironment.setApplicationState(byte[]), RuntimeEnvironment.setSavepoint(String, boolean)

setRawApplicationState

protected void setRawApplicationState(java.lang.String savepoint,
                                      byte[] appState)

Stores the raw application state for the designated savepoint. Use null to remove the state for the designated savepoint. The savepoint will not be flushed.

Parameters:

savepoint - The savepoint for which to store the application state. This allows for several different application states.

appState - The raw application state for the designated savepoint. Use null to remove it for the designated savepoint.

See Also:

RuntimeEnvironment.setApplicationState(byte[])

requireGUIContext

protected <T extends GUIContext> T requireGUIContext(java.lang.Class<T> guiContextType)

Returns the required GUI context or throws an exception if it is not available.

Type Parameters:

T - the type of the required GUI context

Parameters:

guiContextType - the type of the required GUI context

Returns:

the required GUI context if available

Throws:

ApplicationEnvironmentException - if the required GUI context is not available