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 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
    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
    isCancellable()
    Checks whether evaluation will throw JexlException.Cancel (true) or return null (false) if interrupted.
    boolean
    isConstCapture()
     
    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)
    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
    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)
    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 Details

  • 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

    • 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()
      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 (@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

    • isSharedInstance

      public boolean isSharedInstance()
      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

    • 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

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

    • 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

    • toString

      public String toString()
      Overrides:
      toString in class Object