de.aristaflow.adept2.core.executionmanager

Interface ActivityStarting

All Known Subinterfaces:

SynchronousActivityStarting

public interface ActivityStarting

This interface provides the means to control start events of an activity, that is, selecting, deselecting, starting and resuming an activity. These transitions are used by worklists where the user initiates a state-transition. It also supports enquiries which allow to receive help by another user.
The activity has to be in a proper state, for instance, it will not be allowed to be started if it is not activated. For the appropriate state transitions refer to the ADEPT-metamodel.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
void	deselectActivity(SessionToken session, EBPInstanceReference activity) Deselects the designated activity, that is, the designated user does not want to execute the activity later any more.
void	enquireActivity(SessionToken session, EBPInstanceReference activity, java.util.Set<QualifiedAgent> recipients, java.lang.String question) Sets an enquiry for the designated activity and delegates it to the designated recipients.
java.util.Set<QualifiedAgent>	getEnquiryRecipients(SessionToken session, EBPInstanceReference activity) Gets all agents that are possible recipients for an enquiry for the designated activity and the agent identified by the designated session token.
RemoteIterator<java.util.List<QualifiedAgent>>	getEnquiryRecipientsIterator(SessionToken session, EBPInstanceReference activity) The same as getEnquiryRecipients(SessionToken, EBPInstanceReference) but with partial retrieval of the agents.
ExecutionContext	getExecutionContext(SessionToken session, EBPInstanceReference activity) Gets the execution context for the designated activity.
Pair<java.util.Map<EBPInstanceReference,ExecutionContext>,java.util.Map<EBPInstanceReference,java.lang.Throwable>>	getExecutionContexts(SessionToken session, java.util.Collection<EBPInstanceReference> activities) Gets the execution contexts for the designated activities.
void	replyEnquiry(SessionToken session, EBPInstanceReference activity, java.lang.String reply) Replies to the designated activity, that is the last enquiry is replied.
void	resumeActivity(SessionToken session, EBPInstanceReference activity) Resumes the designated activity from the latest valid savepoint and logs the agent, the organisational position.
void	selectActivity(SessionToken session, EBPInstanceReference activity) Selects the designated activity, that is, the designated user wants to execute the activity later.
void	startActivity(SessionToken session, EBPInstanceReference activity, ProcessConstants.ExecutionMode executionMode) Starts the designated activity in the designated execution mode and logs the agent, the organisational position.

Method Detail

selectActivity

void selectActivity(SessionToken session,
                    EBPInstanceReference activity)
             throws InvalidActivityStateException,
                    InvalidInstanceStateException

Selects the designated activity, that is, the designated user wants to execute the activity later. This method is called by clients to select an activity represented by a worklist item. The execution manager sets the state accordingly and removes the worklist item from the worklists of non-selectors.
The activity needs to be managed by this execution manager and has to be in the appropriate state (NS_ACTIVATED).

Parameters:

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

activity - The reference identifying the activity to select.

Throws:

InvalidActivityStateException - If the activity (process step) is not activated, an InvalidActivityStateException will be raised.

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

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

See Also:

DataContainer, ProcessConstants.NodeState

deselectActivity

void deselectActivity(SessionToken session,
                      EBPInstanceReference activity)
               throws InvalidActivityStateException,
                      InvalidInstanceStateException

Deselects the designated activity, that is, the designated user does not want to execute the activity later any more. This method is called by clients to deselect an activity represented by a worklist item. The execution manager resets the state accordingly (NS_ACTIVATED) and adds the worklist item to the corresponding worklists.
The activity needs to be managed by this execution manager and has to be in the appropriate state (NS_SELECTED).

Parameters:

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

activity - The reference identifying the activity to deselect.

Throws:

InvalidActivityStateException - If the activity (process step) is not 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.

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

WrongAgentException - If the calling agent is not the same agent who selected the activity.

See Also:

DataContainer, ProcessConstants.NodeState

startActivity

void startActivity(SessionToken session,
                   EBPInstanceReference activity,
                   ProcessConstants.ExecutionMode executionMode)
            throws InvalidActivityStateException,
                   InvalidInstanceStateException,
                   AgentUnknownException

Starts the designated activity in the designated execution mode and logs the agent, the organisational position. This method is called by clients to start an activity represented by a worklist item. The execution manager chooses the appropriate runtime manager to execute the activity/application. It also provides the necessary data container to the runtime manager.
The activity needs to be managed by this execution manager and has to be in an appropriate state (NS_ACTIVATED or NS_SELECTED).

This method is also used to display (re-execute) an activity that has already been executed. The activity is started normally in ProcessConstants.ExecutionMode.VIEW_ONLY with a special data container providing read-only access to the values of the output parameters written in the corresponding execution.

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 reference identifying the activity to start.

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

Throws:

InvalidActivityStateException - If the activity (process step) is not activated or selected by the designated user (for normal or test execution) or the designated EBPInstanceReference does not refer to a valid runtime manager, an InvalidActivityStateException will be raised. For ProcessConstants.ExecutionMode.VIEW_ONLY the activity needs to be in state NS_FINISHED or NS_ENQUIRED and it needs to support it. Otherwise an InvalidActivityStateException will be raised.

InvalidInstanceStateException - If the instance is not running but stopped, aborted or finished (for normal or test execution), an InvalidInstanceStateException is thrown. This does not apply to ProcessConstants.ExecutionMode.VIEW_ONLY, which is allowed in all instance states.

AgentUnknownException - If the specified runtime manager refuses the execution since it does not know the designated agent, an AgentUnknownException will be thrown.

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

WrongAgentException - If the calling agent is not the same agent who selected the activity.

See Also:

DataContainer, ProcessConstants.NodeState

resumeActivity

void resumeActivity(SessionToken session,
                    EBPInstanceReference activity)
             throws InvalidActivityStateException,
                    InvalidInstanceStateException,
                    AgentUnknownException

Resumes the designated activity from the latest valid savepoint and logs the agent, the organisational position. This method is called by clients to resume an activity. The execution manager chooses the appropriate runtime manager to resume the execution of the activity/application. It also provides the necessary data container to the runtime manager.
The activity needs to be managed by this execution manager and has to be in an appropriate state (NS_SUSPENDED).

Parameters:

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

activity - The reference identifying the activity to resume.

Throws:

InvalidActivityStateException - If the activity (process step) is not suspended, an InvalidActivityStateException will be raised.

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

AgentUnknownException - If the specified runtime manager refuses the execution since it does not know the designated agent, an AgentUnknownException will be thrown.

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

See Also:

DataContainer, ProcessConstants.NodeState

getEnquiryRecipients

java.util.Set<QualifiedAgent> getEnquiryRecipients(SessionToken session,
                                                   EBPInstanceReference activity)

Gets all agents that are possible recipients for an enquiry for the designated activity and the agent identified by the designated session token.

Implementors must not use a remote iterator when using a database since this may lead to a deadlock since the remote iterator uses its own transaction!

Parameters:

session - The session token identifying the enquiring agent.

activity - The activity to enquire and to determine the enquiry recipients of.

Returns:

A collection of agents to whom the enquiring agent may send the enquiry concerning the designated activity.

getEnquiryRecipientsIterator

RemoteIterator<java.util.List<QualifiedAgent>> getEnquiryRecipientsIterator(SessionToken session,
                                                                            EBPInstanceReference activity)

The same as getEnquiryRecipients(SessionToken, EBPInstanceReference) but with partial retrieval of the agents.

Parameters:

session - The session token identifying the enquiring agent.

activity - The activity to enquire and to determine the enquiry recipients of.

Returns:

An iterator for agents to whom the enquiring agent may send the enquiry concerning the designated activity.

enquireActivity

void enquireActivity(SessionToken session,
                     EBPInstanceReference activity,
                     java.util.Set<QualifiedAgent> recipients,
                     java.lang.String question)
              throws InvalidActivityStateException,
                     InvalidInstanceStateException

Sets an enquiry for the designated activity and delegates it to the designated recipients. This way a performing agent (identified by the session token) may get assistance by other agents when executing the activity. The activity has to be suspended (NS_SUSPENDED) for this special delegation to take place. The activity is then placed in the worklists of the designated recipients with the designated comment. Afterwards the activity can be normally executed (resumeActivity(SessionToken, EBPInstanceReference)) by one of the recipients. The executor can then suspend it afterwards and send it back to the delegator (replyEnquiry(SessionToken, EBPInstanceReference, String)). The executor may also finish the activity, in this case the process will proceed and the delegator will receive the reply without being able to finish the activity. If the activity supports ProcessConstants.ExecutionMode.VIEW_ONLY, the delegator may start the activity as VIEW_ONLY and view the result of the execution besides the reply.
Enquiries may be nested, but every initiator will receive the corresponding reply (enquiries are stacked).

The activity needs to be managed by this execution manager and has to be in an appropriate state (NS_SUSPENDED by the designated user).

Parameters:

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

activity - The reference identifying the activity to enquire.

recipients - The agents who should assist in executing the activity.

question - A question describing the problem when executing the activity. This may be null.

Throws:

InvalidActivityStateException - If the activity (process step) is not suspended, an InvalidActivityStateException will be raised.

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

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

replyEnquiry

void replyEnquiry(SessionToken session,
                  EBPInstanceReference activity,
                  java.lang.String reply)
           throws InvalidActivityStateException,
                  InvalidInstanceStateException

Replies to the designated activity, that is the last enquiry is replied. It is delegated back to the originator of the enquiry (when suspended) or only the reply is delegated back (when finished by the enquiry receiver). The originating agent may then resume and finish the activity finally (or replying in case of nested enquiries). A corresponding item containing the designated reply will be added to the worklist of the originator of the replied enquiry.
The activity needs to be managed by this execution manager and has to be in an appropriate state (NS_SUSPENDED or NS_ENQUIRIED).

If the activity is in state NS_ENQUIRIED with no current enquiries but one replied enquiry left, the corresponding agent needs to call this method which does not reply but drop the last replied enquiry and sets the state to NS_COMPLETED.

Parameters:

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

activity - The reference identifying the activity which has been replied.

reply - A comment containing the answer for the originator. This may be null.

Throws:

InvalidActivityStateException - If no enquiry is active for the designated activity (process step) and the designated user, an InvalidActivityStateException will be raised.

InvalidInstanceStateException - If the activity is not in state SUSPENDED and the instance is not running but stopped, aborted, finished or changed, an InvalidInstanceStateException is thrown. If the activity is in state ENQUIRED, the instance state will be ignored.

WrongExecutionManagerException - If the designated activity is not managed by this execution manager, a WrongExecutionManagerException will be raised.

getExecutionContext

ExecutionContext getExecutionContext(SessionToken session,
                                     EBPInstanceReference activity)
                              throws InvalidActivityStateException,
                                     InvalidInstanceStateException

Gets the execution context for the designated activity. This method allows for retrieving the execution 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.

Parameters:

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

activity - The activity for which to retrieve the execution context.

Returns:

The execution context of the designated activity. This is only returned if the activity is assigned (selected, running or suspended) to the requesting agent.
Note that the execution mode will always be null.

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.

getExecutionContexts

Pair<java.util.Map<EBPInstanceReference,ExecutionContext>,java.util.Map<EBPInstanceReference,java.lang.Throwable>> getExecutionContexts(SessionToken session,
                                                                                                                                        java.util.Collection<EBPInstanceReference> activities)

Gets the execution contexts for the designated activities. This method allows for retrieving the execution 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.

Make sure to check the second element of the pair indicating any problems that occurred when trying to retrieve the execution 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 execution contexts.

Returns:

The execution contexts of the designated activities. These will only be returned for activities that are assigned (selected, running or suspended) to the requesting agent. If there are problems retrieving the execution context of a specific activity, this activity and the corresponding throwable will be in the second element of the pair.
Note that the execution mode in the execution contexts will always be null.

See Also:

getExecutionContext(SessionToken, EBPInstanceReference)