Class JexlOptions


  • public final class JexlOptions
    extends java.lang.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 int ANTISH
      The antish var bit.
      private static int CANCELLABLE
      The cancellable bit.
      private static int CONST_CAPTURE
      The const capture bit.
      private static int DEFAULT
      Default mask .
      private int flags
      The default flags, all but safe.
      private java.util.Collection<java.lang.String> imports
      The imports.
      private static int LEXICAL
      The lexical scope bit.
      private java.math.MathContext mathContext
      The arithmetic math context.
      private int mathScale
      The arithmetic math scale.
      private static java.lang.String[] NAMES
      The flag names ordered.
      private java.util.Map<java.lang.String,​java.lang.Object> namespaces
      The namespaces .
      private static int SAFE
      The safe bit.
      private static int SHADE
      The local shade bit.
      private static int SHARED
      The shared instance bit.
      private static int SILENT
      The silent bit.
      private static int STRICT
      The strict bit.
      private boolean strictArithmetic
      The arithmetic strict math flag.
    • Constructor Summary

      Constructors 
      Constructor Description
      JexlOptions()
      Default ctor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      JexlOptions copy()
      Creates a copy of this instance.
      java.util.Collection<java.lang.String> getImports()
      Gets the optional set of imported packages.
      java.math.MathContext getMathContext()
      The MathContext instance used for +,-,/,*,% operations on big decimals.
      int getMathScale()
      The BigDecimal scale used for comparison and coercion operations.
      java.util.Map<java.lang.String,​java.lang.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..
      private static boolean isSet​(int ordinal, int mask)
      Checks the value of a flag in the mask.
      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, java.lang.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.
      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​(java.lang.String... flags)
      Sets the default (static, shared) option flags.
      void setFlags​(java.lang.String... opts)
      Sets this option flags using the +/- syntax.
      void setImports​(java.util.Collection<java.lang.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​(java.math.MathContext mcontext)
      Sets the arithmetic math context.
      void setMathScale​(int mscale)
      Sets the arithmetic math scale.
      void setNamespaces​(java.util.Map<java.lang.String,​java.lang.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.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

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

      • CONST_CAPTURE

        private static final int CONST_CAPTURE
        The const capture bit.
        See Also:
        Constant Field Values
      • NAMES

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

        private static int DEFAULT
        Default mask .
      • mathContext

        private java.math.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 java.util.Map<java.lang.String,​java.lang.Object> namespaces
        The namespaces .
      • imports

        private java.util.Collection<java.lang.String> imports
        The imports.
    • Constructor Detail

      • JexlOptions

        public JexlOptions()
        Default ctor.
    • Method Detail

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

        public static int parseFlags​(int initial,
                                     java.lang.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
      • 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
      • setDefaultFlags

        public static void setDefaultFlags​(java.lang.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 java.util.Collection<java.lang.String> getImports()
        Gets the optional set of imported packages.
        Returns:
        the set of imports, may be empty, not null
      • getMathContext

        public java.math.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 java.util.Map<java.lang.String,​java.lang.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​(java.lang.String... opts)
        Sets this option flags using the +/- syntax.
        Parameters:
        opts - the option flags
      • setImports

        public void setImports​(java.util.Collection<java.lang.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​(java.math.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​(java.util.Map<java.lang.String,​java.lang.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 java.lang.String toString()
        Overrides:
        toString in class java.lang.Object