Package org.apache.commons.jexl3

Class JexlFeatures

java.lang.Object
org.apache.commons.jexl3.JexlFeatures
public final class JexlFeatures extends 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 Details

  • Constructor Details

    • 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, Set<String> r, Predicate<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 Details

    • createAll

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

    • createDefault

      public static JexlFeatures createDefault()
      Creates a default features set suitable for basic but complete scripting needs.

      Maximizes compatibility with older version scripts (before 3.3), new projects should use createScript() or equivalent features as a base.

      The following scripting features are enabled:

      Returns:
      a new instance of a default scripting 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 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(Object obj)
      Overrides:
      equals in class 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

    • getFlags

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

    • getReservedNames

      public Set<String> getReservedNames()
      Returns:
      the (unmodifiable) set of reserved names.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class 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(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 Predicate<String> namespaceTest()
      Returns:
      the declared namespaces test.

    • namespaceTest

      public JexlFeatures namespaceTest(Predicate<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(Collection<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

    • 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