Package 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.

    • Method Detail

      • selectActivity

        void selectActivity​(SessionToken session,
                    EBPInstanceReference activity)
             throws InvalidActivityStateException,
                    InvalidInstanceStateException,
                    WrongAgentException
        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.
        WrongAgentException - If the calling agent does not have the designated activity in the worklist, a WrongAgentException 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

      • deselectActivity

        void deselectActivity​(SessionToken session,
                      EBPInstanceReference activity)
               throws InvalidActivityStateException,
                      InvalidInstanceStateException,
                      WrongAgentException
        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,
                   WrongAgentException,
                   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.
        WrongAgentException - If the calling agent does not have the designated activity in the worklist, a WrongAgentException will be 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

      • resumeActivity

        void resumeActivity​(SessionToken session,
                    EBPInstanceReference activity)
             throws InvalidActivityStateException,
                    InvalidInstanceStateException,
                    WrongAgentException,
                    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.
        WrongAgentException - If the calling agent does not have the designated activity in the worklist, a WrongAgentException will be 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

        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.

      • enquireActivity

        void enquireActivity​(SessionToken session,
                     EBPInstanceReference activity,
                     Set<QualifiedAgent> recipients,
                     String question)
              throws InvalidActivityStateException,
                     InvalidInstanceStateException,
                     WrongAgentException
        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.
        WrongAgentException - If the calling agent does not have the designated activity in the worklist, a WrongAgentException will be 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,
                  String reply)
           throws InvalidActivityStateException,
                  InvalidInstanceStateException,
                  WrongAgentException
        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.
        WrongAgentException - If the calling agent is not a recipient of the replied enquiry or not the requestor of the last enquiry, a WrongAgentException will be thrown.
        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,
                                     WrongAgentException
        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 the requesting agent may also start or resume or has running. This prevents forbidden data access since the execution context contains the input parameter values of the activity.
        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 will only be returned if the activity can be started or resumed or is already running by the requesting agent.
        Note that the execution mode will always be null. ExecutionContext.resume() stands for whether the activity has been started (is running or suspended instead of selected or activated),
        Throws:
        InvalidActivityStateException - If the activity (process step) is not in a state that allows for starting or resuming, an InvalidActivityStateException will be raised.
        InvalidInstanceStateException - If the instance is not running but stopped, aborted, finished or changed, an InvalidInstanceStateException is thrown.
        WrongAgentException - If the activity can be started or resumed or is already running but not by the calling agent a WrongAgentException will be thrown.

      • getExecutionContexts

        Pair<Map<EBPInstanceReference,​ExecutionContext>,​Map<EBPInstanceReference,​Throwable>> getExecutionContexts​(SessionToken session,
                                                                                                                            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 the requesting agent may also start or resume or has running. This prevents forbidden data access since the execution context contains the input parameter values of the activity.

        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, InvalidInstanceStateException and WrongAgentException.

        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 the requesting agent may start or resume or is currently running. 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. ExecutionContext.resume() stands for whether the activity has been started (is running or suspended instead of selected or activated).
        See Also:
        getExecutionContext(SessionToken, EBPInstanceReference)