de.aristaflow.adept2.model.runtimeenvironment

Interface RuntimeEnvironment

public interface RuntimeEnvironment

This API defines methods by which applications can signal their termination, respond to external control messages and manage the application state when suspending and resuming.

Author:

Markus Lauer, Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
void	applicationClosed() Called by the application to tell the runtime manager about its successful termination.
void	applicationReset() Notifies the runtime manager that the application has been terminated and wants to be reset that is activated again and the current and previous executions have to be completely dropped.
void	applicationResetTo(java.lang.String savepoint) Notifies the runtime manager that the application has been terminated and wants to be reset to the designated savepoint.
void	applicationResetToPreviousSavepoint() Notifies the runtime manager that the application has been terminated and wants to be reset to the last savepoint before this application started.
void	applicationSignalled(int signal) Enables the application to signal a special event to the runtime manager.
void	applicationSuspended() Tells the runtime manager about the application's suspension.
void	applicationSuspended(long timeout) Notifies the runtime manager that the application has been suspended and wants to be resumed after the designated time.
boolean	dispatch() Analyses the messages sent by the runtime manager and call the appropriate methods specified in the ExecutableComponent interface.
byte[]	getApplicationState(java.lang.String savepoint) Returns a byte array in which all the application state relevant information is stored or null in case the application has stored null or an empty array as state.
DriverManager	getDriverManager() Gets a reference to a DriverManager encapsulating the normal JDBC-driver manager.
java.lang.String	getLastSavepoint() Returns the ID of the last savepoint the application can restart at.
ActivityInstance	getLocalisedActivityInstance() Gets the activity instance localised with respect to the rich agent.
java.util.logging.Logger	getLogger() Gets the logger which should be used for all log messages of the ExecutableComponent.
void	setApplicationState(byte[] applicationState) Enables the application to store its internal state to the system.
void	setSavepoint(java.lang.String savepoint, boolean flush) Assigns the designated savepoint to the current state of the data, that is application state and data context.

Method Detail

getLogger

java.util.logging.Logger getLogger()

Gets the logger which should be used for all log messages of the ExecutableComponent. The AristaFlow-platform provides adequate handlers for this logger.

Returns:

A logger to be used for all log messages of the ExecutableComponent.

getDriverManager

DriverManager getDriverManager()

Gets a reference to a DriverManager encapsulating the normal JDBC-driver manager. This is needed to circumvent the memory leak in the driver manager which stores each calling class including the classloader forever.
It is absolutely necessary not to call the driver manager directly! Otherwise memory leaks may occur which may cause the current JVM to die!

Returns:

A driver manager wrapper to encapsulate the normal JDBC-driver manager. Always use the one returned by this method!

getLocalisedActivityInstance

ActivityInstance getLocalisedActivityInstance()

Gets the activity instance localised with respect to the rich agent.

Returns:

The activity instance localised with respect to the rich agent.

dispatch

boolean dispatch()

Analyses the messages sent by the runtime manager and call the appropriate methods specified in the ExecutableComponent interface. This method must be called regularly by the application main thread (the executableComponent of the run-method specified in the ExecutableComponent interface) in order to assure the behaviour expected by the ADEPT system. Important remark: Not reacting to the sent messages causes the (failed) termination of the application! The call by other threads than the main thread raises an InvalidExecutorThreadException- exception. This prevents the component developer from the must of the thread safe implementation of the methods specified in the ExecutableComponent interface. The method returns true if the signal has been accepted by the application which usually indicates that the termination of the application is expected. In that case the run-method must be terminated as soon as possible.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

Returns:

True: The application has accepted the signal which usually indicates that it needs to terminate (depending on the received signal). False: The signal has been declined and the application will go on with its normal task.

getApplicationState

byte[] getApplicationState(java.lang.String savepoint)

Returns a byte array in which all the application state relevant information is stored or null in case the application has stored null or an empty array as state.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

Use de.aristaflow.adept2.model.globals.CommonConstants#VIEW_ONLY_SAVEPOINT to store additional data required for view-only execution that is not part of the process context.

Parameters:

savepoint - Identifies the requested session state. Use null to get the current session state that has no savepoint yet.

Returns:

Application related session content or null if no savepoint exists for the designated ID.

getLastSavepoint

java.lang.String getLastSavepoint()

Returns the ID of the last savepoint the application can restart at. Usually the application should use the savepoint ID provided by ExecutableComponent.initResume(String, SessionContext). This will allow to resume the application with an earlier savepoint if the user wants it.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

Returns:

The ID of the savepoint the stored application related content belongs to. If there is no savepoint, that is the application has not been suspended or there is no explicit savepoint, null will be returned.

setApplicationState

void setApplicationState(byte[] applicationState)

Enables the application to store its internal state to the system. This method can be called for preparing the suspension of the application. The passed byte array should contain the current internal state of the application
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

The latest application state that is stored when terminating will be provided for a view-only execution.

Parameters:

applicationState - Byte array that keeps the current internal state of the application.

setSavepoint

void setSavepoint(java.lang.String savepoint,
                  boolean flush)

Assigns the designated savepoint to the current state of the data, that is application state and data context. This may be flushed to the server or just stored intermediately. By flushing the savepoint, the designated application state (if provided) as well as all changes to the data context since the last savepoint (or starting the application) will be sent to the server and thus persisted. If the application suspends shortly afterwards, one should not flush since this will be unnecessary overhead.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

Parameters:

savepoint - The identifier by which the current data state could be retrieved. This must neither be null nor the empty string.

flush - Whether to flush all data since the last savepoint and store it in the data manager.

applicationSuspended

void applicationSuspended()

Tells the runtime manager about the application's suspension.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

applicationSuspended

void applicationSuspended(long timeout)

Notifies the runtime manager that the application has been suspended and wants to be resumed after the designated time.
The time-constraint will be respected as best as possible. However, since Java does not support realtime operations, the time-constraint may be violated marginally. Additionally, the application may be started earlier due to a manual intervention of a user or it may be started later in case the automatic resuming service is not available at the designated time. The application should take care of this. An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

Parameters:

timeout - The time period (in milliseconds) when the suspended application wants to be resumed automatically.

applicationReset

void applicationReset()

Notifies the runtime manager that the application has been terminated and wants to be reset that is activated again and the current and previous executions have to be completely dropped.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

applicationResetTo

void applicationResetTo(java.lang.String savepoint)

Notifies the runtime manager that the application has been terminated and wants to be reset to the designated savepoint. All changes after this savepoint will be lost.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

Parameters:

savepoint - The savepoint to which to reset the execution. This should be a previous savepoint. If this is null the last implicit savepoint will be used. If the savepoint does not exist, the execution will be reset completely.

applicationResetToPreviousSavepoint

void applicationResetToPreviousSavepoint()

Notifies the runtime manager that the application has been terminated and wants to be reset to the last savepoint before this application started. If there is no explicit savepoint, the last implicit savepoint will be used which is the state right before this execution resumed. If there is neither an explicit nor an implicit savepoint, a complete reset will occur. All changes done in the current execution will be lost. This will also include all implicit savepoint until the previous explicit savepoint.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

applicationClosed

void applicationClosed()

Called by the application to tell the runtime manager about its successful termination.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component. This also checks for whether all mandatory output parameters have been written. If not, an ApplicationFailedException will be thrown.

Throws:

ApplicationFailedException - If not all mandatory output parameters have been written, an ApplicationFailedException will be thrown.

applicationSignalled

void applicationSignalled(int signal)

Enables the application to signal a special event to the runtime manager. What type of signal is on hand is specified by the parameter signal.
An InvalidExecutorThreadException will be thrown if the method is not called by the main thread of the corresponding component.

Parameters:

signal - ID that specifies the type of the signalled event