Class JexlFeatures


  • public final class JexlFeatures
    extends java.lang.Object
    A set of language feature options.

    These control syntactical constructs that will throw JexlException.Feature exceptions (a subclass of JexlException.Parsing) when disabled.

    It is recommended to be explicit in choosing the features you need rather than rely on the default constructor: the 2 convenience methods createNone() and createAll() are the recommended starting points to selectively enable or disable chosen features.

    • Registers: register syntax (#number), used internally for {g,s}etProperty
    • Reserved Names: a set of reserved variable names that can not be used as local variable (or parameter) names
    • Global Side Effect : assigning/modifying values on global variables (=, += , -=, ...)
    • Lexical: lexical scope, prevents redefining local variables
    • Lexical Shade: local variables shade globals, prevents confusing a global variable with a local one
    • Side Effect : assigning/modifying values on any variables or left-value
    • Constant Array Reference: ensures array references only use constants;they should be statically solvable.
    • New Instance: creating an instance using new(...)
    • Loops: loop constructs (while(true), for(...))
    • Lambda: function definitions (()->{...}, function(...) ).
    • Method calls: calling methods (obj.method(...) or obj['method'](...)); when disabled, leaves function calls - including namespace prefixes - available
    • Structured literals: arrays, lists, maps, sets, ranges
    • Pragma: pragma construct as in #pragma x y
    • Annotation: @annotation statement;
    • Thin-arrow: use the thin-arrow, ie -> for lambdas as in x -> x + x
    • Fat-arrow: use the fat-arrow, ie => for lambdas as in x => x + x
    • Namespace pragma: whether the #pragma jexl.namespace.ns namespace syntax is allowed
    • Import pragma: whether the #pragma jexl.import fully.qualified.class.name syntax is allowed
    • Comparator names: whether the comparator operator names can be used (as in gt for >, lt for <, ...)
    • Pragma anywhere: whether pragma, that are not statements and handled before execution begins, can appear anywhere in the source or before any statements - ie at the beginning of a script.
    • Const Capture: whether variables captured by lambdas are read-only (aka const, same as Java) or read-write.
    Since:
    3.2
    • Field Detail

      • TEST_STR_FALSE

        public static final java.util.function.Predicate<java.lang.String> TEST_STR_FALSE
        The false predicate.
      • F_NAMES

        private static final java.lang.String[] F_NAMES
        Te feature names (for toString()).
      • RESERVED

        public static final int RESERVED
        Reserved future feature ordinal (unused as of 3.3.1).
        See Also:
        Constant Field Values
      • SIDE_EFFECT

        public static final int SIDE_EFFECT
        Side effects feature ordinal.
        See Also:
        Constant Field Values
      • SIDE_EFFECT_GLOBAL

        public static final int SIDE_EFFECT_GLOBAL
        Global side effects feature ordinal.
        See Also:
        Constant Field Values
      • ARRAY_REF_EXPR

        public static final int ARRAY_REF_EXPR
        Expressions allowed in array reference ordinal.
        See Also:
        Constant Field Values
      • NEW_INSTANCE

        public static final int NEW_INSTANCE
        New-instance feature ordinal.
        See Also:
        Constant Field Values
      • METHOD_CALL

        public static final int METHOD_CALL
        Lambda feature ordinal.
        See Also:
        Constant Field Values
      • STRUCTURED_LITERAL

        public static final int STRUCTURED_LITERAL
        Structured literal feature ordinal.
        See Also:
        Constant Field Values
      • ANNOTATION

        public static final int ANNOTATION
        Annotation feature ordinal.
        See Also:
        Constant Field Values
      • LEXICAL_SHADE

        public static final int LEXICAL_SHADE
        Lexical shade feature ordinal.
        See Also:
        Constant Field Values
      • THIN_ARROW

        public static final int THIN_ARROW
        Thin-arrow lambda syntax.
        See Also:
        Constant Field Values
      • NS_PRAGMA

        public static final int NS_PRAGMA
        Namespace pragma feature ordinal.
        See Also:
        Constant Field Values
      • IMPORT_PRAGMA

        public static final int IMPORT_PRAGMA
        Import pragma feature ordinal.
        See Also:
        Constant Field Values
      • COMPARATOR_NAMES

        public static final int COMPARATOR_NAMES
        Comparator names (legacy) syntax.
        See Also:
        Constant Field Values
      • PRAGMA_ANYWHERE

        public static final int PRAGMA_ANYWHERE
        The pragma anywhere feature ordinal.
        See Also:
        Constant Field Values
      • CONST_CAPTURE

        public static final int CONST_CAPTURE
        Captured variables are const.
        See Also:
        Constant Field Values
      • ALL_FEATURES

        private static final long ALL_FEATURES
        All features. N.B. ensure this is updated if additional features are added.
        See Also:
        Constant Field Values
      • DEFAULT_FEATURES

        private static final long DEFAULT_FEATURES
        The default features flag mask.

        Meant for compatibility with scripts written before 3.3.1

        See Also:
        Constant Field Values
      • SCRIPT_FEATURES

        private static final long SCRIPT_FEATURES
        The canonical scripting (since 3.3.1) features flag mask based on the original default.

        Adds lexical, lexical-shade and const-capture but removes comparator-names and pragma-anywhere

        See Also:
        Constant Field Values
      • RESERVED_WORDS

        private static final java.util.Set<java.lang.String> RESERVED_WORDS
        Protected future syntactic elements.

        throw, switch, case, default, class, instanceof, jexl, $jexl

        Since:
        3.3.1
      • flags

        private long flags
        The feature flags.
      • reservedNames

        private java.util.Set<java.lang.String> reservedNames
        The set of reserved names, aka global variables that can not be masked by local variables or parameters.
      • nameSpaces

        private java.util.function.Predicate<java.lang.String> nameSpaces
        The namespace names.
    • Constructor Detail

      • JexlFeatures

        public JexlFeatures()
        Creates default instance, equivalent to the result of calling the preferred alternative createDefault()
      • JexlFeatures

        public JexlFeatures​(JexlFeatures features)
        Copy constructor.
        Parameters:
        features - the feature to copy from
      • JexlFeatures

        protected JexlFeatures​(long f,
                               java.util.Set<java.lang.String> r,
                               java.util.function.Predicate<java.lang.String> n)
        An all member constructor for derivation.

        Not respecting immutability or thread-safety constraints for this class constructor arguments will likely result in unexpected behavior.

        Parameters:
        f - flag
        r - reserved variable names; must be an immutable Set or thread-safe (concurrent or synchronized set)
        n - namespace predicate; must be stateless or thread-safe
    • Method Detail

      • createAll

        public static JexlFeatures createAll()
        Creates an all features enabled set.
        Returns:
        a new instance of all features set
        Since:
        3.3.1
      • createNone

        public static JexlFeatures createNone()
        Creates an empty feature set.

        This is the strictest base-set since no feature is allowed, suitable as-is only for the simplest expressions.

        Returns:
        a new instance of an empty features set
        Since:
        3.3.1
      • createScript

        public static JexlFeatures createScript()
        The modern scripting features set.

        This is the recommended set for new projects.

        All default features with the following differences:

        It also adds a set of reserved words to enable future unencumbered syntax evolution: try, catch, throw, finally, switch, case, default, class, instanceof

        Returns:
        a new instance of a modern scripting features set
        Since:
        3.3.1
      • stringify

        public static java.lang.String stringify​(int feature)
        The text corresponding to a feature code.
        Parameters:
        feature - the feature number
        Returns:
        the feature name
      • annotation

        public JexlFeatures annotation​(boolean flag)
        Sets whether annotation constructs are enabled.

        When disabled, parsing a script/expression using syntactic annotation constructs (@annotation) will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • arrayReferenceExpr

        public JexlFeatures arrayReferenceExpr​(boolean flag)
        Sets whether array references expressions are enabled.

        When disabled, parsing a script/expression using 'obj[ ref ]' where ref is not a string or integer literal will throw a parsing exception;

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • comparatorNames

        public JexlFeatures comparatorNames​(boolean flag)
        Sets whether the legacy comparison operator names syntax is enabled.

        When disabled, comparison operators names (eq;ne;le;lt;ge;gt) will be treated as plain identifiers.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
        Since:
        3.3
      • constCapture

        public JexlFeatures constCapture​(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
        Returns:
        this features instance
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • fatArrow

        public JexlFeatures fatArrow​(boolean flag)
        Sets whether fat-arrow lambda syntax is enabled.

        When disabled, parsing a script/expression using syntactic fat-arrow (=<) will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
        Since:
        3.3
      • getFeature

        private boolean getFeature​(int feature)
        Gets a feature flag value.
        Parameters:
        feature - feature ordinal
        Returns:
        true if on, false if off
      • getFlags

        public long getFlags()
        Returns:
        these features"s flags
      • getReservedNames

        public java.util.Set<java.lang.String> getReservedNames()
        Returns:
        the (unmodifiable) set of reserved names.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • importPragma

        public JexlFeatures importPragma​(boolean flag)
        Sets whether import pragma constructs are enabled.

        When disabled, parsing a script/expression using syntactic import pragma constructs (#pragma jexl.import....) will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
        Since:
        3.3
      • isLexical

        public boolean isLexical()
        Returns:
        whether lexical scope feature is enabled
      • isLexicalShade

        public boolean isLexicalShade()
        Returns:
        whether lexical shade feature is enabled
      • isReservedName

        public boolean isReservedName​(java.lang.String name)
        Checks whether a name is reserved.
        Parameters:
        name - the name to check
        Returns:
        true if reserved, false otherwise
      • lambda

        public JexlFeatures lambda​(boolean flag)
        Sets whether lambda/function constructs are enabled.

        When disabled, parsing a script/expression using syntactic lambda constructs (->,function) will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • lexical

        public JexlFeatures lexical​(boolean flag)
        Sets whether syntactic lexical mode is enabled.
        Parameters:
        flag - true means syntactic lexical function scope is in effect, false implies non-lexical scoping
        Returns:
        this features instance
      • lexicalShade

        public JexlFeatures lexicalShade​(boolean flag)
        Sets whether syntactic lexical shade is enabled.
        Parameters:
        flag - true means syntactic lexical shade is in effect and implies lexical scope
        Returns:
        this features instance
      • localVar

        public JexlFeatures localVar​(boolean flag)
        Sets whether local variables are enabled.

        When disabled, parsing a script/expression using a local variable or parameter syntax will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • loops

        public JexlFeatures loops​(boolean flag)
        Sets whether looping constructs are enabled.

        When disabled, parsing a script/expression using syntactic looping constructs (for,while) will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • methodCall

        public JexlFeatures methodCall​(boolean flag)
        Sets whether method calls expressions are enabled.

        When disabled, parsing a script/expression using 'obj.method()' will throw a parsing exception;

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • namespacePragma

        public JexlFeatures namespacePragma​(boolean flag)
        Sets whether namespace pragma constructs are enabled.

        When disabled, parsing a script/expression using syntactic namespace pragma constructs (#pragma jexl.namespace....) will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
        Since:
        3.3
      • namespaceTest

        public java.util.function.Predicate<java.lang.String> namespaceTest()
        Returns:
        the declared namespaces test.
      • namespaceTest

        public JexlFeatures namespaceTest​(java.util.function.Predicate<java.lang.String> names)
        Sets a test to determine namespace declaration.
        Parameters:
        names - the name predicate
        Returns:
        this features instance
      • newInstance

        public JexlFeatures newInstance​(boolean flag)
        Sets whether creating new instances is enabled.

        When disabled, parsing a script/expression using 'new(...)' will throw a parsing exception; using a class as functor will fail at runtime.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • pragma

        public JexlFeatures pragma​(boolean flag)
        Sets whether pragma constructs are enabled.

        When disabled, parsing a script/expression using syntactic pragma constructs (#pragma) will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • pragmaAnywhere

        public JexlFeatures pragmaAnywhere​(boolean flag)
        Sets whether pragma constructs can appear anywhere in the code.
        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
        Since:
        3.3
      • register

        public JexlFeatures register​(boolean flag)
        Sets whether register are enabled.

        This is mostly used internally during execution of JexlEngine.{g,s}etProperty.

        When disabled, parsing a script/expression using the register syntax will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • reservedNames

        public JexlFeatures reservedNames​(java.util.Collection<java.lang.String> names)
        Sets a collection of reserved r precluding those to be used as local variables or parameter r.
        Parameters:
        names - the r to reserve
        Returns:
        this features instance
      • script

        public JexlFeatures script​(boolean flag)
        Sets whether scripts constructs are enabled.

        When disabled, parsing a script using syntactic script constructs (statements, ...) will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • setFeature

        private void setFeature​(int feature,
                                boolean flag)
        Sets a feature flag.
        Parameters:
        feature - the feature ordinal
        flag - turn-on, turn off
      • sideEffect

        public JexlFeatures sideEffect​(boolean flag)
        Sets whether side effect expressions are enabled.

        When disabled, parsing a script/expression using syntactical constructs modifying variables or members will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • sideEffectGlobal

        public JexlFeatures sideEffectGlobal​(boolean flag)
        Sets whether side effect expressions on global variables (aka non-local) are enabled.

        When disabled, parsing a script/expression using syntactical constructs modifying variables including all potentially ant-ish variables will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • structuredLiteral

        public JexlFeatures structuredLiteral​(boolean flag)
        Sets whether array/map/set literal expressions are enabled.

        When disabled, parsing a script/expression creating one of these literals will throw a parsing exception;

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
      • supportsAnnotation

        public boolean supportsAnnotation()
        Returns:
        true if annotation are enabled, false otherwise
      • supportsArrayReferenceExpr

        public boolean supportsArrayReferenceExpr()
        Returns:
        true if array references can contain method call expressions, false otherwise
      • supportsComparatorNames

        public boolean supportsComparatorNames()
        Returns:
        true if legacy comparison operator names syntax is enabled, false otherwise
        Since:
        3.3
      • supportsConstCapture

        public boolean supportsConstCapture()
        Returns:
        true if lambda captured-variables are const, false otherwise
      • supportsExpression

        public boolean supportsExpression()
        Returns:
        true if expressions (aka not scripts) are enabled, false otherwise
      • supportsFatArrow

        public boolean supportsFatArrow()
        Returns:
        true if fat-arrow lambda syntax is enabled, false otherwise
        Since:
        3.3
      • supportsImportPragma

        public boolean supportsImportPragma()
        Returns:
        true if import pragma are enabled, false otherwise
        Since:
        3.3
      • supportsLambda

        public boolean supportsLambda()
        Returns:
        true if lambda are enabled, false otherwise
      • supportsLocalVar

        public boolean supportsLocalVar()
        Returns:
        true if local variables syntax is enabled
      • supportsLoops

        public boolean supportsLoops()
        Returns:
        true if loops are enabled, false otherwise
      • supportsMethodCall

        public boolean supportsMethodCall()
        Returns:
        true if array references can contain expressions, false otherwise
      • supportsNamespacePragma

        public boolean supportsNamespacePragma()
        Returns:
        true if namespace pragma are enabled, false otherwise
        Since:
        3.3
      • supportsNewInstance

        public boolean supportsNewInstance()
        Returns:
        true if creating new instances is enabled, false otherwise
      • supportsPragma

        public boolean supportsPragma()
        Returns:
        true if namespace pragma are enabled, false otherwise
      • supportsPragmaAnywhere

        public boolean supportsPragmaAnywhere()
        Returns:
        true if pragma constructs can appear anywhere in the code, false otherwise
        Since:
        3.3
      • supportsRegister

        public boolean supportsRegister()
        Returns:
        true if register syntax is enabled
      • supportsScript

        public boolean supportsScript()
        Returns:
        true if scripts are enabled, false otherwise
      • supportsSideEffect

        public boolean supportsSideEffect()
        Returns:
        true if side effects are enabled, false otherwise
      • supportsSideEffectGlobal

        public boolean supportsSideEffectGlobal()
        Returns:
        true if global variables can be assigned
      • supportsStructuredLiteral

        public boolean supportsStructuredLiteral()
        Returns:
        true if array/map/set literal expressions are supported, false otherwise
      • supportsThinArrow

        public boolean supportsThinArrow()
        Returns:
        true if thin-arrow lambda syntax is enabled, false otherwise
        Since:
        3.3
      • thinArrow

        public JexlFeatures thinArrow​(boolean flag)
        Sets whether thin-arrow lambda syntax is enabled.

        When disabled, parsing a script/expression using syntactic thin-arrow (-<) will throw a parsing exception.

        Parameters:
        flag - true to enable, false to disable
        Returns:
        this features instance
        Since:
        3.3