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

    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 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:

        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:

        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.

      • terminate

        void terminate()

        Additionally to 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
        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.

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