de.aristaflow.adept2.core.runtimeservice

Interface RuntimeService

All Superinterfaces:

ADEPT2Service, RuntimeManager

public interface RuntimeService
extends RuntimeManager

The runtime service resembles a runtime manager but it is not actively executing ExecutableComponents but just provides the information for execution passively. This allows arbitrary client application to use ADEPT2 as information provider for the execution of activities. The client applications have control over the execution instead of the runtime environment of ADEPT2.
When starting or resuming activities, the process context ( SimpleSessionContext) is provided including for instance the values for input parameters but no GUI context. The execution is decoupled from the runtime service, the interaction is controlled by the corresponding client application. However, since ADEPT2 is designed to control the execution, there may be control requests and signals sent to the execution. These can only be offered to the executing client application. Since this is rather critical, a callback may be registered to increase response behaviour of the client application.
Just like with ExecutableComponent each execution (session) is identified by an ID ( SessionContext.getSessionID() and SimpleSessionContext.getSessionID() ). These needs to be provided at the interface methods. Additionally, the methods require an authentication by providing a SessionToken. This usually has to have the same credentials as the one that started/resumed the execution. Otherwise it would be possible to control the execution just by knowing the ID of the execution session.
Due to the loose coupling between executing client and runtime environment, it is possible that the runtime environment has terminated/aborted the execution, while the the executing client has not taken notice of this. Therefore most methods requiring the execution session ID may throw an UnknownSessionException. Like the name implies the runtime service does not know the session ID, which may either be due to not being the runtime manager having started the execution session or the execution being terminated by already terminated due to various reasons.

Note that besides the reduced control through ADEPT2, using this kind of execution prevents reusing the activity. An ExecutableComponent is self-contained and can therefore be used in any process and executed in any client as long as there is a runtime manager providing the required GUIContext. Executing via RuntimeService only works if the activity is started by the client application that is able to interpret the corresponding process context. Thus the activity is on the one hand closely bound to the client application and on the other hand even to the process context. That is, the executing client application already needs to be considered when modelling the corresponding process template.
Due to this restrictions we do not recommend using this interface. However, it allows for easy integration of process logic including simple data provision into existing client applications. To distinguish this kind of execution from the reusable execution using ExecutableComponent we use the term "clients executing activities proprietarily".

Although a RuntimeService significantly differs from a RuntimeManager it needs the very same interface to hide the different execution behaviour from ADEPT2. However, only activities fulfilling the requirements for execution by a runtime service like not having a real GUI context can be started/resumed by the runtime service. Starting/resuming of incompatible activities will be declined. Additionally, a user need not log on at the runtime service. Therefore no AgentUnknownException will be thrown by this service.
Despite logging on being a no-op, logging a user off from the runtime service works by terminating all running activities of the corresponding user. Note that since this service has no control over the execution, terminating running activities via the runtime service may lead to heavy failing of these activities since the execution sessions may not respond to a termination request in time.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
RemoteExecutionControlManager	getExecutionControlManager() Gets a manager for controlling the execution of an activity, for instance, finishing, suspending,...
RemoteProgressMonitor	getProgressMonitor() Gets the interface for remotely using ProgressMonitor.
ProgressMonitor	getProgressMonitor(SessionToken token, java.lang.String sessionID) Gets the ProgressMonitor for the designated execution session.
RemoteActivityStarting	getRemoteActivityStarting() Gets the activity starting for clients executing activities proprietarily.
RemoteRuntimeEnvironment	getRuntimeEnvironment() Gets the interface for remotely using RuntimeEnvironment.
SynchronousActivityStarting	getSynchronousActivityStarting() Returns null.
java.util.Map<EBPInstanceReference,ProcessConstants.NodeState>	logoffAndTerminateActivities(SessionToken session, QualifiedAgent agent, boolean forceTermination) Logs the agent off that is identified by the designated client session factory.
void	logon(SessionToken token, ClientSessionFactory csf) Does nothing since a runtime service does not know about logged on agents.

Methods inherited from interface de.aristaflow.adept2.core.runtimemanager.RuntimeManager

commit, preferAutoStartNotification, prepareCommit, resumeActivity, rollbackActivity, startActivity, updateClientSessionFactory

Methods inherited from interface de.aristaflow.adept2.base.service.ADEPT2Service

getLocalUris, getRelease, getRuntimeRequiredServices, getServiceInstanceName, getStartupRequiredServices, getURIs, init, ping, preShutdown, shutdown, start

Method Detail

logon

void logon(SessionToken token,
           ClientSessionFactory csf)

Does nothing since a runtime service does not know about logged on agents. This has to be handled by the corresponding client using the runtime service.

Specified by:

logon in interface RuntimeManager

Parameters:

token - Ignored.

csf - Ignored.

logoffAndTerminateActivities

java.util.Map<EBPInstanceReference,ProcessConstants.NodeState> logoffAndTerminateActivities(SessionToken session,
                                                                                            QualifiedAgent agent,
                                                                                            boolean forceTermination)

Logs the agent off that is identified by the designated client session factory. Afterwards this agent cannot execute activities on this runtime manager any longer. Currently running activities will be suspended if they support this. Otherwise they keep on running unless the termination is forced. A forced termination will reset or abort running activities that cannot be suspended. If you do not want to logoff in case of running activities, use ExecutionControlManager.getActivities(SessionToken, de.aristaflow.adept2.model.runtimeenvironment.ActivityState.State[]) beforehand.
Terminating activities is done the same way as shutting down the runtime manager.

The returned map contains all activities that have been running when calling this method mapped to their state after executing this method. Their state is represented as ProcessConstants.NodeState as follows:

• NS_SUSPENDED: The activity supports a suspend and suspending it was successful.
• NS_RUNNING: The activity was suspended and the termination was not forced. Therefore it keeps on running.
• NS_COMPLETED: The termination was forced and the activity was able to close itself.
• NS_ACTIVATED: The termination was forced and the activity was able to reset itself.
• NS_FAILED: The termination was forced and the activity was aborted.
• null: The termination failed with an exception, the node state could not be determined.

Implementations have to be synchronised correctly, since a logoff can happen concurrently to starting or resuming an activity. ensure to only allow to execute activities for the logged on agents. And only these client session factories must be used! This method is not synchronised against concurrent starting or resuming, since the agents are not explicitly logged on. This method just terminates all currently running activities of the agent identified by the session token.

Specified by:

logoffAndTerminateActivities in interface RuntimeManager

Parameters:

session - The session which is used to check for access rights on this method and to retrieve agent of whom to terminate the running activities.

agent - Ignored.

forceTermination - Whether unsuspensible activities should be reset or aborted instead of continue to run.

Returns:

The running activities and their state (running, suspended, finished or failed) after executing this method. This allows to recheck and stop the activities that should not keep on running.

getExecutionControlManager

RemoteExecutionControlManager getExecutionControlManager()

Gets a manager for controlling the execution of an activity, for instance, finishing, suspending,... The returned execution control manager can be used remotely by clients executing activities proprietarily.

Specified by:

getExecutionControlManager in interface RuntimeManager

Returns:

An instance for controlling the execution of activities.

getSynchronousActivityStarting

SynchronousActivityStarting getSynchronousActivityStarting()

Returns null. Use getRemoteActivityStarting() instead since starting activities remotely works differently from starting them synchronously.

Specified by:

getSynchronousActivityStarting in interface RuntimeManager

Returns:

null. Use getRemoteActivityStarting() instead.

getRemoteActivityStarting

RemoteActivityStarting getRemoteActivityStarting()

Gets the activity starting for clients executing activities proprietarily. This allows to start and resume activities while providing the session context. Since no ExecutableComponent instance exists, all interaction while executing needs to be done via a remote runtime environment.

Returns:

The activity starting for clients executing activities proprietarily providing the session context of the activity when starting or resuming.

getRuntimeEnvironment

RemoteRuntimeEnvironment getRuntimeEnvironment()

Gets the interface for remotely using RuntimeEnvironment. Since we do not have an ExecutableComponent, the interaction with the RuntimeEnvironment needs to be done via a service.

Returns:

The interface for remotely using RuntimeEnvironment clients executing activities proprietarily not using ExecutableComponent.

getProgressMonitor

RemoteProgressMonitor getProgressMonitor()

Gets the interface for remotely using ProgressMonitor. Since we do not have an ExecutableComponent, the interaction with the ProgressMonitor needs to be done via a service.

Returns:

The interface for remotely using ProgressMonitor clients executing activities proprietarily not using ExecutableComponent.

getProgressMonitor

ProgressMonitor getProgressMonitor(SessionToken token,
                                   java.lang.String sessionID)
                            throws UnknownSessionException

Gets the ProgressMonitor for the designated execution session. This may only be used locally since the returned ProgressMonitor cannot be used remotely. Remote callers need to use getProgressMonitor().

Parameters:

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

sessionID - The execution session ID to retrieve the corresponding progress monitor.

Returns:

The progress monitor for the designated execution session.

Throws:

UnknownSessionException - If the designated session 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.