org.apache.commons.jexl3

## Class JexlBuilder

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

-     public class JexlBuilder
      extends Object

  Configure and builds a JexlEngine.

  The `setSilent` and `setStrict` methods allow to fine-tune an engine instance behavior according to various error control needs. The strict flag tells the engine when and if null as operand is considered an error, the silent flag tells the engine what to do with the error (log as warning or throw exception).

  - 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.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `JexlBuilder()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `antish()`
    `JexlBuilder` | `antish(boolean flag)` Sets whether the engine will resolve antish variable names.
    `JexlArithmetic` | `arithmetic()`
    `JexlBuilder` | `arithmetic(JexlArithmetic a)` Sets the JexlArithmetic instance the engine will use.
    `int` | `cache()`
    `JexlBuilder` | `cache(int size)` Sets the expression cache size the engine will use.
    `int` | `cacheThreshold()`
    `JexlBuilder` | `cacheThreshold(int length)` Sets the maximum length for an expression to be cached.
    `Boolean` | `cancellable()`
    `JexlBuilder` | `cancellable(boolean flag)` Sets the engine behavior upon interruption: throw an JexlException.Cancel or terminates the current evaluation and return null.
    `Charset` | `charset()`
    `JexlBuilder` | `charset(Charset arg)` Sets the charset to use.
    `boolean` | `collectAll()`
    `JexlBuilder` | `collectAll(boolean flag)` Sets whether the engine variable collectors considers all potential forms of variable syntaxes.
    `int` | `collectMode()`
    `JexlBuilder` | `collectMode(int mode)` Experimental collector mode setter.
    `JexlEngine` | `create()`
    `Boolean` | `debug()`
    `JexlBuilder` | `debug(boolean flag)` Sets whether the engine will report debugging information when error occurs.
    `JexlFeatures` | `features()`
    `JexlBuilder` | `features(JexlFeatures f)` Sets the features the engine will use as a base by default.
    `boolean` | `lexical()`
    `JexlBuilder` | `lexical(boolean flag)` Sets whether the engine is in lexical mode.
    `boolean` | `lexicalShade()`
    `JexlBuilder` | `lexicalShade(boolean flag)` Sets whether the engine is in lexical shading mode.
    `ClassLoader` | `loader()`
    `JexlBuilder` | `loader(Charset arg)` Deprecated. since 3.1 use `charset(Charset)` instead
    `JexlBuilder` | `loader(ClassLoader l)` Sets the class loader to use.
    `org.apache.commons.logging.Log` | `logger()`
    `JexlBuilder` | `logger(org.apache.commons.logging.Log log)` Sets the o.a.c.Log instance to use.
    `Map<String,Object>` | `namespaces()`
    `JexlBuilder` | `namespaces(Map<String,Object> ns)` Sets the default namespaces map the engine will use.
    `JexlOptions` | `options()`
    `Boolean` | `safe()`
    `JexlBuilder` | `safe(boolean flag)` Sets whether the engine considers dereferencing null in navigation expressions as errors or evaluates them as null.
    `JexlSandbox` | `sandbox()`
    `JexlBuilder` | `sandbox(JexlSandbox box)` Sets the sandbox the engine will use.
    `Boolean` | `silent()`
    `JexlBuilder` | `silent(boolean flag)` Sets whether the engine will throw JexlException during evaluation when an error is triggered.
    `int` | `stackOverflow()`
    `JexlBuilder` | `stackOverflow(int size)` Sets the number of script/expression evaluations that can be stacked.
    `JexlUberspect.ResolverStrategy` | `strategy()`
    `JexlBuilder` | `strategy(JexlUberspect.ResolverStrategy rs)` Sets the JexlUberspect strategy strategy the engine will use.
    `Boolean` | `strict()`
    `JexlBuilder` | `strict(boolean flag)` Sets whether the engine considers unknown variables, methods, functions and constructors as errors or evaluates them as null.
    `JexlUberspect` | `uberspect()`
    `JexlBuilder` | `uberspect(JexlUberspect u)` Sets the JexlUberspect instance the engine will use.

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

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

- - ### Constructor Detail

    - #### JexlBuilder

          public JexlBuilder()

  - ### Method Detail

    - #### uberspect

          public JexlBuilder uberspect(JexlUberspect u)

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

    - #### uberspect

          public JexlUberspect uberspect()

      Returns:
        the uberspect

    - #### strategy

          public JexlBuilder strategy(JexlUberspect.ResolverStrategy rs)

      Sets the JexlUberspect strategy strategy the engine will use.

      This is ignored if the uberspect has been set.

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

    - #### strategy

          public JexlUberspect.ResolverStrategy strategy()

      Returns:
        the strategy strategy

    - #### options

          public JexlOptions options()

      Returns:
        the current set of options

    - #### arithmetic

          public JexlBuilder arithmetic(JexlArithmetic a)

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

    - #### arithmetic

          public JexlArithmetic arithmetic()

      Returns:
        the arithmetic

    - #### sandbox

          public JexlBuilder sandbox(JexlSandbox box)

      Sets the sandbox the engine will use.
      Parameters:
        `box` - the sandbox
      Returns:
        this builder

    - #### sandbox

          public JexlSandbox sandbox()

      Returns:
        the sandbox

    - #### 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

    - #### features

          public JexlFeatures features()

      Returns:
        the features

    - #### 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

    - #### logger

          public org.apache.commons.logging.Log logger()

      Returns:
        the logger

    - #### loader

          public JexlBuilder loader(ClassLoader l)

      Sets the class loader to use.
      Parameters:
        `l` - the class loader
      Returns:
        this builder

    - #### loader

          public ClassLoader loader()

      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

    - #### charset

          public JexlBuilder charset(Charset arg)

      Sets the charset to use.
      Parameters:
        `arg` - the charset
      Returns:
        this builder
      Since:
        3.1

    - #### charset

          public Charset charset()

      Returns:
        the charset

    - #### 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

    - #### antish

          public boolean antish()

      Returns:
        whether antish resolution is enabled

    - #### 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

    - #### lexical

          public boolean lexical()

      Returns:
        whether lexical scope is enabled

    - #### 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

    - #### lexicalShade

          public boolean lexicalShade()

      Returns:
        whether lexical shading is enabled

    - #### silent

          public JexlBuilder silent(boolean flag)

      Sets whether the engine will throw JexlException during evaluation when an error is triggered.
      Parameters:
        `flag` - true means no JexlException will occur, false allows them
      Returns:
        this builder

    - #### silent

          public Boolean silent()

      Returns:
        the silent error handling flag

    - #### strict

          public JexlBuilder strict(boolean flag)

      Sets whether the engine considers unknown variables, methods, functions and constructors as errors or evaluates them as null.
      Parameters:
        `flag` - true means strict error reporting, false allows them to be evaluated as null
      Returns:
        this builder

    - #### strict

          public Boolean strict()

      Returns:
        true if strict, false otherwise

    - #### safe

          public JexlBuilder safe(boolean flag)

      Sets whether the engine considers dereferencing null in navigation expressions as errors or evaluates them as null.

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

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

    - #### safe

          public Boolean safe()

      Returns:
        true if safe, false otherwise

    - #### 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

    - #### debug

          public Boolean debug()

      Returns:
        the debugging information flag

    - #### 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

    - #### cancellable

          public Boolean cancellable()

      Returns:
        the cancellable information flag
      Since:
        3.1

    - #### 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 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

    - #### collectAll

          public boolean collectAll()

      Returns:
        true if variable collection follows strict syntactic rule
      Since:
        3.2

    - #### collectMode

          public int collectMode()

      Returns:
        0 if variable collection follows strict syntactic rule
      Since:
        3.2

    - #### 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

    - #### namespaces

          public Map<String,Object> namespaces()

      Returns:
        the map of namespaces.

    - #### 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

    - #### cache

          public int cache()

      Returns:
        the cache size

    - #### 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

    - #### cacheThreshold

          public int cacheThreshold()

      Returns:
        the cache threshold

    - #### 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

    - #### stackOverflow

          public int stackOverflow()

      Returns:
        the cache size

    - #### create

          public JexlEngine create()

      Returns:
        a `JexlEngine` instance

Copyright © 2001–2021 The Apache Software Foundation. All rights reserved.