de.aristaflow.adept2.core.runtimeservice

Interface RemoteActivityStarting

public interface RemoteActivityStarting

This interface is for starting and resuming activities that are bound to specific client applications which is indicated by the corresponding GUI context ID ( GUIConstants.CLIENT_APPLICATION). Only these activities can be started/resumed by this interface, other activities or lightweight processes will be declined with an IllegalArgumentException.
When starting/resuming an activity, its process context (e.g. its input parameter values) are provided as well as an ID identifying the session for executing the activity. This ID is required for every interaction with the runtime service/environment. Additionally, the credentials of the session token are bound to this execution session ID to provide a valid authentication and prevent messing with a stolen execution session ID.
Due to the loosely coupled execution, signals normally sent to the ExecutableComponent cannot be handled the same way. However, a callback can be registered for such signals. Such a callback has to be provided as URIs of the corresponding service. The callback is optional, client applications can also fetch the messages for the signals themselves via RemoteRuntimeEnvironment.

Obviously, a started/resumed activity eventually needs to be terminated. This is done as soon as one of the termination methods of the RemoteRuntimeEnvironment is called. This renders the session ID invalid and removes all data related to that execution, for instance outstanding messages. Depending on the kind of termination, the output data is required or optional. However, it is useful to always provide the output data produced until termination.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
SimpleSessionContext	getSimpleSessionContext(SessionToken session, EBPInstanceReference activity, ProcessConstants.ExecutionMode executionMode) Gets an incomplete simple session context for the designated activity.
Pair<java.util.Map<EBPInstanceReference,SimpleSessionContext>,java.util.Map<EBPInstanceReference,java.lang.Throwable>>	getSimpleSessionContexts(SessionToken session, java.util.Collection<EBPInstanceReference> activities, ProcessConstants.ExecutionMode executionMode) Gets incomplete simple session contexts for the designated activities.
SimpleSessionContext	resumeActivity(SessionToken session, EBPInstanceReference activity, java.net.URI[] exeMsgListener) Resumes the designated activity from the latest valid savepoint if the activity is appropriate for a RuntimeService and provides its process context and the execution session ID.
SimpleSessionContext	startActivity(SessionToken session, EBPInstanceReference activity, ProcessConstants.ExecutionMode executionMode, java.net.URI[] exeMsgListener) Starts the designated activity if it is appropriate for a RuntimeService and provides its process context and the execution session ID.

Method Detail

startActivity

SimpleSessionContext startActivity(SessionToken session,
                                   EBPInstanceReference activity,
                                   ProcessConstants.ExecutionMode executionMode,
                                   java.net.URI[] exeMsgListener)
                            throws InvalidActivityStateException,
                                   InvalidInstanceStateException

Starts the designated activity if it is appropriate for a RuntimeService and provides its process context and the execution session ID. For asynchronously receiving messages sent to execution, an ExecutionMessageListener can be provided.

Parameters:

session - The session which is used to check for access rights on this method and to retrieve the starting agent and the corresponding organisational position.

activity - The unique ID of the activity to start.

executionMode - The execution mode in which to start the activity, for instance, a test mode.

exeMsgListener - URIs of a ExecutionMessageListener to exchange execution messages asynchronously. If this is null, message exchange will be done synchronously, that is the messages will be provided via RemoteRuntimeEnvironment.getUnrepliedRequests(SessionToken, String).

Returns:

The SimpleSessionContext providing the process context (e.g. the input parameter values) of the started activity.

Throws:

InvalidActivityStateException - If the activity (process step) is not activated or selected by the designated user, an InvalidActivityStateException will be raised.

InvalidInstanceStateException - If the instance is not running but stopped, aborted, finished or changed, an InvalidInstanceStateException is thrown.

java.lang.IllegalArgumentException - If the designated activity does not fulfil the constraints for running in the runtime service, an IllegalArgumentException will be thrown.

resumeActivity

SimpleSessionContext resumeActivity(SessionToken session,
                                    EBPInstanceReference activity,
                                    java.net.URI[] exeMsgListener)
                             throws InvalidActivityStateException,
                                    InvalidInstanceStateException

Resumes the designated activity from the latest valid savepoint if the activity is appropriate for a RuntimeService and provides its process context and the execution session ID. For asynchronously receiving messages sent to execution, an ExecutionMessageListener can be provided. Since resuming the activity is internally asynchronous, a timeout is required. If this timeout elapses resuming will be aborted and null will be returned.

When resuming the savepoint from which to resume is provided in the returned session context. The additional state information related to that savepoint can be retrieved by RemoteRuntimeEnvironment.getApplicationState(SessionToken, String, String).

Parameters:

session - The session which is used to check for access rights on this method and to retrieve the starting agent and the corresponding organisational position.

activity - The unique ID of the activity to resume.

exeMsgListener - URIs of a ExecutionMessageListener to exchange execution messages asynchronously. If this is null, message exchange will be done synchronously, that is the messages will be provided via RemoteRuntimeEnvironment.getUnrepliedRequests(SessionToken, String).

Returns:

The SimpleSessionContext providing the process context (e.g. the input parameter values as well as the already provided output parameter values) of the resumed activity.

Throws:

InvalidActivityStateException - If the activity (process step) is not activated or selected by the designated user, an InvalidActivityStateException will be raised.

InvalidInstanceStateException - If the instance is not running but stopped, aborted, finished or changed, an InvalidInstanceStateException is thrown.

java.lang.IllegalArgumentException - If the designated activity does not fulfil the constraints for running in the runtime service, an IllegalArgumentException will be thrown.

getSimpleSessionContext

SimpleSessionContext getSimpleSessionContext(SessionToken session,
                                             EBPInstanceReference activity,
                                             ProcessConstants.ExecutionMode executionMode)
                                      throws InvalidActivityStateException,
                                             InvalidInstanceStateException

Gets an incomplete simple session context for the designated activity. This method allows for retrieving the simple session context of an activity without changing its state. However, this method can only be called for activities that are assigned to a user (selected, running or suspended) and only by the corresponding agent. This prevents forbidden data access.

The SimpleSessionContext.getSessionID() of the returned context will be null and the flag SimpleSessionContext.isResumed() will be unset since they cannot be determined.

Parameters:

session - The session which is used to check for access rights on this method.

activity - The activity for which to retrieve the simple session context.

executionMode - The execution mode which to apply, which may have consequences on the configuration.

Returns:

The simple session context for the designated activity as far as its attributes can be determined. This is only returned if the activity is assigned (selected, running or suspended) to the requesting agent.

Throws:

InvalidActivityStateException - If the activity (process step) is not selected, running or suspended by the designated user, an InvalidActivityStateException will be raised.

InvalidInstanceStateException - If the instance is not running but stopped, aborted, finished or changed, an InvalidInstanceStateException is thrown.

See Also:

ActivityStarting.getExecutionContext(SessionToken, EBPInstanceReference)

getSimpleSessionContexts

Pair<java.util.Map<EBPInstanceReference,SimpleSessionContext>,java.util.Map<EBPInstanceReference,java.lang.Throwable>> getSimpleSessionContexts(SessionToken session,
                                                                                                                                                java.util.Collection<EBPInstanceReference> activities,
                                                                                                                                                ProcessConstants.ExecutionMode executionMode)

Gets incomplete simple session contexts for the designated activities. This method allows for retrieving the simple session context of several activities as once. The state of the activities will not be affected by this. However, this method can only be called for activities that are assigned to a user (selected, running or suspended) and only by the corresponding agent. This prevents forbidden data access.
The SimpleSessionContext.getSessionID() of the returned contexts will be null and the flag SimpleSessionContext.isResumed() will be unset since they cannot be determined. The execution mode will be set to the designated one.

Make sure to check the second element of the pair indicating any problems that occurred when trying to retrieve the simple session context of the corresponding activity. This will contain the checked exceptions InvalidActivityStateException and InvalidInstanceStateException.

Parameters:

session - The session which is used to check for access rights on this method.

activities - The activities for which to retrieve the simple session contexts.

executionMode - The execution mode which to apply to all simple session contexts.

Returns:

The simple session contexts of the designated activities as far as the attributes can be determined. These will only be returned for activities that are assigned (selected, running or suspended) to the requesting agent. If there are problems retrieving the simple session context of a specific activity, this activity and the corresponding throwable will be in the second element of the pair.

See Also:

#getSimpleSessionContext(SessionToken, EBPInstanceReference, ExecutionMode), ActivityStarting.getExecutionContexts(SessionToken, Collection)