org.camunda.bpm.engine.runtime
Interface CaseExecutionCommandBuilder

All Known Implementing Classes:

CaseExecutionCommandBuilderImpl

public interface CaseExecutionCommandBuilder

A fluent builder for defining a command to execute for a case execution.

This fluent builder offers different points to execute a defined command:

• execute()
• manualStart()
• disable()
• reenable()
• complete()
• close()

The entry point to use this fluent builder is CaseService.withCaseExecution(String). It expects an id of a case execution as parameter.

This fluent builder can be used as follows:

(1) Set and remove case execution variables:

caseService
.withCaseExecution("aCaseDefinitionId")
.setVariable("aVariableName", "aVariableValue")
.setVariable("anotherVariableName", 999)
.removeVariable("aVariableNameToRemove")
.execute();

(2) Set case execution variable and start the case execution manually:

caseService
.withCaseExecution("aCaseDefinitionId")
.setVariable("aVariableName", "aVariableValue")
.manualStart();

etc.

Note: All defined changes for a case execution within this fluent builder will be performed in one command. So for example: if you set and remove variables of a case execution this happens in a single command. This has the effect that if anything went wrong the whole command will be rolled back.

Author:

Roman Smirnov

Method Summary

void	close() Additionally to execute() the associated case instance will be closed, so that no further work or modifications is allowed for the associated case instance.
void	complete() Additionally to execute() the associated case execution will be completed.
void	disable() Additionally to execute() the associated case execution will be disabled.
void	execute() Invoking this method will remove and/or set the passed variables.
void	manualStart() Additionally to execute() the associated case execution will be started manually.
void	reenable() Additionally to execute() the associated case execution will be re-enabled.
CaseExecutionCommandBuilder	removeVariable(String variableName) Pass a variable name of a variable to be removed for a case execution.
CaseExecutionCommandBuilder	removeVariableLocal(String variableName) Pass a variable name of a local variable to be removed for a case execution (not considering parent scopes).
CaseExecutionCommandBuilder	removeVariables(Collection<String> variableNames) Pass a collection of variable names of variables to be removed for a case execution.
CaseExecutionCommandBuilder	removeVariablesLocal(Collection<String> variableNames) Pass a collection of variable names of local variables to be removed for a case execution (not considering parent scopes).
CaseExecutionCommandBuilder	setVariable(String variableName, Object variableValue) Pass a variable to the case execution.
CaseExecutionCommandBuilder	setVariableLocal(String variableName, Object variableValue) Pass a local variable to the case execution (not considering parent scopes).
CaseExecutionCommandBuilder	setVariables(Map<String,Object> variables) Pass a map of variables to the case execution.
CaseExecutionCommandBuilder	setVariablesLocal(Map<String,Object> variables) Pass a map of variables to the case execution (not considering parent scopes).

Method Detail

setVariable

CaseExecutionCommandBuilder setVariable(String variableName,
                                        Object variableValue)

Pass a variable to the case execution. If the variable is not already existing, they will be created in the case instance (which is the root execution) otherwise the existing variable will be updated.

Invoking this method multiple times allows passing multiple variables.

Parameters:

variableName - the name of the variable to set

variableValue - the value of the variable to set

Returns:

the builder

Throws:

NotValidException - when the given variable name is null or the same variable should be removed in the same command

setVariables

CaseExecutionCommandBuilder setVariables(Map<String,Object> variables)

Pass a map of variables to the case execution. If the variables are not already existing, they will be created in the case instance (which is the root execution) otherwise the existing variable will be updated.

Invoking this method multiple times allows passing multiple variables.

Parameters:

variables - the map of variables

Returns:

the builder

Throws:

NotValidException - when one of the passed variables should be removed in the same command

setVariableLocal

CaseExecutionCommandBuilder setVariableLocal(String variableName,
                                             Object variableValue)

Pass a local variable to the case execution (not considering parent scopes).

Invoking this method multiple times allows passing multiple variables.

Parameters:

variableName - the name of the variable to set

variableValue - the value of the variable to set

Returns:

the builder

Throws:

NotValidException - when the given variable name is null or the same variable should be removed in the same command

setVariablesLocal

CaseExecutionCommandBuilder setVariablesLocal(Map<String,Object> variables)

Pass a map of variables to the case execution (not considering parent scopes).

Invoking this method multiple times allows passing multiple variables.

Parameters:

variables - the map of variables

Returns:

the builder

Throws:

NotValidException - when one of the passed variables should be removed in the same command

removeVariable

CaseExecutionCommandBuilder removeVariable(String variableName)

Pass a variable name of a variable to be removed for a case execution.

Invoking this method multiple times allows passing multiple variable names.

Parameters:

variableName - the name of a variable to remove

Returns:

the builder

Throws:

NotValidException - when the given variable name is null or the same variable should be set in the same command

removeVariables

CaseExecutionCommandBuilder removeVariables(Collection<String> variableNames)

Pass a collection of variable names of variables to be removed for a case execution.

Invoking this method multiple times allows passing multiple variable names.

Parameters:

variableNames - a collection of names of variables to remove

Returns:

the builder

Throws:

NotValidException - when one of the passed variables should be set in the same command

removeVariableLocal

CaseExecutionCommandBuilder removeVariableLocal(String variableName)

Pass a variable name of a local variable to be removed for a case execution (not considering parent scopes).

Invoking this method multiple times allows passing multiple variable names.

Parameters:

variableName - the name of a variable to remove

Returns:

the builder

Throws:

NotValidException - when the given variable name is null or the same variable should be set in same command

removeVariablesLocal

CaseExecutionCommandBuilder removeVariablesLocal(Collection<String> variableNames)

Pass a collection of variable names of local variables to be removed for a case execution (not considering parent scopes).

Invoking this method multiple times allows passing multiple variable names.

Parameters:

variableNames - a collection of names of variables to remove

Returns:

the builder

Throws:

NotValidException - when one of the passed variables should be set in the same command

execute

void execute()

Invoking this method will remove and/or set the passed variables.

This behaves as follows:

1. if at least one variable name of a variable to remove is passed, those variables will be removed.
2. if at least one local variable name of a local variable to remove is passed, those local variables will be removed.
3. if at least one variable to add or update is passed, those variables will be set for a case execution.
4. if at least one local variable to add or update is passed, those variables will be set for a case execution.

Throws:

NotValidException - when the given case execution id is null

NotFoundException - when no case execution is found for the given case execution id

ProcessEngineException - when an internal exception happens during the execution of the command.

manualStart

void manualStart()

Additionally to execute() the associated case execution will be started manually. Therefore there happens a transition from the state ENABLED to state ACTIVE.

According to CMMN 1.0 specification the state ACTIVE means, that the with the case execution related Stage or Task is executing in this state:

• Task: the task will be completed immediately
• HumanTask: a new user task will be instantiated
• ProcessTask: a new process instance will be instantiated
• CaseTask: a new case instance will be instantiated

Throws:

NotValidException - when the given case execution id is null

NotFoundException - when no case execution is found for the given case execution id

NotAllowedException - when the transition is not allowed to be done or when the case execution is a case instance

ProcessEngineException - when an internal exception happens during the execution of the command.

disable

void disable()

Additionally to execute() the associated case execution will be disabled. Therefore there happens a transition from the state ENABLED to state DISABLED.

According to CMMN 1.0 specification the state DISABLED means, that the with the case execution related Stage or Task should not be executed in the case instance.

If the given case execution has a parent case execution, that parent case execution will be notified that the given case execution has been disabled. This can lead to a completion of the parent case execution if the completion criteria are fulfilled.

Throws:

NotValidException - when the given case execution id is null

NotFoundException - when no case execution is found for the given case execution id

NotAllowedException - when the transition is not allowed to be done or when the case execution is a case instance

ProcessEngineException - when an internal exception happens during the execution of the command.

reenable

void reenable()

Additionally to execute() the associated case execution will be re-enabled. Therefore there happens a transition from the state DISABLED to state ENABLED.

According to CMMN 1.0 specification the state DISABLED means, that the with the case execution related Stage or Task is waiting for a decision to become ACTIVE or DISABLED once again.

Throws:

NotValidException - when the given case execution id is null

NotFoundException - when no case execution is found for the given case execution id

NotAllowedException - when the transition is not allowed to be done or when the case execution is a case instance

ProcessEngineException - when an internal exception happens during the execution of the command.

complete

void complete()

Additionally to execute() the associated case execution will be completed. Therefore there happens a transition from the state ACTIVE to state COMPLETED.

It is only possible to complete a case execution which is associated with a Stage or Task.

In case of a Stage the completion can only be performed when the following criteria are fulfilled:

• there are no children in the state ACTIVE

For a Task instance, this means its purpose has been accomplished:

• HumanTask has been completed by human.

If the given case execution has a parent case execution, that parent case execution will be notified that the given case execution has been completed. This can lead to a completion of the parent case execution if the completion criteria are fulfilled.

Throws:

NotValidException - when the given case execution id is null

NotFoundException - when no case execution is found for the given case execution id

NotAllowedException - when the transition is not allowed to be done

ProcessEngineException - when an internal exception happens during the execution of the command.

close

void close()

Additionally to execute() the associated case instance will be closed, so that no further work or modifications is allowed for the associated case instance. Therefore there happens a transition from the state COMPLETED to state CLOSED.

Throws:

NotValidException - when the given case execution id is null

NotFoundException - when no case execution is found for the given case execution id

NotAllowedException - when the transition is not allowed to be done

ProcessEngineException - when an internal exception happens during the execution of the command.