de.aristaflow.adept2.core.runtimeservice

Interface RemoteRuntimeEnvironment

public interface RemoteRuntimeEnvironment

The interface provides RuntimeEnvironments for clients executing activities proprietarily not using ExecutableComponent. Usually this interface is called remotely. Therefore not all methods of the RuntimeEnvironment are provided here. Additionally, dispatching needs to be done by the client, therefore messages are provided and need to be replied to. This can be done either by polling (getUnrepliedRequests(SessionToken, String), replyMessage(SessionToken, ReplyMessage)) or asynchronously via ExecutionMessageListener. Due to the loose coupling between execution and runtime manager, there are no checks for the valid executor thread.

Since this handles several executions concurrently, each method requires the sessionID of the execution. If the designated session ID does not exist, an UnknownSessionException will be thrown for each method. This usually indicates that the execution has been terminated from server side but the executing client has not responded in time. Clients should check the state of the corresponding process step.
If the session token does not match the designated session ID, that is the session token has not the same credentials as the starting token, a ServiceAccessControlException will be thrown. That means the session token needs to have the same top-level session token as the starting/resuming session token.

The methods of these interface are similar to the ones of RuntimeEnvironment. They need an additional session ID to identify the execution session and a session token to verify it. Additionally methods for terminating the execution have to provide the data context (since the data cannot be stored as side-effect like in a DataContext). Note that this data context only needs to provide the values of the output parameters but not the values of the input parameters like the data context provided when starting/resuming the activity. However, it can also be the very same DataContext-instance.
And unlike the normal runtime environment, only one of the termination methods must be called which immediately indicates the termination of the execution. With ExecutableComponents, the termination is indicated by leaving the run-method which allows to call the termination methods arbitrarily. Obviously calling a termination method renders the corresponding session ID invalid.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
void	applicationClosed(SessionToken token, java.lang.String sessionID, SerialisableDataContext dataContext) Signals the termination of the designated execution session that is the execution is closed.
void	applicationFailed(SessionToken token, java.lang.String sessionID, ApplicationEnvironmentException excpt, SerialisableDataContext dataContext) Signals the failing of the designated execution session that is the execution is terminated due to the designated application environment exception and all data produced yet is invalidated.
void	applicationFailed(SessionToken token, java.lang.String sessionID, ApplicationFailedException excpt, SerialisableDataContext dataContext) Signals the failing of the designated execution session that is the execution is terminated due to the designated application failed exception and all data produced yet is invalidated.
void	applicationFailed(SessionToken token, java.lang.String sessionID, java.lang.String errorMessage, java.lang.String state, long errorCode, SerialisableDataContext dataContext) Signals the failing of the designated execution session that is the execution is terminated due to a failure and all data produced yet is invalidated.
void	applicationReset(SessionToken token, java.lang.String sessionID, SerialisableDataContext dataContext) Signals the termination of the designated execution session that is the execution is reset and all data produced yet (including from previous execution sessions) is invalidated.
void	applicationResetTo(SessionToken token, java.lang.String sessionId, java.lang.String savepoint, SerialisableDataContext dataContext) Signals the termination of the designated execution session that is the execution is reset to the designated savepoint.
void	applicationResetToPreviousSavepoint(SessionToken token, java.lang.String sessionId, SerialisableDataContext dataContext) Signals the termination of the designated execution session that is the execution is reset to the last savepoint before the execution started.
void	applicationSuspended(SessionToken token, java.lang.String sessionID, SerialisableDataContext dataContext) Signals the termination of the designated execution session that is the execution is suspended.
byte[]	getApplicationState(SessionToken token, java.lang.String sessionId, java.lang.String savepoint) RuntimeEnvironment.getApplicationState(String)
java.lang.String	getLastSavepoint(SessionToken token, java.lang.String sessionId) RuntimeEnvironment.getLastSavepoint()
ActivityInstance	getLocalisedActivityInstance(SessionToken token, java.lang.String sessionId) Gets the activity instance localised with respect to the rich agent of the designated execution session.
java.util.List<de.aristaflow.adept2.model.runtimeenvironment.messages.execution.ExecutionMessage>	getUnrepliedRequests(SessionToken token, java.lang.String sessionID) Gets the request messages that have been sent to the designated execution session.
boolean	replyMessage(SessionToken token, de.aristaflow.adept2.model.runtimeenvironment.messages.execution.ReplyMessage<?> reply) Replies to a request message received by getUnrepliedRequests(SessionToken, String).
void	setApplicationState(SessionToken token, java.lang.String sessionId, byte[] applicationState) RuntimeEnvironment.setApplicationState(byte[])
void	setSavepoint(SessionToken token, java.lang.String sessionId, java.lang.String savepoint, boolean flush, SerialisableDataContext dataContext) RuntimeEnvironment.setSavepoint(String, boolean)

Method Detail

getLocalisedActivityInstance

ActivityInstance getLocalisedActivityInstance(SessionToken token,
                                              java.lang.String sessionId)
                                       throws UnknownSessionException

Gets the activity instance localised with respect to the rich agent of the designated execution session.

Parameters:

token - The session token which is used to check for access rights on this method. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionId - The session ID of the execution to get the localised activity instance of.

Returns:

The activity instance localised with respect to the rich agent of the designated execution session. This will be null if no localisation can apply.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

getUnrepliedRequests

java.util.List<de.aristaflow.adept2.model.runtimeenvironment.messages.execution.ExecutionMessage> getUnrepliedRequests(SessionToken token,
                                                                                                                       java.lang.String sessionID)
                                                                                                                throws UnknownSessionException

Gets the request messages that have been sent to the designated execution session. This includes newly sent messages as well as old messages that have not been replied yet.
The messages are the same messages that are sent to an ExecutableComponent and dispatched in the runtime environment. Due to the loose coupling dispatching has to be done by the proprietarily executing client. This can either be done by providing an ExecutionMessageListener when starting/resuming the activity or by calling this method regularly (just like RuntimeEnvironment.dispatch() ). Messages should be replied fast since the signaller sending the message usually waits if a reply is expected (depends on the message).

Parameters:

token - The session token which is used to check for access rights on this method. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionID - The session ID of the execution to get messages for.

Returns:

The list of request messages received since the last time this method has been called and additionally old messages that have not been replied yet but the requestor is still waiting for a reply. The list is in FIFO order, that is the most recent request is at the end. Usually this is the most critical request. In case there are no messages, an empty list will be returned. If the designated execution session has registered an ExecutionMessageListener null will be returned.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

replyMessage

boolean replyMessage(SessionToken token,
                     de.aristaflow.adept2.model.runtimeenvironment.messages.execution.ReplyMessage<?> reply)
              throws UnknownSessionException

Replies to a request message received by getUnrepliedRequests(SessionToken, String). This should be done fast since the requestor may wait for this reply.
The reply must have the same message and session ID as the corresponding request message. It may be the very same ReplyMessage -instance.
Replying positively to a state change request, for instance a CloseMessage does not mean, the execution has terminated when the reply is sent but rather the execution will close shortly.

Parameters:

token - The session token which is used to check for access rights on this method. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

reply - The message containing the reply for the corresponding request message.

Returns:

Whether the requestor has waited for the reply and received it in time (and not retrieved a timeout while waiting for it). This indicates whether the requestor will react appropriately depending on the reply. If the requestor is not waiting at all, false will be returned.

Throws:

UnknownSessionException - If the session ID of the reply is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the session ID of the reply, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

getApplicationState

byte[] getApplicationState(SessionToken token,
                           java.lang.String sessionId,
                           java.lang.String savepoint)
                    throws UnknownSessionException

RuntimeEnvironment.getApplicationState(String)

Parameters:

token - The session token which is used to check for access rights on this method. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionId - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

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

Returns:

application related session content

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

getLastSavepoint

java.lang.String getLastSavepoint(SessionToken token,
                                  java.lang.String sessionId)
                           throws UnknownSessionException

RuntimeEnvironment.getLastSavepoint()

Parameters:

token - The session token which is used to check for access rights on this method. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionId - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

Returns:

The ID of the last savepoint stored for the designated execution session or null in case no savepoint has been stored yet.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

setApplicationState

void setApplicationState(SessionToken token,
                         java.lang.String sessionId,
                         byte[] applicationState)
                  throws UnknownSessionException

RuntimeEnvironment.setApplicationState(byte[])

Parameters:

token - The session token which is used to check for access rights on this method. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionId - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

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

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

setSavepoint

void setSavepoint(SessionToken token,
                  java.lang.String sessionId,
                  java.lang.String savepoint,
                  boolean flush,
                  SerialisableDataContext dataContext)
           throws UnknownSessionException

RuntimeEnvironment.setSavepoint(String, boolean)

Parameters:

token - The session token which is used to check for access rights on this method. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionId - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

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.

dataContext - The data context providing the output parameters produced in the execution yet. These need not be complete since they are just flushed and may be used when resuming. This may be null to indicate that no output parameter values have been produced yet.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

applicationSuspended

void applicationSuspended(SessionToken token,
                          java.lang.String sessionID,
                          SerialisableDataContext dataContext)
                   throws UnknownSessionException

Signals the termination of the designated execution session that is the execution is suspended. The corresponding data context provides the values of the output parameters produced yet.

Parameters:

token - The session token which is used to check for access rights on this method and to suspend the activity. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionID - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

dataContext - The data context providing the output parameters produced in the execution yet. These need not be complete since the execution is suspended and will be resumed. This may be null to indicate that no output parameter values have been produced yet.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

See Also:

RuntimeEnvironment.applicationSuspended()

applicationReset

void applicationReset(SessionToken token,
                      java.lang.String sessionID,
                      SerialisableDataContext dataContext)
               throws UnknownSessionException

Signals the termination of the designated execution session that is the execution is reset and all data produced yet (including from previous execution sessions) is invalidated. The corresponding data context is for information purpose only.

Parameters:

token - The session token which is used to check for access rights on this method and to reset the activity. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionID - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

dataContext - The data context providing the output parameters produced in the execution. These is for information purpose only, that is the values will be stored in the data manager but invalidated right afterwards since the execution has been reset. Therefore this may be null.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

See Also:

RuntimeEnvironment.applicationReset()

applicationResetTo

void applicationResetTo(SessionToken token,
                        java.lang.String sessionId,
                        java.lang.String savepoint,
                        SerialisableDataContext dataContext)
                 throws UnknownSessionException

Signals the termination of the designated execution session that is the execution is reset to the designated savepoint. All data produced after this savepoint (including from previous execution sessions) is invalidated and will be removed. The corresponding data context is for information purpose only.

Parameters:

token - The session token which is used to check for access rights on this method and to reset the activity. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionId - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

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

dataContext - The data context providing the output parameters produced in the execution. These is for information purpose only, that is the values will be stored in the data manager but invalidated right afterwards since the execution has been reset. Therefore this may be null.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

See Also:

RuntimeEnvironment.applicationResetTo(String)

applicationResetToPreviousSavepoint

void applicationResetToPreviousSavepoint(SessionToken token,
                                         java.lang.String sessionId,
                                         SerialisableDataContext dataContext)
                                  throws UnknownSessionException

Signals the termination of the designated execution session that is the execution is reset to the last savepoint before the execution 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 (including current explicit savepoints) done in the current execution will be lost. This will also include all implicit savepoint until the previous explicit savepoint. The corresponding data context is for information purpose only.

Parameters:

token - The session token which is used to check for access rights on this method and to reset the activity. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionId - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

dataContext - The data context providing the output parameters produced in the execution. These is for information purpose only, that is the values will be stored in the data manager but invalidated right afterwards since the execution has been reset. Therefore this may be null.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

See Also:

RuntimeEnvironment.applicationResetToPreviousSavepoint()

applicationClosed

void applicationClosed(SessionToken token,
                       java.lang.String sessionID,
                       SerialisableDataContext dataContext)
                throws UnknownSessionException

Signals the termination of the designated execution session that is the execution is closed. The corresponding data context provides all the values for the output parameters as defined for the corresponding activity used in the process template.
This also checks for whether all mandatory output parameters have been written. The application will be failed and the corresponding ApplicationFailedException will be thrown by this method so that the caller knows the problem. Since the application will be failed, the runtime service will not know it any more afterwards.

Parameters:

token - The session token which is used to check for access rights on this method and to close the activity. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionID - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

dataContext - The data context providing the output parameters produced in the execution yet. There have to be values for all mandatory output parameters and at least null values for optional output parameters. This may only be null when closing a view-only execution session.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

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

See Also:

RuntimeEnvironment.applicationClosed()

applicationFailed

void applicationFailed(SessionToken token,
                       java.lang.String sessionID,
                       java.lang.String errorMessage,
                       java.lang.String state,
                       long errorCode,
                       SerialisableDataContext dataContext)
                throws UnknownSessionException

Signals the failing of the designated execution session that is the execution is terminated due to a failure and all data produced yet is invalidated. This resembles an ApplicationFailedException which is usually thrown by ExecutableComponent.run().

Parameters:

token - The session token which is used to check for access rights on this method and to fail the activity. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionID - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

errorMessage - The corresponding error message that describes the error in detail

state - Arbitrary state information specific to the component, comparable to the vendor code in SQLException.

errorCode - A well-defined error code.

dataContext - The data context providing the output parameters produced in the execution. These is for information purpose only, that is the values will be stored in the data manager but they are not used in the process since the execution failed. However, providing these values may help in determining the cause of the failure. Therefore this may be null.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

See Also:

ApplicationFailedException

applicationFailed

void applicationFailed(SessionToken token,
                       java.lang.String sessionID,
                       ApplicationFailedException excpt,
                       SerialisableDataContext dataContext)
                throws UnknownSessionException

Signals the failing of the designated execution session that is the execution is terminated due to the designated application failed exception and all data produced yet is invalidated. This resembles an ApplicationFailedException which is usually thrown by ExecutableComponent.run().

Parameters:

token - The session token which is used to check for access rights on this method and to fail the activity. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionID - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

excpt - The ApplicationFailedException for failing the the execution session.

dataContext - The data context providing the output parameters produced in the execution. These is for information purpose only, that is the values will be stored in the data manager but they are not used in the process since the execution failed. However, providing these values may help in determining the cause of the failure. Therefore this may be null.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.

applicationFailed

void applicationFailed(SessionToken token,
                       java.lang.String sessionID,
                       ApplicationEnvironmentException excpt,
                       SerialisableDataContext dataContext)
                throws UnknownSessionException

Signals the failing of the designated execution session that is the execution is terminated due to the designated application environment exception and all data produced yet is invalidated. This resembles an ApplicationEnvironmentException which is usually thrown by ExecutableComponent.run().

Parameters:

token - The session token which is used to check for access rights on this method and to fail the activity. This has to be a session token having the same credentials (top-level session token) as the session token used for starting the corresponding activity.

sessionID - The session ID of the execution. This is the same session ID provided to an ExecutableComponent.

excpt - The ApplicationEnvironmentException for failing the execution session.

dataContext - The data context providing the output parameters produced in the execution. These is for information purpose only, that is the values will be stored in the data manager but they are not used in the process since the execution failed. However, providing these values may help in determining the cause of the failure. Therefore this may be null.

Throws:

UnknownSessionException - If the designated session ID is not known, an UnknownSessionException will be thrown. This usually indicates that the server has terminated the execution because the client did not respond in time.

ServiceAccessControlException - If the designated token does not match the designated session ID, that is the session token has not the same credentials as the token starting the designated execution session, a ServiceAccessControlException will be thrown.