org.camunda.bpm.engine.runtime.CaseExecutionCommandBuilder Maven / Gradle / Ivy
/*
* Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH
* under one or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information regarding copyright
* ownership. Camunda licenses this file to you under the Apache License,
* Version 2.0; 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.camunda.bpm.engine.runtime;
import java.util.Collection;
import java.util.Map;
import org.camunda.bpm.engine.CaseService;
import org.camunda.bpm.engine.ProcessEngineException;
import org.camunda.bpm.engine.exception.NotAllowedException;
import org.camunda.bpm.engine.exception.NotFoundException;
import org.camunda.bpm.engine.exception.NotValidException;
import org.camunda.bpm.model.cmmn.instance.CaseTask;
import org.camunda.bpm.model.cmmn.instance.HumanTask;
import org.camunda.bpm.model.cmmn.instance.ProcessTask;
import org.camunda.bpm.model.cmmn.instance.Stage;
import org.camunda.bpm.model.cmmn.instance.Task;
/**
* A fluent builder for defining a command to execute for a case execution.
*
* This fluent builder offers different points to execute a defined command:
*
* - {@link #execute()}
* - {@link #manualStart()}
* - {@link #disable()}
* - {@link #reenable()}
* - {@link #complete()}
* - {@link #close()}
*
*
*
* The entry point to use this fluent builder is {@link 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
*
*/
public interface CaseExecutionCommandBuilder {
/**
* 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.
*
* @param variableName the name of the variable to set
* @param variableValue the value of the variable to set
*
* @return the builder
*
* @throws NotValidException when the given variable name is null or the same variable
* should be removed in the same command
*/
CaseExecutionCommandBuilder setVariable(String variableName, Object variableValue);
/**
* 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.
*
* @param variables the map of variables
*
* @return the builder
*
* @throws NotValidException when one of the passed variables should be removed
* in the same command
*/
CaseExecutionCommandBuilder setVariables(Map variables);
/**
* Pass a local variable to the case execution (not considering parent scopes).
*
* Invoking this method multiple times allows passing multiple variables.
*
* @param variableName the name of the variable to set
* @param variableValue the value of the variable to set
*
* @return the builder
*
* @throws NotValidException when the given variable name is null or the same variable
* should be removed in the same command
*/
CaseExecutionCommandBuilder setVariableLocal(String variableName, Object variableValue);
/**
* Pass a map of variables to the case execution (not considering parent scopes).
*
* Invoking this method multiple times allows passing multiple variables.
*
* @param variables the map of variables
*
* @return the builder
*
* @throws NotValidException when one of the passed variables should be removed
* in the same command
*/
CaseExecutionCommandBuilder setVariablesLocal(Map variables);
/**
* Pass a variable name of a variable to be removed for a case execution.
*
* Invoking this method multiple times allows passing multiple variable names.
*
* @param variableName the name of a variable to remove
*
* @return the builder
*
* @throws NotValidException when the given variable name is null or the same variable
* should be set in the same command
*/
CaseExecutionCommandBuilder removeVariable(String variableName);
/**
* 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.
*
* @param variableNames a collection of names of variables to remove
*
* @return the builder
*
* @throws NotValidException when one of the passed variables should be set
* in the same command
*/
CaseExecutionCommandBuilder removeVariables(Collection variableNames);
/**
* 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.
*
* @param variableName the name of a variable to remove
*
* @return the builder
*
* @throws NotValidException when the given variable name is null or the same
* variable should be set in same command
*/
CaseExecutionCommandBuilder removeVariableLocal(String variableName);
/**
* 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.
*
* @param variableNames a collection of names of variables to remove
*
* @return the builder
*
* @throws NotValidException when one of the passed variables should be set
* in the same command
*/
CaseExecutionCommandBuilder removeVariablesLocal(Collection variableNames);
/**
* Invoking this method will remove and/or set the passed variables.
*
* This behaves as follows:
*
*
* - if at least one variable name of a variable to remove is passed, those
* variables will be removed.
*
* - if at least one local variable name of a local variable to remove is
* passed, those local variables will be removed.
*
* - if at least one variable to add or update is passed, those variables
* will be set for a case execution.
*
* - 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
* @throws NotFoundException when no case execution is found for the
* given case execution id
* @throws ProcessEngineException when an internal exception happens during the execution
* of the command.
*/
void execute();
/**
* Additionally to {@link #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 {@link Stage} or {@link Task} is
* executing in this state:
*
* - {@link Task}: the {@link Task task} will be completed immediately
* - {@link HumanTask}: a new {@link org.camunda.bpm.engine.task.Task user task} will be instantiated
* - {@link ProcessTask}: a new {@link ProcessInstance process instance} will be instantiated
* - {@link CaseTask}: a new {@link CaseInstance case instance} will be instantiated
*
*
*
* @throws NotValidException when the given case execution id is null
* @throws NotFoundException when no case execution is found for the
* given case execution id
* @throws NotAllowedException when the transition is not allowed to be done or
* when the case execution is a case instance
* @throws ProcessEngineException when an internal exception happens during the execution
* of the command.
*/
void manualStart();
/**
* Additionally to {@link #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 {@link Stage} or {@link 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
* @throws NotFoundException when no case execution is found for the
* given case execution id
* @throws NotAllowedException when the transition is not allowed to be done or
* when the case execution is a case instance
* @throws ProcessEngineException when an internal exception happens during the execution
* of the command.
*/
void disable();
/**
* Additionally to {@link #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 {@link Stage} or {@link Task} is waiting
* for a decision to become ACTIVE or DISABLED once again.
*
* @throws NotValidException when the given case execution id is null
* @throws NotFoundException when no case execution is found for the
* given case execution id
* @throws NotAllowedException when the transition is not allowed to be done or
* when the case execution is a case instance
* @throws ProcessEngineException when an internal exception happens during the execution
* of the command.
*/
void reenable();
/**
* Additionally to {@link #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
* {@link Stage} or {@link Task}.
*
* In case of a {@link Stage} the completion can only be performed when the following
* criteria are fulfilled:
*
* - there are no children in the state
ACTIVE
*
*
*
* For a {@link Task} instance, this means its purpose has been accomplished:
*
* - {@link 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
* @throws NotFoundException when no case execution is found for the
* given case execution id
* @throws NotAllowedException when the transition is not allowed to be done
* @throws ProcessEngineException when an internal exception happens during the execution
* of the command.
*/
void complete();
/**
* Additionally to {@link #execute()} the associated case execution will
* be terminated. Therefore there happens a transition to state TERMINATED.
*
* @throws NotValidException when the given case execution id is null
* @throws NotFoundException when no case execution is found for the
* given case execution id
* @throws NotAllowedException when the transition is not allowed to be done or
* when the case execution is a case instance
* @throws ProcessEngineException when an internal exception happens during the execution
* of the command.
*/
void terminate();
/**
* Additionally to {@link #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
* @throws NotFoundException when no case execution is found for the
* given case execution id
* @throws NotAllowedException when the transition is not allowed to be done
* @throws ProcessEngineException when an internal exception happens during the execution
* of the command.
*/
void close();
}