org.activiti.engine.RuntimeService Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of activiti-engine Show documentation
workflow engine base on bboss and activiti.
The newest version!
/* Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.activiti.engine;

import java.util.Collection;
import java.util.List;
import java.util.Map;

import org.activiti.engine.runtime.Execution;
import org.activiti.engine.runtime.ExecutionQuery;
import org.activiti.engine.runtime.NativeExecutionQuery;
import org.activiti.engine.runtime.NativeProcessInstanceQuery;
import org.activiti.engine.runtime.ProcessInstance;
import org.activiti.engine.runtime.ProcessInstanceQuery;
import org.activiti.engine.task.IdentityLink;
import org.activiti.engine.task.IdentityLinkType;


/** 
 * 
 * @author Tom Baeyens
 * @author Joram Barrez
 * @author Daniel Meyer
 */
public interface RuntimeService {
  
  /** 
   * Starts a new process instance in the latest version of the process definition with the given key.
   * @param processDefinitionKey key of process definition, cannot be null.
   * @throws ActivitiObjectNotFoundException when no process definition is deployed with the given key.
   */
  ProcessInstance startProcessInstanceByKey(String processDefinitionKey);
  
  /**
   * Starts a new process instance in the latest version of the process
   * definition with the given key.
   * 
   * A business key can be provided to associate the process instance with a
   * certain identifier that has a clear business meaning. For example in an
   * order process, the business key could be an order id. This business key can
   * then be used to easily look up that process instance , see
   * {@link ProcessInstanceQuery#processInstanceBusinessKey(String)}. Providing such a business
   * key is definitely a best practice.
   * 
   * Note that a business key MUST be unique for the given process definition.
   * Process instance from different process definition are allowed to have the
   * same business key.
   * 
   * The combination of processdefinitionKey-businessKey must be unique.
   * 
   * @param processDefinitionKey
   *          key of process definition, cannot be null.
   * @param businessKey
   *          a key that uniquely identifies the process instance in the context
   *          or the given process definition.
   * @throws ActivitiObjectNotFoundException
   *           when no process definition is deployed with the given key.
   */
  ProcessInstance startProcessInstanceByKey(String processDefinitionKey, String businessKey);
  
  /** Starts a new process instance in the latest version of the process definition with the given key 
   * @param processDefinitionKey key of process definition, cannot be null.
   * @param variables the variables to pass, can be null.
   * @throws ActivitiObjectNotFoundException when no process definition is deployed with the given key. 
   */
  ProcessInstance startProcessInstanceByKey(String processDefinitionKey, Map variables);
  
  /** 
   * Starts a new process instance in the latest version of the process definition with the given key.
   * 
   * A business key can be provided to associate the process instance with a
   * certain identifier that has a clear business meaning. For example in an
   * order process, the business key could be an order id. This business key can
   * then be used to easily look up that process instance , see
   * {@link ProcessInstanceQuery#processInstanceBusinessKey(String)}. Providing such a business
   * key is definitely a best practice.
   * 
   * Note that a business key MUST be unique for the given process definition.
   * Process instance from different process definition are allowed to have the
   * same business key.
   * 
   * The combination of processdefinitionKey-businessKey must be unique.
   * @param processDefinitionKey key of process definition, cannot be null.
   * @param variables the variables to pass, can be null.
   * @param businessKey a key that uniquely identifies the process instance in the context or the
   *                    given process definition.
   * @throws ActivitiObjectNotFoundException when no process definition is deployed with the given key.
   */
  ProcessInstance startProcessInstanceByKey(String processDefinitionKey, String businessKey, Map variables);

  /** Starts a new process instance in the exactly specified version of the process definition with the given id.
   * @param processDefinitionId the id of the process definition, cannot be null.
   * @throws ActivitiObjectNotFoundException when no process definition is deployed with the given key. 
   */
  ProcessInstance startProcessInstanceById(String processDefinitionId);
  
  /** 
   * Starts a new process instance in the exactly specified version of the process definition with the given id.
   * 
   * A business key can be provided to associate the process instance with a
   * certain identifier that has a clear business meaning. For example in an
   * order process, the business key could be an order id. This business key can
   * then be used to easily look up that process instance , see
   * {@link ProcessInstanceQuery#processInstanceBusinessKey(String)}. Providing such a business
   * key is definitely a best practice.
   * 
   * Note that a business key MUST be unique for the given process definition.
   * Process instance from different process definition are allowed to have the
   * same business key.
   * 
   * @param processDefinitionId the id of the process definition, cannot be null.
   * @param businessKey a key that uniquely identifies the process instance in the context or the
   *                    given process definition.
   * @throws ActivitiObjectNotFoundException when no process definition is deployed with the given key. 
   */
  ProcessInstance startProcessInstanceById(String processDefinitionId, String businessKey);
  
  /** Starts a new process instance in the exactly specified version of the process definition with the given id.
   * @param processDefinitionId the id of the process definition, cannot be null.
   * @param variables variables to be passed, can be null
   * @throws ActivitiObjectNotFoundException when no process definition is deployed with the given key. 
   */
  ProcessInstance startProcessInstanceById(String processDefinitionId, Map variables);
  
  /** 
   * Starts a new process instance in the exactly specified version of the process definition with the given id.
   * 
   * A business key can be provided to associate the process instance with a
   * certain identifier that has a clear business meaning. For example in an
   * order process, the business key could be an order id. This business key can
   * then be used to easily look up that process instance , see
   * {@link ProcessInstanceQuery#processInstanceBusinessKey(String)}. Providing such a business
   * key is definitely a best practice.
   * 
   * Note that a business key MUST be unique for the given process definition.
   * Process instance from different process definition are allowed to have the
   * same business key.
   * 
   * @param processDefinitionId the id of the process definition, cannot be null.
   * @param variables variables to be passed, can be null
   * @throws ActivitiObjectNotFoundException when no process definition is deployed with the given key. 
   */
  ProcessInstance startProcessInstanceById(String processDefinitionId, String businessKey, Map variables);
  
  /**
   * Signals the process engine that a message is received and starts a new 
   * {@link ProcessInstance}.
   * 
   * Calling this method can have two different outcomes:
   * 

   * If the message name is associated with a message start event, a new
   * process instance is started.
   * If no subscription to a message with the given name exists, {@link ActivitiException}
   * is thrown
   * 
   * 
   *  
   * @param messageName
   *          the 'name' of the message as specified as an attribute on the
   *          bpmn20 {@code } element.

   * @return the {@link ProcessInstance} object representing the started process instance
   * 
   * @throws ActivitiExeception if no subscription to a message with the given name exists
   * 
   * @since 5.9
   */
  ProcessInstance startProcessInstanceByMessage(String messageName);
  
  /**
   * Signals the process engine that a message is received and starts a new 
   * {@link ProcessInstance}.
   * 
   * See {@link #startProcessInstanceByMessage(String, Map)}. This method allows 
   * specifying a business key.
   *  
   * @param messageName
   *          the 'name' of the message as specified as an attribute on the
   *          bpmn20 {@code } element.
   * @param businessKey
   *          the business key which is added to the started process instance 
   * 
   * @throws ActivitiExeception if no subscription to a message with the given name exists
   * 
   * @since 5.10
   */
  ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey);
  
  /**
   * Signals the process engine that a message is received and starts a new 
   * {@link ProcessInstance}.
   * 
   * See {@link #startProcessInstanceByMessage(String)}. In addition, this method allows 
   * specifying a the payload of the message as a map of process variables.
   *  
   * @param messageName
   *          the 'name' of the message as specified as an attribute on the
   *          bpmn20 {@code } element.
   * @param processVariables
   *          the 'payload' of the message. The variables are added as processes
   *          variables to the started process instance.
   * @return the {@link ProcessInstance} object representing the started process instance
   * 
   * @throws ActivitiExeception if no subscription to a message with the given name exists
   * 
   * @since 5.9
   */
  ProcessInstance startProcessInstanceByMessage(String messageName, Map processVariables);
  
  /**
   * Signals the process engine that a message is received and starts a new 
   * {@link ProcessInstance}.
   * 
   * See {@link #startProcessInstanceByMessage(String, Map)}. In addition, this method allows 
   * specifying a business key.
   *  
   * @param messageName
   *          the 'name' of the message as specified as an attribute on the
   *          bpmn20 {@code } element.
   * @param businessKey
   *          the business key which is added to the started process instance 
   * @param processVariables
   *          the 'payload' of the message. The variables are added as processes
   *          variables to the started process instance.
   * @return the {@link ProcessInstance} object representing the started process instance
   * 
   * @throws ActivitiExeception if no subscription to a message with the given name exists
   * 
   * @since 5.9
   */
  ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey, Map processVariables);

  /** Delete an existing runtime process instance.
   * @param processInstanceId id of process instance to delete, cannot be null.
   * @param deleteReason reason for deleting, can be null.
   * @throws ActivitiObjectNotFoundException when no process instance is found with the given id.
   */
  void deleteProcessInstance(String processInstanceId, String deleteReason,String bussinessOperation,String bussinessRemark);
    
  /** Finds the activity ids for all executions that are waiting in activities. 
   * This is a list because a single activity can be active multiple times.
   * @param executionId id of the execution, cannot be null.
   * @throws ActivitiObjectNotFoundException when no execution exists with the given executionId. 
   */
  List getActiveActivityIds(String executionId);

  /** Sends an external trigger to an activity instance that is waiting inside the given execution.
   * @param executionId id of execution to signal, cannot be null.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId. 
   */
  void signal(String executionId);
  
  /** Sends an external trigger to an activity instance that is waiting inside the given execution.
   * @param executionId id of execution to signal, cannot be null.
   * @param processVariables a map of process variables
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId. 
   */
  void signal(String executionId, Map processVariables);
  
  // Identity Links ///////////////////////////////////////////////////////////////
  
  /**
   * Involves a user with a process instance. The type of identity link is defined by the
   * given identityLinkType.
   * @param processInstanceId id of the process instance, cannot be null.
   * @param userId id of the user involve, cannot be null.
   * @param identityLinkType type of identityLink, cannot be null (@see {@link IdentityLinkType}).
   * @throws ActivitiObjectNotFoundException when the process instance doesn't exist.
   */
  void addUserIdentityLink(String processInstanceId, String userId, String identityLinkType);
  
  /**
   * Retrieves the {@link IdentityLink}s associated with the given process instance.
   * Such an {@link IdentityLink} informs how a certain user is involved with a process instance.
   */
  List getIdentityLinksForProcessInstance(String instanceId);
  
  // Variables ////////////////////////////////////////////////////////////////////
  
  /** All variables visible from the given execution scope (including parent scopes).
   * @param executionId id of execution, cannot be null.
   * @return the variables or an empty map if no such variables are found.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId. */
  Map getVariables(String executionId);
  
  /** All variable values that are defined in the execution scope, without taking outer scopes into account.
   * If you have many task local variables and you only need a few, consider using {@link #getVariablesLocal(String, Collection)} 
   * for better performance.
   * @param executionId id of execution, cannot be null.
   * @return the variables or an empty map if no such variables are found.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId. */
   Map getVariablesLocal(String executionId);

   /** The variable values for all given variableNames, takes all variables into account which are visible from the given execution scope (including parent scopes). 
   * @param executionId id of execution, cannot be null.
   * @param variableNames the collection of variable names that should be retrieved.
   * @return the variables or an empty map if no such variables are found.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId. */
   Map getVariables(String executionId, Collection variableNames);

   /** The variable values for the given variableNames only taking the given execution scope into account, not looking in outer scopes. 
   * @param executionId id of execution, cannot be null.
   * @param variableNames the collection of variable names that should be retrieved.
   * @return the variables or an empty map if no such variables are found.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId.  */
   Map getVariablesLocal(String executionId, Collection variableNames);

  /** The variable value.  Searching for the variable is done in all scopes that are visible to the given execution (including parent scopes).
   * Returns null when no variable value is found with the given name or when the value is set to null.
   * @param executionId id of execution, cannot be null.
   * @param variableName name of variable, cannot be null.
   * @return the variable value or null if the variable is undefined or the value of the variable is null.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId. */
  Object getVariable(String executionId, String variableName);

  /** The variable value for an execution. Returns the value when the variable is set 
   * for the execution (and not searching parent scopes). Returns null when no variable value is found with the given name or when the value is set to null.  */
  Object getVariableLocal(String executionId, String variableName);

  /** Update or create a variable for an execution.  If the variable is not already existing somewhere in the execution hierarchy,
   * it will be created in the process instance (which is the root execution). 
   * @param executionId id of execution to set variable in, cannot be null.
   * @param variableName name of variable to set, cannot be null.
   * @param value value to set. When null is passed, the variable is not removed,
   * only it's value will be set to null.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId. 
   */
  void setVariable(String executionId, String variableName, Object value);

  /** Update or create a variable for an execution (not considering parent scopes). 
   * If the variable is not already existing, it will be created in the given execution.
   * @param executionId id of execution to set variable in, cannot be null.
   * @param variableName name of variable to set, cannot be null.
   * @param value value to set. When null is passed, the variable is not removed,
   * only it's value will be set to null.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId.  */
  void setVariableLocal(String executionId, String variableName, Object value);

  /** Update or create given variables for an execution (including parent scopes). If the variables are not already existing, they will be created in the process instance 
   * (which is the root execution).
   * @param executionId id of the execution, cannot be null.
   * @param variables map containing name (key) and value of variables, can be null.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId.  */
  void setVariables(String executionId, Map variables);
  
  /** Update or create given variables for an execution (not considering parent scopes). If the variables are not already existing, it will be created in the given execution.
   * @param executionId id of the execution, cannot be null.
   * @param variables map containing name (key) and value of variables, can be null.
   * @throws ActivitiObjectNotFoundException when no execution is found for the given executionId. */
  void setVariablesLocal(String executionId, Map variables);
  
  /**
   * Removes a variable for an execution.
   * @param executionId id of execution to remove variable in.
   * @param variableName name of variable to remove.
   */
  void removeVariable(String executionId, String variableName);
  
  /**
   * Removes a variable for an execution (not considering parent scopes).
   * @param executionId id of execution to remove variable in.
   * @param variableName name of variable to remove.
   */
  void removeVariableLocal(String executionId, String variableName);
  
  /**
   * Removes variables for an execution.
   * @param executionId id of execution to remove variable in.
   * @param variableNames collection containing name of variables to remove.
   */
  void removeVariables(String executionId, Collection variableNames);

  /**
   * Remove variables for an execution (not considering parent scopes).
   * @param executionId id of execution to remove variable in.
   * @param variableNames collection containing name of variables to remove.
   */
  void removeVariablesLocal(String executionId, Collection variableNames);
  
  // Queries ////////////////////////////////////////////////////////
  
  /** Creates a new {@link ExecutionQuery} instance, 
   * that can be used to query the executions and process instances. */
  ExecutionQuery createExecutionQuery();
  
  /**
   * creates a new {@link NativeExecutionQuery} to query {@link Execution}s
   * by SQL directly
   */
  NativeExecutionQuery createNativeExecutionQuery();
  
  /**
   * Creates a new {@link ProcessInstanceQuery} instance, that can be used
   * to query process instances.
   */
  ProcessInstanceQuery createProcessInstanceQuery();

  /**
   * creates a new {@link NativeProcessInstanceQuery} to query {@link ProcessInstance}s 
   * by SQL directly
   */
  NativeProcessInstanceQuery createNativeProcessInstanceQuery();
  
  // Process instance state //////////////////////////////////////////
    
  /**
   * Suspends the process instance with the given id. 
   * 
   * If a process instance is in state suspended, activiti will not 
   * execute jobs (timers, messages) associated with this instance.
   * 
   * If you have a process instance hierarchy, suspending
   * one process instance form the hierarchy will not suspend other 
   * process instances form that hierarchy.
   * 
   *  @throws ActivitiObjectNotFoundException if no such processInstance can be found.
   *  @throws ActivitiException the process instance is already in state suspended.
   */
  void suspendProcessInstanceById(String processInstanceId);
  
  /**
   * Activates the process instance with the given id. 
   * 
   * If you have a process instance hierarchy, suspending
   * one process instance form the hierarchy will not suspend other 
   * process instances form that hierarchy.
   * 
   * @throws ActivitiObjectNotFoundException if no such processInstance can be found. 
   * @throws ActivitiException if the process instance is already in state active.
   */
  void activateProcessInstanceById(String processInstanceId);
  
  // Events ////////////////////////////////////////////////////////////////////////
  
  /**
   * Notifies the process engine that a signal event of name 'signalName' has
   * been received. This method delivers the signal to all executions waiting on
   * the signal. 
   * 
   * NOTE: The waiting executions are notified synchronously. 
   * 
   * @param signalName
   *          the name of the signal event
   */
  void signalEventReceived(String signalName);
  
  /**
   * Notifies the process engine that a signal event of name 'signalName' has
   * been received. This method delivers the signal to all executions waiting on
   * the signal.
   * 
   * NOTE: The waiting executions are notified synchronously.
   * 
   * @param signalName
   *          the name of the signal event
   * @param processVariables
   *          a map of variables added to the execution(s)
   */
  void signalEventReceived(String signalName, Map processVariables);
  
  /**
   * Notifies the process engine that a signal event of name 'signalName' has
   * been received. This method delivers the signal to a single execution, being the 
   * execution referenced by 'executionId'. 
   * The waiting execution is notified synchronously.
   * 
   * @param signalName
   *          the name of the signal event
   * @param executionId
   *          the id of the execution to deliver the signal to
   * @throws ActivitiObjectNotFoundException if no such execution exists.
   * @throws ActivitiException if the execution has not subscribed to the signal.
   */
  void signalEventReceived(String signalName, String executionId);  
  
  /**
   * Notifies the process engine that a signal event of name 'signalName' has
   * been received. This method delivers the signal to a single execution, being the 
   * execution referenced by 'executionId'. 
   * The waiting execution is notified synchronously.
   * 
   * @param signalName
   *          the name of the signal event
   * @param executionId
   *          the id of the execution to deliver the signal to
   * @param processVariables
   *          a map of variables added to the execution(s)
   * @throws ActivitiObjectNotFoundException if no such execution exists.
   * @throws ActivitiException if the execution has not subscribed to the signal
   */
  void signalEventReceived(String signalName, String executionId, Map processVariables);

  /**
   * Notifies the process engine that a message event with name 'messageName' has
   * been received and has been correlated to an execution with id 'executionId'. 
   * 
   * The waiting execution is notified synchronously.
   * 
   * @param messageName
   *          the name of the message event
   * @param executionId
   *          the id of the execution to deliver the message to
   * @throws ActivitiObjectNotFoundException if no such execution exists.
   * @throws ActivitiException if the execution has not subscribed to the signal
   */
  void messageEventReceived(String messageName, String executionId);
  
  /**
   * Notifies the process engine that a message event with the name 'messageName' has
   * been received and has been correlated to an execution with id 'executionId'. 
   * 
   * The waiting execution is notified synchronously.
   * 
   * @param messageName
   *          the name of the message event
   * @param executionId
   *          the id of the execution to deliver the message to
   * @param processVariables
   *          a map of variables added to the execution
   * @throws ActivitiObjectNotFoundException if no such execution exists.
   * @throws ActivitiException if the execution has not subscribed to the signal
   */
  void messageEventReceived(String messageName, String executionId, Map processVariables);

}