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
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final int
    The antish var bit.
    private static final int
    The cancellable bit.
    private static int
    Default mask .
    private int
    The default flags, all but safe.
    The imports.
    private static final int
    The lexical scope bit.
    private MathContext
    The arithmetic math context.
    private int
    The arithmetic math scale.
    private static final String[]
    The flag names ordered.
    private Map<String,Object>
    The namespaces .
    private static final int
    The safe bit.
    private static final int
    The local shade bit.
    private static final int
    The shared instance bit.
    private static final int
    The silent bit.
    private static final int
    The strict bit.
    private boolean
    The arithmetic strict math flag.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Default ctor.
  • Method Summary

    Modifier and Type
    Method
    Description
    Creates a copy of this instance.
    Gets the optional set of imported packages.
    The MathContext instance used for +,-,/,*,% operations on big decimals.
    int
    The BigDecimal scale used for comparison and coercion operations.
    Gets the optional map of namespaces.
    boolean
    Checks whether evaluation will attempt resolving antish variable names.
    boolean
    Checks whether evaluation will throw JexlException.Cancel (true) or return null (false) if interrupted.
    boolean
    Checks whether runtime variable scope is lexical.
    boolean
    Checks whether local variables shade global ones.
    boolean
    Checks whether the engine considers null in navigation expression as errors during evaluation..
    private static boolean
    isSet(int ordinal, int mask)
    Checks the value of a flag in the mask.
    boolean
     
    boolean
    Checks whether the engine will throw a JexlException when an error is encountered during evaluation.
    boolean
    Checks whether the engine considers unknown variables, methods and constructors as errors during evaluation.
    boolean
    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.
    private static int
    set(int ordinal, int mask, boolean value)
    Sets the value of a flag in a mask.
    Set options from engine.
    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
    Sets the default (static, shared) option flags.
    void
    setFlags(String... opts)
    Sets this option flags using the +/- syntax.
    void
    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
    Sets the arithmetic math context.
    void
    setMathScale(int mscale)
    Sets the arithmetic math scale.
    void
    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.
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • SHARED

      private static final int SHARED
      The shared instance bit.
      See Also:
    • SHADE

      private static final int SHADE
      The local shade bit.
      See Also:
    • ANTISH

      private static final int ANTISH
      The antish var bit.
      See Also:
    • LEXICAL

      private static final int LEXICAL
      The lexical scope bit.
      See Also:
    • SAFE

      private static final int SAFE
      The safe bit.
      See Also:
    • SILENT

      private static final int SILENT
      The silent bit.
      See Also:
    • STRICT

      private static final int STRICT
      The strict bit.
      See Also:
    • CANCELLABLE

      private static final int CANCELLABLE
      The cancellable bit.
      See Also:
    • NAMES

      private static final String[] NAMES
      The flag names ordered.
    • DEFAULT

      private static int DEFAULT
      Default mask .
    • mathContext

      private MathContext mathContext
      The arithmetic math context.
    • mathScale

      private int mathScale
      The arithmetic math scale.
    • strictArithmetic

      private boolean strictArithmetic
      The arithmetic strict math flag.
    • flags

      private int flags
      The default flags, all but safe.
    • namespaces

      private Map<String,Object> namespaces
      The namespaces .
    • imports

      private Collection<String> imports
      The imports.
  • Constructor Details

    • JexlOptions

      public JexlOptions()
      Default ctor.
  • Method Details

    • set

      private static int set(int ordinal, int mask, boolean value)
      Sets the value of a flag in a mask.
      Parameters:
      ordinal - the flag ordinal
      mask - the flags mask
      value - true or false
      Returns:
      the new flags mask value
    • isSet

      private static boolean isSet(int ordinal, int mask)
      Checks the value of a flag in the mask.
      Parameters:
      ordinal - the flag ordinal
      mask - the flags mask
      Returns:
      the mask value with this flag or-ed in
    • 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