/* 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.repository.Deployment;
import org.activiti.engine.repository.ProcessDefinition;
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;
/** Service which provides access to {@link Deployment}s,
* {@link ProcessDefinition}s and {@link ProcessInstance}s.
*
* @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 ActivitiException 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 ActivitiException
* 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 ActivitiException when no process definition is deployed with the given key.
*/
ProcessInstance startProcessInstanceByKey(String processDefinitionKey, Map<String, Object> 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 ActivitiException when no process definition is deployed with the given key.
*/
ProcessInstance startProcessInstanceByKey(String processDefinitionKey, String businessKey, Map<String, Object> 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 ActivitiException 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 ActivitiException 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 ActivitiException when no process definition is deployed with the given key.
*/
ProcessInstance startProcessInstanceById(String processDefinitionId, Map<String, Object> 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 ActivitiException when no process definition is deployed with the given key.
*/
ProcessInstance startProcessInstanceById(String processDefinitionId, String businessKey, Map<String, Object> variables);
/**
* <p>Signals the process engine that a message is received and starts a new
* {@link ProcessInstance}.</p>
*
* <p>Calling this method can have two different outcomes:
* <ul>
* <li>If the message name is associated with a message start event, a new
* process instance is started.</li>
* <li>If no subscription to a message with the given name exists, {@link ActivitiException}
* is thrown</li>
* </ul>
* </p>
*
* @param messageName
* the 'name' of the message as specified as an attribute on the
* bpmn20 {@code <message name="messageName" />} 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);
/**
* <p>Signals the process engine that a message is received and starts a new
* {@link ProcessInstance}.</p>
*
* 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 <message name="messageName" />} 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);
/**
* <p>Signals the process engine that a message is received and starts a new
* {@link ProcessInstance}.</p>
*
* 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 <message name="messageName" />} 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<String, Object> processVariables);
/**
* <p>Signals the process engine that a message is received and starts a new
* {@link ProcessInstance}.</p>
*
* 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 <message name="messageName" />} 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<String, Object> 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 ActivitiException when no process instance is found with the given id.
*/
void deleteProcessInstance(String processInstanceId, String deleteReason);
/** 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 ActivitiException when no execution exists with the given executionId.
*/
List<String> 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 ActivitiException 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 ActivitiException when no execution is found for the given executionId.
*/
void signal(String executionId, Map<String, Object> processVariables);
// 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 ActivitiException when no execution is found for the given executionId. */
Map<String, Object> 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 ActivitiException when no execution is found for the given executionId. */
Map<String, Object> 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 ActivitiException when no execution is found for the given executionId. */
Map<String, Object> getVariables(String executionId, Collection<String> 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 ActivitiException when no execution is found for the given executionId. */
Map<String, Object> getVariablesLocal(String executionId, Collection<String> 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 ActivitiException 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 ActivitiException 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 ActivitiException 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 ActivitiException when no execution is found for the given executionId. */
void setVariables(String executionId, Map<String, ? extends Object> 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 ActivitiException when no execution is found for the given executionId. */
void setVariablesLocal(String executionId, Map<String, ? extends Object> 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<String> 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<String> 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 ActivitiException if no such processInstance can be found or if 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 ActivitiException if no such processInstance can be found or 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.<p/>
*
* <strong>NOTE:</strong> 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.<p/>
*
* <strong>NOTE:</strong> 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<String, Object> 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 ActivitiException if no such execution exists or 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 ActivitiException if no such execution exists or if the execution
* has not subscribed to the signal
*/
void signalEventReceived(String signalName, String executionId, Map<String, Object> 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 ActivitiException if no such execution exists or 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 ActivitiException if no such execution exists or if the execution
* has not subscribed to the signal
*/
void messageEventReceived(String messageName, String executionId, Map<String, Object> processVariables);
}