Package org.flowable.variable.api.delegate

# Interface VariableScope

All Superinterfaces:
  `VariableContainer`

All Known Subinterfaces:
  `DelegateExecution`, `DelegatePlanItemInstance`

public interface VariableScope extends VariableContainer
Interface for class that acts as a scope for variables: i.e. the implementation can be used to set and get variables. Variables are typically stored on the 'highest parent'. For executions, this means that when called on an execution the variable will be stored on the process instance execution. Variables can be stored on the actual scope itself though, by calling the xxLocal methods.

Author:
  Tom Baeyens, Joram Barrez

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static VariableScope`
  `empty()`
  `Object`
  `getTransientVariable(String variableName)`
  Similar to `getVariable(String)`, including the searching via the parent scopes, but for transient variables only.
  `Object`
  `getTransientVariableLocal(String variableName)`
  Similar to `getVariableLocal(String)`, but for a transient variable.
  `Map<String,Object>`
  `getTransientVariables()`
  Similar to `getVariables()`, but for transient variables only.
  `Map<String,Object>`
  `getTransientVariablesLocal()`
  Similar to `getVariableLocal(String)`, but for transient variables only.
  `Object`
  `getVariable(String variableName)`
  Returns the variable value for one specific variable.
  `Object`
  `getVariable(String variableName, boolean fetchAllVariables)`
  Similar to `getVariable(String)`, but has an extra flag that indicates whether or not all variables need to be fetched when getting one variable.
  `<T> T`
  `getVariable(String variableName, Class<T> variableClass)`
  Typed version of the `getVariable(String)` method.
  `VariableInstance`
  `getVariableInstance(String variableName)`
  Similar to `getVariable(String)`, but returns a `VariableInstance` instance, which contains more information than just the value.
  `VariableInstance`
  `getVariableInstance(String variableName, boolean fetchAllVariables)`
  Similar to `getVariable(String, boolean)`, but returns an instance of `VariableInstance`, which has some additional information beyond the value.
  `VariableInstance`
  `getVariableInstanceLocal(String variableName)`
  Similar to `getVariableLocal(String)`, but returns an instance of `VariableInstance`, which has some additional information beyond the value.
  `VariableInstance`
  `getVariableInstanceLocal(String variableName, boolean fetchAllVariables)`
  Similar to `getVariableLocal(String, boolean)`, but returns an instance of `VariableInstance`, which has some additional information beyond the value.
  `Map<String,VariableInstance>`
  `getVariableInstances()`
  Returns all variables, as instances of the `VariableInstance` interface, which gives more information than only the value (type, execution id, etc.)
  `Map<String,VariableInstance>`
  `getVariableInstances(Collection<String> variableNames)`
  Similar to `getVariableInstances()`, but limited to only the variables with the provided names.
  `Map<String,VariableInstance>`
  `getVariableInstances(Collection<String> variableNames, boolean fetchAllVariables)`
  Similar to `getVariables(Collection, boolean)` but returns the variables as instances of the `VariableInstance` interface, which gives more information than only the value (type, execution id, etc.)
  `Map<String,VariableInstance>`
  `getVariableInstancesLocal()`
  Returns the variables local to this scope as instances of the `VariableInstance` interface, which provided additional information about the variable.
  `Map<String,VariableInstance>`
  `getVariableInstancesLocal(Collection<String> variableNames)`
  Similar to `getVariableInstances(Collection)`, but only for variables local to this scope.
  `Map<String,VariableInstance>`
  `getVariableInstancesLocal(Collection<String> variableNames, boolean fetchAllVariables)`
  Similar to `getVariableInstances(Collection, boolean)`, but only for variables local to this scope.
  `Object`
  `getVariableLocal(String variableName)`
  Returns the value for the specific variable and only checks this scope and not any parent scope.
  `Object`
  `getVariableLocal(String variableName, boolean fetchAllVariables)`
  Similar to `getVariableLocal(String)`, but has an extra flag that indicates whether or not all variables need to be fetched when getting one variable.
  `<T> T`
  `getVariableLocal(String variableName, Class<T> variableClass)`
  Typed version of the `getVariableLocal(String)` method.
  `Set<String>`
  `getVariableNames()`
  Returns all the names of the variables for this scope and all parent scopes.
  `Set<String>`
  `getVariableNamesLocal()`
  Returns all the names of the variables for this scope (no parent scopes).
  `Map<String,Object>`
  `getVariables()`
  Returns all variables.
  `Map<String,Object>`
  `getVariables(Collection<String> variableNames)`
  Similar to `getVariables()`, but limited to only the variables with the provided names.
  `Map<String,Object>`
  `getVariables(Collection<String> variableNames, boolean fetchAllVariables)`
  Similar to `getVariables(Collection)`, but with a flag that indicates that all variables should be fetched when fetching the specific variables.
  `Map<String,Object>`
  `getVariablesLocal()`
  Returns the variable local to this scope only.
  `Map<String,Object>`
  `getVariablesLocal(Collection<String> variableNames)`
  Similar to `getVariables(Collection)`, but only for variables local to this scope.
  `Map<String,Object>`
  `getVariablesLocal(Collection<String> variableNames, boolean fetchAllVariables)`
  Similar to `getVariables(Collection, boolean)`, but only for variables local to this scope.
  `boolean`
  `hasVariable(String variableName)`
  Returns whether this scope or any parent scope has a specific variable.
  `boolean`
  `hasVariableLocal(String variableName)`
  Returns whether this scope has a specific variable.
  `boolean`
  `hasVariables()`
  Returns whether this scope or any parent scope has variables.
  `boolean`
  `hasVariablesLocal()`
  Returns whether this scope has variables.
  `void`
  `removeTransientVariable(String variableName)`
  Removes a specific transient variable.
  `void`
  `removeTransientVariableLocal(String variableName)`
  Removes a specific transient variable (also searching parent scopes).
  `void`
  `removeTransientVariables()`
  Remove all transient variable of this scope and its parent scopes.
  `void`
  `removeTransientVariablesLocal()`
  Removes all local transient variables.
  `void`
  `removeVariable(String variableName)`
  Removes the variable and creates a new HistoricVariableUpdate.
  `void`
  `removeVariableLocal(String variableName)`
  Removes the local variable and creates a new HistoricVariableUpdate.
  `void`
  `removeVariables()`
  Removes the (local) variables and creates a new HistoricVariableUpdate for each of them.
  `void`
  `removeVariables(Collection<String> variableNames)`
  Removes the variables and creates a new HistoricVariableUpdate for each of them.
  `void`
  `removeVariablesLocal()`
  Removes the (local) variables and creates a new HistoricVariableUpdate for each of them.
  `void`
  `removeVariablesLocal(Collection<String> variableNames)`
  Removes the local variables and creates a new HistoricVariableUpdate for each of them.
  `void`
  `setTransientVariable(String variableName, Object variableValue)`
  Similar to `setVariable(String, Object)`, but the variable is transient: - no history is kept for the variable - the variable is only available until a waitstate is reached in the process - transient variables 'shadow' persistent variable (when getVariable('abc') where 'abc' is both persistent and transient, the transient value is returned.
  `void`
  `setTransientVariableLocal(String variableName, Object variableValue)`
  Similar to `setVariableLocal(String, Object)`, but for a transient variable.
  `void`
  `setTransientVariables(Map<String,Object> transientVariables)`
  Similar to `setVariables(Map)`, but for transient variables.
  `void`
  `setTransientVariablesLocal(Map<String,Object> transientVariables)`
  Similar to `setVariablesLocal(Map)`, but for transient variables.
  `void`
  `setVariable(String variableName, Object value)`
  Sets the variable with the provided name to the provided value.
  `void`
  `setVariable(String variableName, Object value, boolean fetchAllVariables)`
  Similar to `setVariable(String, Object)`, but with an extra flag to indicate whether all variables should be fetched while doing this or not.
  `Object`
  `setVariableLocal(String variableName, Object value)`
  Similar to `setVariable(String, Object)`, but the variable is set to this scope specifically.
  `Object`
  `setVariableLocal(String variableName, Object value, boolean fetchAllVariables)`
  Similar to `setVariableLocal(String, Object)`, but with an extra flag to indicate whether all variables should be fetched while doing this or not.
  `void`
  `setVariables(Map<String,? extends Object> variables)`
  Sets the provided variables to the variable scope.
  `void`
  `setVariablesLocal(Map<String,? extends Object> variables)`
  Similar to `setVariables(Map)`, but the variable are set on this scope specifically.

  ### Methods inherited from interface org.flowable.common.engine.api.variable.VariableContainer

  `getTenantId`

- ## Method Details

  - ### empty

    static VariableScope empty()
    Returns:
      an empty (null object) variable scope.

  - ### getVariables

    Map<String,Object> getVariables()
    Returns all variables. This will include all variables of parent scopes too.

  - ### getVariableInstances

    Map<String,VariableInstance> getVariableInstances()
    Returns all variables, as instances of the `VariableInstance` interface, which gives more information than only the value (type, execution id, etc.)

  - ### getVariables

    Map<String,Object> getVariables(Collection<String> variableNames)
    Similar to `getVariables()`, but limited to only the variables with the provided names.

  - ### getVariableInstances

    Map<String,VariableInstance> getVariableInstances(Collection<String> variableNames)
    Similar to `getVariableInstances()`, but limited to only the variables with the provided names.

  - ### getVariables

    Map<String,Object> getVariables(Collection<String> variableNames, boolean fetchAllVariables)
    Similar to `getVariables(Collection)`, but with a flag that indicates that all variables should be fetched when fetching the specific variables. If set to false, only the specific variables will be fetched. Depending on the use case, this can be better for performance, as it avoids fetching and processing the other variables. However, if the other variables are needed further on, getting them in one go is probably better (and the variables are cached during one Command execution).

  - ### getVariableInstances

    Map<String,VariableInstance> getVariableInstances(Collection<String> variableNames, boolean fetchAllVariables)
    Similar to `getVariables(Collection, boolean)` but returns the variables as instances of the `VariableInstance` interface, which gives more information than only the value (type, execution id, etc.)

  - ### getVariablesLocal

    Map<String,Object> getVariablesLocal()
    Returns the variable local to this scope only. So, in contrary to `getVariables()`, the variables from the parent scope won't be returned.

  - ### getVariableInstancesLocal

    Map<String,VariableInstance> getVariableInstancesLocal()
    Returns the variables local to this scope as instances of the `VariableInstance` interface, which provided additional information about the variable.

  - ### getVariablesLocal

    Map<String,Object> getVariablesLocal(Collection<String> variableNames)
    Similar to `getVariables(Collection)`, but only for variables local to this scope.

  - ### getVariableInstancesLocal

    Map<String,VariableInstance> getVariableInstancesLocal(Collection<String> variableNames)
    Similar to `getVariableInstances(Collection)`, but only for variables local to this scope.

  - ### getVariablesLocal

    Map<String,Object> getVariablesLocal(Collection<String> variableNames, boolean fetchAllVariables)
    Similar to `getVariables(Collection, boolean)`, but only for variables local to this scope.

  - ### getVariableInstancesLocal

    Map<String,VariableInstance> getVariableInstancesLocal(Collection<String> variableNames, boolean fetchAllVariables)
    Similar to `getVariableInstances(Collection, boolean)`, but only for variables local to this scope.

  - ### getVariable

    Object getVariable(String variableName)
    Returns the variable value for one specific variable. Will look in parent scopes when the variable does not exist on this particular scope.
    Specified by:
      `getVariable` in interface `VariableContainer`

  - ### getVariableInstance

    VariableInstance getVariableInstance(String variableName)
    Similar to `getVariable(String)`, but returns a `VariableInstance` instance, which contains more information than just the value.

  - ### getVariable

    Object getVariable(String variableName, boolean fetchAllVariables)
    Similar to `getVariable(String)`, but has an extra flag that indicates whether or not all variables need to be fetched when getting one variable. By default true (for backwards compatibility reasons), which means that calling `getVariable(String)` will fetch all variables, of the current scope and all parent scopes. Setting this flag to false can thus be better for performance. However, variables are cached, and if other variables are used later on, setting this true might actually be better for performance.

  - ### getVariableInstance

    VariableInstance getVariableInstance(String variableName, boolean fetchAllVariables)
    Similar to `getVariable(String, boolean)`, but returns an instance of `VariableInstance`, which has some additional information beyond the value.

  - ### getVariableLocal

    Object getVariableLocal(String variableName)
    Returns the value for the specific variable and only checks this scope and not any parent scope.

  - ### getVariableInstanceLocal

    VariableInstance getVariableInstanceLocal(String variableName)
    Similar to `getVariableLocal(String)`, but returns an instance of `VariableInstance`, which has some additional information beyond the value.

  - ### getVariableLocal

    Object getVariableLocal(String variableName, boolean fetchAllVariables)
    Similar to `getVariableLocal(String)`, but has an extra flag that indicates whether or not all variables need to be fetched when getting one variable. By default true (for backwards compatibility reasons), which means that calling `getVariableLocal(String)` will fetch all variables, of the current scope. Setting this flag to false can thus be better for performance. However, variables are cached, and if other variables are used later on, setting this true might actually be better for performance.

  - ### getVariableInstanceLocal

    VariableInstance getVariableInstanceLocal(String variableName, boolean fetchAllVariables)
    Similar to `getVariableLocal(String, boolean)`, but returns an instance of `VariableInstance`, which has some additional information beyond the value.

  - ### getVariable

    <T> T getVariable(String variableName, Class<T> variableClass)
    Typed version of the `getVariable(String)` method.

  - ### getVariableLocal

    <T> T getVariableLocal(String variableName, Class<T> variableClass)
    Typed version of the `getVariableLocal(String)` method.

  - ### getVariableNames

    Set<String> getVariableNames()
    Returns all the names of the variables for this scope and all parent scopes.
    Specified by:
      `getVariableNames` in interface `VariableContainer`

  - ### getVariableNamesLocal

    Set<String> getVariableNamesLocal()
    Returns all the names of the variables for this scope (no parent scopes).

  - ### setVariable

    void setVariable(String variableName, Object value)
    Sets the variable with the provided name to the provided value. In the case when variable name is an expression which is resolved by expression manager, the value is set in the object resolved from the expression.

    A variable is set according to the following algorithm:

    - If variable name is an expression, resolve expression and set the value on the resolved object.
    - If this scope already contains a variable by the provided name as a local variable, its value is overwritten to the provided value.
    - If this scope does not contain a variable by the provided name as a local variable, the variable is set to this scope's parent scope, if there is one. If there is no parent scope (meaning this scope is the root scope of the hierarchy it belongs to), this scope is used. This applies recursively up the parent scope chain until, if no scope contains a local variable by the provided name, ultimately the root scope is reached and the variable value is set on that scope.
    In practice for most cases, this algorithm will set variables to the scope of the execution at the process instance’s root level, if there is no execution-local variable by the provided name.
    Specified by:
      `setVariable` in interface `VariableContainer`
    Parameters:
      `variableName` - the name of the variable to be set
      `value` - the value of the variable to be set

  - ### setVariable

    void setVariable(String variableName, Object value, boolean fetchAllVariables)
    Similar to `setVariable(String, Object)`, but with an extra flag to indicate whether all variables should be fetched while doing this or not. Variable name expression is not resolved. The variable will be put on the highest possible scope. For an execution this is the process instance execution. If this is not wanted, use the `setVariableLocal(String, Object)` method instead. The default (e.g. when calling `setVariable(String, Object)`), is true, for backwards compatibility reasons. However, in some use cases, it might make sense not to fetch any other variables when setting one variable (for example when doing nothing more than just setting one variable).

  - ### setVariableLocal

    Object setVariableLocal(String variableName, Object value)
    Similar to `setVariable(String, Object)`, but the variable is set to this scope specifically. Variable name is handled as a variable name string without resolving an expression.

  - ### setVariableLocal

    Object setVariableLocal(String variableName, Object value, boolean fetchAllVariables)
    Similar to `setVariableLocal(String, Object)`, but with an extra flag to indicate whether all variables should be fetched while doing this or not.

  - ### setVariables

    void setVariables(Map<String,? extends Object> variables)
    Sets the provided variables to the variable scope.

    Variables are set according algorithm for `setVariable(String, Object)`, applied separately to each variable.

    Parameters:
      `variables` - a map of keys and values for the variables to be set

  - ### setVariablesLocal

    void setVariablesLocal(Map<String,? extends Object> variables)
    Similar to `setVariables(Map)`, but the variable are set on this scope specifically.

  - ### hasVariables

    boolean hasVariables()
    Returns whether this scope or any parent scope has variables.

  - ### hasVariablesLocal

    boolean hasVariablesLocal()
    Returns whether this scope has variables.

  - ### hasVariable

    boolean hasVariable(String variableName)
    Returns whether this scope or any parent scope has a specific variable.
    Specified by:
      `hasVariable` in interface `VariableContainer`

  - ### hasVariableLocal

    boolean hasVariableLocal(String variableName)
    Returns whether this scope has a specific variable.

  - ### removeVariable

    void removeVariable(String variableName)
    Removes the variable and creates a new HistoricVariableUpdate.

  - ### removeVariableLocal

    void removeVariableLocal(String variableName)
    Removes the local variable and creates a new HistoricVariableUpdate.

  - ### removeVariables

    void removeVariables(Collection<String> variableNames)
    Removes the variables and creates a new HistoricVariableUpdate for each of them.

  - ### removeVariablesLocal

    void removeVariablesLocal(Collection<String> variableNames)
    Removes the local variables and creates a new HistoricVariableUpdate for each of them.

  - ### removeVariables

    void removeVariables()
    Removes the (local) variables and creates a new HistoricVariableUpdate for each of them.

  - ### removeVariablesLocal

    void removeVariablesLocal()
    Removes the (local) variables and creates a new HistoricVariableUpdate for each of them.

  - ### setTransientVariable

    void setTransientVariable(String variableName, Object variableValue)
    Similar to `setVariable(String, Object)`, but the variable is transient: - no history is kept for the variable - the variable is only available until a waitstate is reached in the process - transient variables 'shadow' persistent variable (when getVariable('abc') where 'abc' is both persistent and transient, the transient value is returned.
    Specified by:
      `setTransientVariable` in interface `VariableContainer`

  - ### setTransientVariableLocal

    void setTransientVariableLocal(String variableName, Object variableValue)
    Similar to `setVariableLocal(String, Object)`, but for a transient variable. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### setTransientVariables

    void setTransientVariables(Map<String,Object> transientVariables)
    Similar to `setVariables(Map)`, but for transient variables. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### getTransientVariable

    Object getTransientVariable(String variableName)
    Similar to `getVariable(String)`, including the searching via the parent scopes, but for transient variables only. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### getTransientVariables

    Map<String,Object> getTransientVariables()
    Similar to `getVariables()`, but for transient variables only. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### setTransientVariablesLocal

    void setTransientVariablesLocal(Map<String,Object> transientVariables)
    Similar to `setVariablesLocal(Map)`, but for transient variables. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### getTransientVariableLocal

    Object getTransientVariableLocal(String variableName)
    Similar to `getVariableLocal(String)`, but for a transient variable. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### getTransientVariablesLocal

    Map<String,Object> getTransientVariablesLocal()
    Similar to `getVariableLocal(String)`, but for transient variables only. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### removeTransientVariableLocal

    void removeTransientVariableLocal(String variableName)
    Removes a specific transient variable (also searching parent scopes). See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### removeTransientVariable

    void removeTransientVariable(String variableName)
    Removes a specific transient variable. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### removeTransientVariables

    void removeTransientVariables()
    Remove all transient variable of this scope and its parent scopes. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.

  - ### removeTransientVariablesLocal

    void removeTransientVariablesLocal()
    Removes all local transient variables. See `setTransientVariable(String, Object)` for the rules on 'transient' variables.