JexlBuilder (Apache Commons JEXL 3.7.0 API)
Description: declaration: package: org.apache.commons.jexl3, class: JexlBuilder

Package org.apache.commons.jexl3

# Class JexlBuilder

java.lang.Object
org.apache.commons.jexl3.JexlBuilder

public class JexlBuilder extends Object
Configures and builds a JexlEngine.

The builder allow fine-tuning an engine instance behavior according to various control needs. Check `JexlBuilder()` for permission impacts starting with JEXL 3.3.

Broad configurations elements are controlled through the features (`JexlFeatures`) that can restrict JEXL syntax - for instance, only expressions with no-side effects - and permissions (`JexlPermissions`) that control the visible set of objects - for instance, avoiding access to any object in java.rmi.* -.

Fine error control and runtime-overridable behaviors are implemented through options (`JexlOptions`). Most common flags accessible from the builder are reflected in its options (`options()`).

The `silent` flag tells the engine what to do with the error; when true, errors are logged as warning, when false, they throw `JexlException` exceptions.

The `strict` flag tells the engine when and if null as operand is considered an error. The `safe` flog determines if safe-navigation is used. Safe-navigation allows an evaluation shortcut and return null in expressions that attempts dereferencing null, typically a method call or accessing a property.

The `lexical` and `lexicalShade` flags can be used to enforce a lexical scope for variables and parameters. The `lexicalShade` can be used to further ensure no global variable can be used with the same name as a local one even after it goes out of scope. The corresponding feature flags should be preferred since they will detect violations at parsing time. (see `JexlFeatures`)

The following rules apply on silent and strict flags:

- When "silent" & "not-strict":

  0 & null should be indicators of "default" values so that even in an case of error, something meaningful can still be inferred; may be convenient for configurations.

- When "silent" & "strict":

  One should probably consider using null as an error case - ie, every object manipulated by JEXL should be valued; the ternary operator, especially the '?:' form can be used to workaround exceptional cases. Use case could be configuration with no implicit values or defaults.

- When "not-silent" & "not-strict":

  The error control grain is roughly on par with JEXL 1.0

- When "not-silent" & "strict":

  The finest error control grain is obtained; it is the closest to Java code - still augmented by "script" capabilities regarding automated conversions and type matching.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final int`
  `CACHE_THRESHOLD`
  The default maximum expression length to hit the expression cache.
  `static final JexlFeatures`
  `FULL`
  The full feature set that was the implicit default before JEXL 3.7.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JexlBuilder()`
  Default constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `antish()`
  Is antish resolution enabled?
  `JexlBuilder`
  `antish(boolean flag)`
  Sets whether the engine will resolve antish variable names.
  `JexlArithmetic`
  `arithmetic()`
  Gets the JexlArithmetic instance the engine will use.
  `JexlBuilder`
  `arithmetic(JexlArithmetic a)`
  Sets the JexlArithmetic instance the engine will use.
  `JexlBuilder`
  `booleanLogical(boolean flag)`
  Sets whether logical expressions ("" , ||) coerce their result to boolean.
  `int`
  `cache()`
  Gets the expression cache size the engine will use.
  `JexlBuilder`
  `cache(int size)`
  Sets the expression cache size the engine will use.
  `IntFunction<JexlCache<?,?>>`
  `cacheFactory()`
  Gets the expression-cache factory the engine will use.
  `JexlBuilder`
  `cacheFactory(IntFunction<JexlCache<?,?>> factory)`
  Sets the expression-cache factory the engine will use.
  `int`
  `cacheThreshold()`
  Gets the maximum length for an expression to be cached.
  `JexlBuilder`
  `cacheThreshold(int length)`
  Sets the maximum length for an expression to be cached.
  `Boolean`
  `cancellable()`
  Gets the cancellable information flag
  `JexlBuilder`
  `cancellable(boolean flag)`
  Sets the engine behavior upon interruption: throw an JexlException.Cancel or terminates the current evaluation and return null.
  `Charset`
  `charset()`
  Gets the charset
  `JexlBuilder`
  `charset(Charset arg)`
  Sets the charset to use.
  `boolean`
  `collectAll()`
  Does the variable collection follow strict syntactic rule?
  `JexlBuilder`
  `collectAll(boolean flag)`
  Sets whether the engine variable collectors considers all potential forms of variable syntaxes.
  `int`
  `collectMode()`
  Gets the collection mode.
  `JexlBuilder`
  `collectMode(int mode)`
  Experimental collector mode setter.
  `JexlEngine`
  `create()`
  Create a new engine
  `Boolean`
  `debug()`
  Gets the debug flag.
  `JexlBuilder`
  `debug(boolean flag)`
  Sets whether the engine will report debugging information when error occurs.
  `JexlFeatures`
  `features()`
  Gets the features the engine will use as a base by default.
  `JexlBuilder`
  `features(JexlFeatures f)`
  Sets the features the engine will use as a base by default.
  `Collection<String>`
  `imports()`
  Gets the optional set of imported packages.
  `JexlBuilder`
  `imports(String... imports)`
  Sets the optional set of imports.
  `JexlBuilder`
  `imports(Collection<String> imports)`
  Sets the optional set of imports.
  `boolean`
  `lexical()`
  Deprecated.
  3.5.0
  `JexlBuilder`
  `lexical(boolean flag)`
  Sets whether the engine is in lexical mode.
  `boolean`
  `lexicalShade()`
  Deprecated.
  3.5.0
  `JexlBuilder`
  `lexicalShade(boolean flag)`
  Sets whether the engine is in lexical shading mode.
  `ClassLoader`
  `loader()`
  Gets the classloader
  `JexlBuilder`
  `loader(ClassLoader l)`
  Sets the class loader to use.
  `JexlBuilder`
  `loader(Charset arg)`
  Deprecated.
  since 3.1 use `charset(Charset)` instead
  `org.apache.commons.logging.Log`
  `logger()`
  Gets the logger
  `JexlBuilder`
  `logger(org.apache.commons.logging.Log log)`
  Sets the o.a.c.Log instance to use.
  `Map<String,Object>`
  `namespaces()`
  Gets the map of namespaces.
  `JexlBuilder`
  `namespaces(Map<String,Object> ns)`
  Sets the default namespaces map the engine will use.
  `JexlOptions`
  `options()`
  Gets the current set of options
  `Supplier<org.apache.commons.jexl3.parser.JexlScriptParser>`
  `parserFactory()`
  Gets the Jexl script parser factory the engine will use.
  `JexlBuilder`
  `parserFactory(Supplier<org.apache.commons.jexl3.parser.JexlScriptParser> factory)`
  Sets the Jexl script parser factory the engine will use.
  `JexlPermissions`
  `permissions()`
  Gets the permissions
  `JexlBuilder`
  `permissions(JexlPermissions p)`
  Sets the JexlPermissions instance the engine will use.
  `Boolean`
  `safe()`
  Is it safe to dereference null?
  `JexlBuilder`
  `safe(boolean flag)`
  Sets whether the engine considers dereferencing null in navigation expressions as null or triggers an error.
  `JexlSandbox`
  `sandbox()`
  Gets the sandbox
  `JexlBuilder`
  `sandbox(JexlSandbox box)`
  Sets the sandbox the engine will use.
  `static void`
  `setDefaultFeatures(JexlFeatures features)`
  Sets the default features used when creating a new builder.
  `static void`
  `setDefaultOptions(String... flags)`
  Sets the default option flags used when creating a new engine.
  `static void`
  `setDefaultPermissions(JexlPermissions permissions)`
  Sets the default permissions.
  `Boolean`
  `silent()`
  Is error handling silent?
  `JexlBuilder`
  `silent(boolean flag)`
  Sets whether the engine will throw JexlException during evaluation when an error is triggered.
  `int`
  `stackOverflow()`
  Gets the cache size
  `JexlBuilder`
  `stackOverflow(int size)`
  Sets the number of script/expression evaluations that can be stacked.
  `JexlUberspect.ResolverStrategy`
  `strategy()`
  Gets the JexlUberspect strategy
  `JexlBuilder`
  `strategy(JexlUberspect.ResolverStrategy rs)`
  Sets the JexlUberspect strategy the engine will use.
  `Boolean`
  `strict()`
  Is it strict mode?
  `JexlBuilder`
  `strict(boolean flag)`
  Sets whether the engine considers unknown variables, methods, functions, and constructors as errors or evaluates them as null.
  `JexlBuilder`
  `strictInterpolation(boolean flag)`
  Is interpolation strict?
  `JexlUberspect`
  `uberspect()`
  Gets the uberspect
  `JexlBuilder`
  `uberspect(JexlUberspect u)`
  Sets the JexlUberspect instance the engine will use.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### FULL

    public static final JexlFeatures FULL
    The full feature set that was the implicit default before JEXL 3.7.

    This captures `JexlFeatures.createDefault()` - the feature set the engine used as its fallback throughout 3.x (since 3.3) before the 3.7 hardening. It enables `new(...)`, loops, side-effects, lambdas, method calls, structured literals, pragmas, etc. Use it (or `setDefaultFeatures(JexlFeatures)`) to restore pre-3.7 behavior:

         JexlEngine jexl = new JexlBuilder().features(JexlBuilder.FULL).create();

    `JexlFeatures` instances are mutable; copy this one via `new JexlFeatures(JexlBuilder.FULL)` before customizing it rather than mutating the shared instance.

    Since:
      3.7.0

  - ### CACHE_THRESHOLD

    protected static final int CACHE_THRESHOLD
    The default maximum expression length to hit the expression cache.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### JexlBuilder

    public JexlBuilder()
    Default constructor.

    As of JEXL 3.3, to reduce the security risks inherent to JEXL"s purpose, the builder will use a set of restricted permissions as a default to create the `JexlEngine` instance. This will greatly reduce which classes and methods are visible to JEXL and usable in scripts using default implicit behaviors.

    However, without mitigation, this change will likely break some scripts at runtime, especially those exposing your own class instances through arguments, contexts, or namespaces. The default set of allowed packages and denied classes is described by `JexlPermissions.SECURE` as of JEXL 3.7 (previously `JexlPermissions.RESTRICTED` since 3.3).

    As of JEXL 3.7, the default features also disable `new(...)`, global side-effects, pragmas, and annotations, and enable lexical scoping; loops remain available to scripts (but never to expressions). Scripts using a disabled construct will throw `JexlException.Feature` at parse time unless a permissive feature set is configured.

    The recommended mitigation if your usage of JEXL is impacted is to load a `jexl.yaml` configuration via `JexlConfigLoader` that restores the legacy permissions and features, or to explicitly configure them via `permissions(JexlPermissions)` and `features(JexlFeatures)`. Use `JexlPermissions.logging()` to discover which reflective elements the new algorithm denies.

    Note that an explicit call to `uberspect(JexlUberspect)` will supersede any permissions related behavior by using the `JexlUberspect` provided as argument used as-is in the created `JexlEngine`.

    Since:
      3.3

- ## Method Details

  - ### setDefaultPermissions

    public static void setDefaultPermissions(JexlPermissions permissions)
    Sets the default permissions.
    Parameters:
      `permissions` - the permissions

  - ### setDefaultFeatures

    public static void setDefaultFeatures(JexlFeatures features)
    Sets the default features used when creating a new builder.

    Passing `null` restores the 3.7 hardened default (new-instance, global side-effects, pragmas, and annotations disabled, lexical scoping enabled; see `secureFeatures()`).

    Parameters:
      `features` - the features, or `null` to restore the hardened default
    Since:
      3.7.0

  - ### setDefaultOptions

    public static void setDefaultOptions(String... flags)
    Sets the default option flags used when creating a new engine.

    Delegates to `JexlOptions.setDefaultFlags(String...)`; see that method for the flag-name syntax (`"+flag"`/`"-flag"`) and the available flag names (`cancellable`, `strict`, `silent`, `safe`, `lexical`, `antish`, `lexicalShade`, ...).

    Example: restore safe/antish defaults before creating any engine:

        JexlBuilder.setDefaultOptions("+safe", "+antish");

    Parameters:
      `flags` - the flags to set or clear
    Since:
      3.7.0

  - ### antish

    public boolean antish()
    Is antish resolution enabled?
    Returns:
      whether antish resolution is enabled

  - ### antish

    public JexlBuilder antish(boolean flag)
    Sets whether the engine will resolve antish variable names.
    Parameters:
      `flag` - true means antish resolution is enabled, false disables it
    Returns:
      this builder

  - ### arithmetic

    public JexlArithmetic arithmetic()
    Gets the JexlArithmetic instance the engine will use.
    Returns:
      the arithmetic

  - ### arithmetic

    public JexlBuilder arithmetic(JexlArithmetic a)
    Sets the JexlArithmetic instance the engine will use.
    Parameters:
      `a` - the arithmetic
    Returns:
      this builder

  - ### booleanLogical

    public JexlBuilder booleanLogical(boolean flag)
    Sets whether logical expressions ("" , ||) coerce their result to boolean.
    Parameters:
      `flag` - true or false
    Returns:
      this builder

  - ### cache

    public int cache()
    Gets the expression cache size the engine will use.
    Returns:
      the cache size

  - ### cache

    public JexlBuilder cache(int size)
    Sets the expression cache size the engine will use.

    The cache will contain at most `size` expressions of at most `cacheThreshold` length. Note that all JEXL caches are held through SoftReferences and may be garbage-collected.

    Parameters:
      `size` - if not strictly positive, no cache is used.
    Returns:
      this builder

  - ### cacheFactory

    public IntFunction<JexlCache<?,?>> cacheFactory()
    Gets the expression-cache factory the engine will use.
    Returns:
      the cache factory

  - ### cacheFactory

    public JexlBuilder cacheFactory(IntFunction<JexlCache<?,?>> factory)
    Sets the expression-cache factory the engine will use.
    Parameters:
      `factory` - the function to produce a cache.
    Returns:
      this builder

  - ### parserFactory

    public Supplier<org.apache.commons.jexl3.parser.JexlScriptParser> parserFactory()
    Gets the Jexl script parser factory the engine will use.
    Returns:
      the cache factory
    Since:
      3.5.0

  - ### parserFactory

    public JexlBuilder parserFactory(Supplier<org.apache.commons.jexl3.parser.JexlScriptParser> factory)
    Sets the Jexl script parser factory the engine will use.
    Parameters:
      `factory` - the function to produce a cache.
    Returns:
      this builder
    Since:
      3.5.0

  - ### cacheThreshold

    public int cacheThreshold()
    Gets the maximum length for an expression to be cached.
    Returns:
      the cache threshold

  - ### cacheThreshold

    public JexlBuilder cacheThreshold(int length)
    Sets the maximum length for an expression to be cached.

    Expression whose length is greater than this expression cache length threshold will bypass the cache.

    It is expected that a "long" script will be parsed once and its reference kept around in user-space structures; the jexl expression cache has no added-value in this case.

    Parameters:
      `length` - if not strictly positive, the value is silently replaced by the default value (64).
    Returns:
      this builder

  - ### cancellable

    public Boolean cancellable()
    Gets the cancellable information flag
    Returns:
      the cancellable information flag
    Since:
      3.1

  - ### cancellable

    public JexlBuilder cancellable(boolean flag)
    Sets the engine behavior upon interruption: throw an JexlException.Cancel or terminates the current evaluation and return null.
    Parameters:
      `flag` - true implies the engine throws the exception, false makes the engine return null.
    Returns:
      this builder
    Since:
      3.1

  - ### charset

    public Charset charset()
    Gets the charset
    Returns:
      the charset

  - ### charset

    public JexlBuilder charset(Charset arg)
    Sets the charset to use.
    Parameters:
      `arg` - the charset
    Returns:
      this builder
    Since:
      3.1

  - ### collectAll

    public boolean collectAll()
    Does the variable collection follow strict syntactic rule?
    Returns:
      true if variable collection follows strict syntactic rule
    Since:
      3.2

  - ### collectAll

    public JexlBuilder collectAll(boolean flag)
    Sets whether the engine variable collectors considers all potential forms of variable syntaxes.
    Parameters:
      `flag` - true means var collections considers constant array accesses equivalent to dotted references
    Returns:
      this builder
    Since:
      3.2

  - ### collectMode

    public int collectMode()
    Gets the collection mode.
    Returns:
      0 if variable collection follows strict syntactic rule
    Since:
      3.2

  - ### collectMode

    public JexlBuilder collectMode(int mode)
    Experimental collector mode setter.
    Parameters:
      `mode` - 0 or 1 as equivalents to false and true, other values are experimental
    Returns:
      this builder
    Since:
      3.2

  - ### create

    public JexlEngine create()
    Create a new engine
    Returns:
      a `JexlEngine` instance

  - ### debug

    public Boolean debug()
    Gets the debug flag.
    Returns:
      the debugging information flag

  - ### debug

    public JexlBuilder debug(boolean flag)
    Sets whether the engine will report debugging information when error occurs.
    Parameters:
      `flag` - true implies debug is on, false implies debug is off.
    Returns:
      this builder
    See Also:
      - `JexlEngine.isDebug()`

  - ### features

    public JexlFeatures features()
    Gets the features the engine will use as a base by default.
    Returns:
      the features

  - ### features

    public JexlBuilder features(JexlFeatures f)
    Sets the features the engine will use as a base by default.

    Note that the script flag will be ignored; the engine will be able to parse expressions and scripts.

    Note also that these will apply to template expressions and scripts.

    As a last remark, if lexical or lexicalShade are set as features, this method will also set the corresponding options.

    Parameters:
      `f` - the features
    Returns:
      this builder

  - ### imports

    public Collection<String> imports()
    Gets the optional set of imported packages.
    Returns:
      the set of imports, may be empty, not null

  - ### imports

    public JexlBuilder imports(Collection<String> imports)
    Sets the optional set of imports.
    Parameters:
      `imports` - the imported packages
    Returns:
      this builder

  - ### imports

    public JexlBuilder imports(String... imports)
    Sets the optional set of imports.
    Parameters:
      `imports` - the imported packages
    Returns:
      this builder

  - ### lexical

    @Deprecated public boolean lexical()
    Deprecated.
    3.5.0
    Is lexical scope enabled?
    Returns:
      whether lexical scope is enabled
    See Also:
      - `JexlOptions.isLexical()`

  - ### lexical

    public JexlBuilder lexical(boolean flag)
    Sets whether the engine is in lexical mode.
    Parameters:
      `flag` - true means lexical function scope is in effect, false implies non-lexical scoping
    Returns:
      this builder
    Since:
      3.2

  - ### lexicalShade

    @Deprecated public boolean lexicalShade()
    Deprecated.
    3.5.0
    Checks whether lexical shading is enabled.
    Returns:
      whether lexical shading is enabled
    See Also:
      - `JexlOptions.isLexicalShade()`

  - ### lexicalShade

    public JexlBuilder lexicalShade(boolean flag)
    Sets whether the engine is in lexical shading mode.
    Parameters:
      `flag` - true means lexical shading is in effect; false implies no lexical shading
    Returns:
      this builder
    Since:
      3.2

  - ### loader

    public ClassLoader loader()
    Gets the classloader
    Returns:
      the class loader

  - ### loader

    @Deprecated public JexlBuilder loader(Charset arg)
    Deprecated.
    since 3.1 use `charset(Charset)` instead
    Sets the charset to use.
    Parameters:
      `arg` - the charset
    Returns:
      this builder

  - ### loader

    public JexlBuilder loader(ClassLoader l)
    Sets the class loader to use.
    Parameters:
      `l` - the class loader
    Returns:
      this builder

  - ### logger

    public org.apache.commons.logging.Log logger()
    Gets the logger
    Returns:
      the logger

  - ### logger

    public JexlBuilder logger(org.apache.commons.logging.Log log)
    Sets the o.a.c.Log instance to use.
    Parameters:
      `log` - the logger
    Returns:
      this builder

  - ### namespaces

    public Map<String,Object> namespaces()
    Gets the map of namespaces.
    Returns:
      the map of namespaces.

  - ### namespaces

    public JexlBuilder namespaces(Map<String,Object> ns)
    Sets the default namespaces map the engine will use.

    Each entry key is used as a prefix, each entry value used as a bean implementing methods; an expression like 'nsx:method(123)' will thus be solved by looking at a registered bean named 'nsx' that implements method 'method' in that map. If all methods are static, you may use the bean class instead of an instance as value.

    If the entry value is a class that has one constructor taking a JexlContext as argument, an instance of the namespace will be created at evaluation time. It might be a good idea to derive a JexlContext to carry the information used by the namespace to avoid variable space pollution and strongly type the constructor with this specialized JexlContext.

    The key or prefix allows to retrieve the bean that plays the role of the namespace. If the prefix is null, the namespace is the top-level namespace allowing to define top-level user-defined namespaces ( ie: myfunc(...) )

    Note that the JexlContext is also used to try to solve top-level namespaces. This allows ObjectContext derived instances to call methods on the wrapped object.

    Parameters:
      `ns` - the map of namespaces
    Returns:
      this builder

  - ### options

    public JexlOptions options()
    Gets the current set of options
    Returns:
      the current set of options

  - ### permissions

    public JexlPermissions permissions()
    Gets the permissions
    Returns:
      the permissions

  - ### permissions

    public JexlBuilder permissions(JexlPermissions p)
    Sets the JexlPermissions instance the engine will use.
    Parameters:
      `p` - the permissions
    Returns:
      this builder

  - ### safe

    public Boolean safe()
    Is it safe to dereference null?
    Returns:
      true if safe, false otherwise

  - ### safe

    public JexlBuilder safe(boolean flag)
    Sets whether the engine considers dereferencing null in navigation expressions as null or triggers an error.

    `x.y()` if x is null throws an exception when not safe, return null and warns if it is.

    It is recommended to use safe(false) as an explicit default.

    Parameters:
      `flag` - true means safe navigation, false throws exception when dereferencing null
    Returns:
      this builder

  - ### sandbox

    public JexlSandbox sandbox()
    Gets the sandbox
    Returns:
      the sandbox

  - ### sandbox

    public JexlBuilder sandbox(JexlSandbox box)
    Sets the sandbox the engine will use.
    Parameters:
      `box` - the sandbox
    Returns:
      this builder

  - ### silent

    public Boolean silent()
    Is error handling silent?
    Returns:
      the silent error handling flag

  - ### silent

    public JexlBuilder silent(boolean flag)
    Sets whether the engine will throw JexlException during evaluation when an error is triggered.

    When not silent, the engine throws an exception when the evaluation triggers an exception or an error.

    It is recommended to use silent(false) as an explicit default.

    Parameters:
      `flag` - true means no JexlException will occur, false allows them
    Returns:
      this builder

  - ### stackOverflow

    public int stackOverflow()
    Gets the cache size
    Returns:
      the cache size

  - ### stackOverflow

    public JexlBuilder stackOverflow(int size)
    Sets the number of script/expression evaluations that can be stacked.
    Parameters:
      `size` - if not strictly positive, limit is reached when Java StackOverflow is thrown.
    Returns:
      this builder

  - ### strategy

    public JexlUberspect.ResolverStrategy strategy()
    Gets the JexlUberspect strategy
    Returns:
      the JexlUberspect strategy

  - ### strategy

    public JexlBuilder strategy(JexlUberspect.ResolverStrategy rs)
    Sets the JexlUberspect strategy the engine will use.

    This is ignored if the uberspect has been set.

    Parameters:
      `rs` - the strategy
    Returns:
      this builder

  - ### strict

    public Boolean strict()
    Is it strict mode?
    Returns:
      true if strict, false otherwise

  - ### strict

    public JexlBuilder strict(boolean flag)
    Sets whether the engine considers unknown variables, methods, functions, and constructors as errors or evaluates them as null.

    When not strict, operators or functions using null operands return null on evaluation. When strict, those raise exceptions.

    It is recommended to use strict(true) as an explicit default.

    Parameters:
      `flag` - true means strict error reporting, false allows them to be evaluated as null
    Returns:
      this builder

  - ### strictInterpolation

    public JexlBuilder strictInterpolation(boolean flag)
    Is interpolation strict?
    Parameters:
      `flag` - strict interpolation flag
    Returns:
      this builder
    See Also:
      - `JexlOptions.setStrictInterpolation(boolean)`

  - ### uberspect

    public JexlUberspect uberspect()
    Gets the uberspect
    Returns:
      the uberspect

  - ### uberspect

    public JexlBuilder uberspect(JexlUberspect u)
    Sets the JexlUberspect instance the engine will use.
    Parameters:
      `u` - the uberspect
    Returns:
      this builder