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 notan 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)
  The sensible default is cancellable, strict and strictArithmetic.

  This interface replaces the now deprecated JexlEngine.Options.

  Since:
    3.2

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `JexlOptions()` Default ctor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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` | `isCancellable()` Checks whether evaluation will throw JexlException.Cancel (true) or return null (false) if interrupted.
    `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()`
    `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.
    `static int` | `parseFlags(int initial, String... flags)` Parses flags by name.
    `JexlOptions` | `set(JexlEngine jexl)` Set options from engine.
    `JexlOptions` | `set(JexlOptions src)` Set options from options.
    `void` | `setAntish(boolean flag)` Sets whether the engine will attempt solving antish variable names from context.
    `void` | `setCancellable(boolean flag)` Sets whether the engine will throw JexlException.Cancel (true) or return null (false) when interrupted during evaluation.
    `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)` Whether 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.
    `String` | `toString()`

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

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

- - ### Constructor Detail

    - #### JexlOptions

          public JexlOptions()

      Default ctor.

  - ### Method Detail

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

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

    - #### setFlags

          public void setFlags(String... opts)

      Sets this option flags using the +/- syntax.
      Parameters:
        `opts` - the option flags

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

    - #### isAntish

          public boolean isAntish()

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

    - #### isCancellable

          public boolean isCancellable()

      Checks whether evaluation will throw JexlException.Cancel (true) or return null (false) if interrupted.
      Returns:
        true when cancellable, 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 (@link 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

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

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

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

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

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

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

    - #### setSharedInstance

          public void setSharedInstance(boolean flag)

      Whether 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

    - #### isSharedInstance

          public boolean isSharedInstance()

      Returns:
        false if a copy of these options is used during execution, true if those can potentially be modified

    - #### set

          public JexlOptions set(JexlEngine jexl)

      Set options from engine.
      Parameters:
        `jexl` - the engine
      Returns:
        this instance

    - #### set

          public JexlOptions set(JexlOptions src)

      Set options from options.
      Parameters:
        `src` - the options
      Returns:
        this instance

    - #### getNamespaces

          public Map<String,Object> getNamespaces()

      Gets the optional map of namespaces.
      Returns:
        the map of namespaces, may be empty, not null

    - #### setNamespaces

          public void setNamespaces(Map<String,Object> ns)

      Sets the optional map of namespaces.
      Parameters:
        `ns` - a namespaces map

    - #### getImports

          public Collection<String> getImports()

      Gets the optional set of imported packages.
      Returns:
        the set of imports, may be empty, not null

    - #### setImports

          public void setImports(Collection<String> imports)

      Sets the optional set of imports.
      Parameters:
        `imports` - the imported packages

    - #### copy

          public JexlOptions copy()

      Creates a copy of this instance.
      Returns:
        a copy

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

Copyright © 2001–2022 The Apache Software Foundation. All rights reserved.