JexlOptions (Apache Commons JEXL 3.7.0 API)
Description: declaration: package: org.apache.commons.jexl3, class: JexlOptions

Package org.apache.commons.jexl3

# Class JexlOptions

java.lang.Object
org.apache.commons.jexl3.JexlOptions

public final class JexlOptions extends Object
Flags and properties that can alter the evaluation behavior. The flags, briefly explained, are the following:

- silent: whether errors throw exception
- safe: whether navigation through null is not an error
- cancellable: whether thread interruption is an error
- lexical: whether redefining local variables is an error
- lexicalShade: whether local variables shade global ones even outside their scope
- strict: whether unknown or unsolvable identifiers are errors
- strictArithmetic: whether null as operand is an error
- sharedInstance: whether these options can be modified at runtime during execution (expert)
- constCapture: whether captured variables will throw an error if an attempt is made to change their value
- strictInterpolation: whether interpolation strings always return a string or attempt to parse and return integer
- booleanLogical: whether logical expressions ("" , ||) coerce their result to boolean

The sensible default is cancellable, strict and strictArithmetic.

This interface replaces the now deprecated JexlEngine.Options.

Since:
  3.2

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JexlOptions()`
  Default ctor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `JexlOptions`
  `copy()`
  Creates a copy of this instance.
  `Collection<String>`
  `getImports()`
  Gets the optional set of imported packages.
  `MathContext`
  `getMathContext()`
  The MathContext instance used for +,-,/,*,% operations on big decimals.
  `int`
  `getMathScale()`
  The BigDecimal scale used for comparison and coercion operations.
  `Map<String,Object>`
  `getNamespaces()`
  Gets the optional map of namespaces.
  `boolean`
  `isAntish()`
  Checks whether evaluation will attempt resolving antish variable names.
  `boolean`
  `isBooleanLogical()`
  Gets whether logical expressions ("" , ||) coerce their result to boolean; if set, an expression like (3 "" 4 "" 5) will evaluate to true.
  `boolean`
  `isCancellable()`
  Checks whether evaluation will throw JexlException.Cancel (true) or return null (false) if interrupted.
  `boolean`
  `isConstCapture()`
  Are lambda captured-variables const?
  `boolean`
  `isLexical()`
  Checks whether runtime variable scope is lexical.
  `boolean`
  `isLexicalShade()`
  Checks whether local variables shade global ones.
  `boolean`
  `isSafe()`
  Checks whether the engine considers null in navigation expression as errors during evaluation.
  `boolean`
  `isSharedInstance()`
  Gets sharing state.
  `boolean`
  `isSilent()`
  Checks whether the engine will throw a `JexlException` when an error is encountered during evaluation.
  `boolean`
  `isStrict()`
  Checks whether the engine considers unknown variables, methods and constructors as errors during evaluation.
  `boolean`
  `isStrictArithmetic()`
  Checks whether the arithmetic triggers errors during evaluation when null is used as an operand.
  `boolean`
  `isStrictInterpolation()`
  Gets the strict-interpolation flag of this options instance.
  `static int`
  `parseFlags(int initial, String... flags)`
  Parses flags by name.
  `JexlOptions`
  `set(JexlEngine jexl)`
  Sets options from engine.
  `JexlOptions`
  `set(JexlOptions src)`
  Sets options from options.
  `void`
  `setAntish(boolean flag)`
  Sets whether the engine will attempt solving antish variable names from context.
  `void`
  `setBooleanLogical(boolean flag)`
  Sets whether logical expressions ("" , ||) coerce their result to boolean.
  `void`
  `setCancellable(boolean flag)`
  Sets whether the engine will throw JexlException.Cancel (true) or return null (false) when interrupted during evaluation.
  `void`
  `setConstCapture(boolean flag)`
  Sets whether lambda captured-variables are const or not.
  `static void`
  `setDefaultFlags(String... flags)`
  Sets the default (static, shared) option flags.
  `void`
  `setFlags(String... opts)`
  Sets this option flags using the +/- syntax.
  `void`
  `setImports(Collection<String> imports)`
  Sets the optional set of imports.
  `void`
  `setLexical(boolean flag)`
  Sets whether the engine uses a strict block lexical scope during evaluation.
  `void`
  `setLexicalShade(boolean flag)`
  Sets whether the engine strictly shades global variables.
  `void`
  `setMathContext(MathContext mcontext)`
  Sets the arithmetic math context.
  `void`
  `setMathScale(int mscale)`
  Sets the arithmetic math scale.
  `void`
  `setNamespaces(Map<String,Object> ns)`
  Sets the optional map of namespaces.
  `void`
  `setSafe(boolean flag)`
  Sets whether the engine considers null in navigation expression as null or as errors during evaluation.
  `void`
  `setSharedInstance(boolean flag)`
  Sets wether these options are immutable at runtime.
  `void`
  `setSilent(boolean flag)`
  Sets whether the engine will throw a `JexlException` when an error is encountered during evaluation.
  `void`
  `setStrict(boolean flag)`
  Sets whether the engine considers unknown variables, methods and constructors as errors during evaluation.
  `void`
  `setStrictArithmetic(boolean stricta)`
  Sets the strict arithmetic flag.
  `void`
  `setStrictInterpolation(boolean strict)`
  Sets the strict interpolation flag.
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### JexlOptions

    public JexlOptions()
    Default ctor.

- ## Method Details

  - ### parseFlags

    public static int parseFlags(int initial, String... flags)
    Parses flags by name.

    A '+flag' or 'flag' will set flag as true, '-flag' set as false. The possible flag names are: cancellable, strict, silent, safe, lexical, antish, lexicalShade

    Parameters:
      `initial` - the initial mask state
      `flags` - the flags to set
    Returns:
      the flag mask updated

  - ### setDefaultFlags

    public static void setDefaultFlags(String... flags)
    Sets the default (static, shared) option flags.

    Whenever possible, we recommend using JexlBuilder methods to unambiguously instantiate a JEXL engine; this method should only be used for testing / validation.

    A '+flag' or 'flag' will set the option named 'flag' as true, '-flag' set as false. The possible flag names are: cancellable, strict, silent, safe, lexical, antish, lexicalShade

    Calling JexlBuilder.setDefaultOptions("+safe") once before JEXL engine creation may ease validating JEXL3.2 in your environment.

    Parameters:
      `flags` - the flags to set

  - ### copy

    public JexlOptions copy()
    Creates a copy of this instance.
    Returns:
      a copy

  - ### getImports

    public Collection<String> getImports()
    Gets the optional set of imported packages.
    Returns:
      the set of imports, may be empty, not null

  - ### getMathContext

    public MathContext getMathContext()
    The MathContext instance used for +,-,/,*,% operations on big decimals.
    Returns:
      the math context

  - ### getMathScale

    public int getMathScale()
    The BigDecimal scale used for comparison and coercion operations.
    Returns:
      the scale

  - ### getNamespaces

    public Map<String,Object> getNamespaces()
    Gets the optional map of namespaces.
    Returns:
      the map of namespaces, may be empty, not null

  - ### isAntish

    public boolean isAntish()
    Checks whether evaluation will attempt resolving antish variable names.
    Returns:
      true if antish variables are solved, false otherwise

  - ### isBooleanLogical

    public boolean isBooleanLogical()
    Gets whether logical expressions ("" , ||) coerce their result to boolean; if set, an expression like (3 "" 4 "" 5) will evaluate to true. If not, it will evaluate to 5. To preserve strict compatibility with 3.4, set the flag to true.
    Returns:
      true if short-circuit logicals coerce their result to boolean, false otherwise
    Since:
      3.5.0

  - ### isCancellable

    public boolean isCancellable()
    Checks whether evaluation will throw JexlException.Cancel (true) or return null (false) if interrupted.
    Returns:
      true when cancellable, false otherwise

  - ### isConstCapture

    public boolean isConstCapture()
    Are lambda captured-variables const?
    Returns:
      true if lambda captured-variables are const, false otherwise

  - ### isLexical

    public boolean isLexical()
    Checks whether runtime variable scope is lexical.

    If true, lexical scope applies to local variables and parameters. Redefining a variable in the same lexical unit will generate errors.

    Returns:
      true if scope is lexical, false otherwise

  - ### isLexicalShade

    public boolean isLexicalShade()
    Checks whether local variables shade global ones.

    After a symbol is defined as local, dereferencing it outside its scope will trigger an error instead of seeking a global variable of the same name. To further reduce potential naming ambiguity errors, global variables (ie non-local) must be declared to be assigned `JexlContext.has(String)` when this flag is on; attempting to set an undeclared global variables will raise an error.

    Returns:
      true if lexical shading is applied, false otherwise

  - ### isSafe

    public boolean isSafe()
    Checks whether the engine considers null in navigation expression as errors during evaluation.
    Returns:
      true if safe, false otherwise

  - ### isSharedInstance

    public boolean isSharedInstance()
    Gets sharing state.
    Returns:
      false if a copy of these options is used during execution, true if those can potentially be modified

  - ### isSilent

    public boolean isSilent()
    Checks whether the engine will throw a `JexlException` when an error is encountered during evaluation.
    Returns:
      true if silent, false otherwise

  - ### isStrict

    public boolean isStrict()
    Checks whether the engine considers unknown variables, methods and constructors as errors during evaluation.
    Returns:
      true if strict, false otherwise

  - ### isStrictArithmetic

    public boolean isStrictArithmetic()
    Checks whether the arithmetic triggers errors during evaluation when null is used as an operand.
    Returns:
      true if strict, false otherwise

  - ### isStrictInterpolation

    public boolean isStrictInterpolation()
    Gets the strict-interpolation flag of this options instance.
    Returns:
      true if interpolation strings always return string, false otherwise

  - ### set

    public JexlOptions set(JexlEngine jexl)
    Sets options from engine.
    Parameters:
      `jexl` - the engine
    Returns:
      `this` instance

  - ### set

    public JexlOptions set(JexlOptions src)
    Sets options from options.
    Parameters:
      `src` - the options
    Returns:
      `this` instance

  - ### setAntish

    public void setAntish(boolean flag)
    Sets whether the engine will attempt solving antish variable names from context.
    Parameters:
      `flag` - true if antish variables are solved, false otherwise

  - ### setBooleanLogical

    public void setBooleanLogical(boolean flag)
    Sets whether logical expressions ("" , ||) coerce their result to boolean.
    Parameters:
      `flag` - true or false

  - ### setCancellable

    public void setCancellable(boolean flag)
    Sets whether the engine will throw JexlException.Cancel (true) or return null (false) when interrupted during evaluation.
    Parameters:
      `flag` - true when cancellable, false otherwise

  - ### setConstCapture

    public void setConstCapture(boolean flag)
    Sets whether lambda captured-variables are const or not.

    When disabled, lambda-captured variables are implicitly converted to read-write local variable (let), when enabled, those are implicitly converted to read-only local variables (const).

    Parameters:
      `flag` - true to enable, false to disable

  - ### setFlags

    public void setFlags(String... opts)
    Sets this option flags using the +/- syntax.
    Parameters:
      `opts` - the option flags

  - ### setImports

    public void setImports(Collection<String> imports)
    Sets the optional set of imports.
    Parameters:
      `imports` - the imported packages

  - ### setLexical

    public void setLexical(boolean flag)
    Sets whether the engine uses a strict block lexical scope during evaluation.
    Parameters:
      `flag` - true if lexical scope is used, false otherwise

  - ### setLexicalShade

    public void setLexicalShade(boolean flag)
    Sets whether the engine strictly shades global variables. Local symbols shade globals after definition and creating global variables is prohibited during evaluation. If setting to lexical shade, lexical scope is also set.
    Parameters:
      `flag` - true if creation is allowed, false otherwise

  - ### setMathContext

    public void setMathContext(MathContext mcontext)
    Sets the arithmetic math context.
    Parameters:
      `mcontext` - the context

  - ### setMathScale

    public void setMathScale(int mscale)
    Sets the arithmetic math scale.
    Parameters:
      `mscale` - the scale

  - ### setNamespaces

    public void setNamespaces(Map<String,Object> ns)
    Sets the optional map of namespaces.
    Parameters:
      `ns` - a namespaces map

  - ### setSafe

    public void setSafe(boolean flag)
    Sets whether the engine considers null in navigation expression as null or as errors during evaluation.

    If safe, encountering null during a navigation expression - dereferencing a method or a field through a null object or property - will not be considered an error but evaluated as null. It is recommended to use setSafe(false) as an explicit default.

    Parameters:
      `flag` - true if safe, false otherwise

  - ### setSharedInstance

    public void setSharedInstance(boolean flag)
    Sets wether these options are immutable at runtime.

    Expert mode; allows instance handled through context to be shared instead of copied.

    Parameters:
      `flag` - true if shared, false if not

  - ### setSilent

    public void setSilent(boolean flag)
    Sets whether the engine will throw a `JexlException` when an error is encountered during evaluation.
    Parameters:
      `flag` - true if silent, false otherwise

  - ### setStrict

    public void setStrict(boolean flag)
    Sets whether the engine considers unknown variables, methods and constructors as errors during evaluation.
    Parameters:
      `flag` - true if strict, false otherwise

  - ### setStrictArithmetic

    public void setStrictArithmetic(boolean stricta)
    Sets the strict arithmetic flag.
    Parameters:
      `stricta` - true or false

  - ### setStrictInterpolation

    public void setStrictInterpolation(boolean strict)
    Sets the strict interpolation flag.

    When strict, interpolation strings composed only of an expression (ie `${...}`) are evaluated as strings; when not strict, integer results are left untouched.

    This can affect the results of expressions like `map.`${key}`` when key is an integer (or a string); it is almost always possible to use `map[key]` to ensure that the key type is not altered.
    Parameters:
      `strict` - true or false

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`