org.apache.commons.jexl3

## Class JexlEngine

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

-     public abstract class JexlEngine
      extends Object

  Creates and evaluates JexlExpression and JexlScript objects. Determines the behavior of expressions and scripts during their evaluation with respect to:
  - Introspection, see `JexlUberspect`
  - Arithmetic and comparison, see `JexlArithmetic`
  - Error reporting
  - Logging

  Note that methods that evaluate expressions may throw unchecked exceptions; The `JexlException` are thrown in "non-silent" mode but since these are RuntimeException, user-code should catch them wherever most appropriate.

  Since:
    2.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `JexlEngine.EmptyContext` The empty context class, public for instrospection.
    `static class` | `JexlEngine.EmptyNamespaceResolver` The empty/static/non-mutable JexlNamespace class, public for instrospection.
    `static interface` | `JexlEngine.Options` Deprecated. 3.2

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static ThreadLocal<JexlContext.ThreadLocal>` | `CONTEXT` The thread local context.
    `static JexlFeatures` | `DEFAULT_FEATURES` Default features.
    `static JexlContext` | `EMPTY_CONTEXT` An empty/static/non-mutable JexlContext singleton used instead of null context.
    `static JexlContext.NamespaceResolver` | `EMPTY_NS` An empty/static/non-mutable JexlNamespace singleton used instead of null namespace.
    `protected static ThreadLocal<JexlEngine>` | `ENGINE` The thread local engine.
    `static Object` | `TRY_FAILED` A marker singleton for invocation failures in tryInvoke.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JexlEngine()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `clearCache()` Clears the expression cache.
    `abstract JexlExpression` | `createExpression(JexlInfo info, String expression)` Creates an JexlExpression from a String containing valid JEXL syntax.
    `JexlExpression` | `createExpression(String expression)` Creates a JexlExpression from a String containing valid JEXL syntax.
    `JexlInfo` | `createInfo()` Create an information structure for dynamic set/get/invoke/new.
    `JexlInfo` | `createInfo(String fn, int l, int c)` Creates a JexlInfo instance.
    `JxltEngine` | `createJxltEngine()` Creates a new `JxltEngine` instance using this engine.
    `JxltEngine` | `createJxltEngine(boolean noScript)` Creates a new `JxltEngine` instance using this engine.
    `abstract JxltEngine` | `createJxltEngine(boolean noScript, int cacheSize, char immediate, char deferred)` Creates a new instance of `JxltEngine` using this engine.
    `JexlScript` | `createScript(File scriptFile)` Creates a Script from a `File` containing valid JEXL syntax.
    `JexlScript` | `createScript(File scriptFile, String... names)` Creates a Script from a `File` containing valid JEXL syntax.
    `abstract JexlScript` | `createScript(JexlFeatures features, JexlInfo info, String source, String... names)` Creates a JexlScript from a String containing valid JEXL syntax.
    `JexlScript` | `createScript(JexlInfo info, File scriptFile, String... names)` Creates a Script from a `File` containing valid JEXL syntax.
    `JexlScript` | `createScript(JexlInfo info, String source, String... names)` Creates a JexlScript from a String containing valid JEXL syntax.
    `JexlScript` | `createScript(JexlInfo info, URL scriptUrl, String... names)` Creates a Script from a `URL` containing valid JEXL syntax.
    `JexlScript` | `createScript(String scriptText)` Creates a Script from a String containing valid JEXL syntax.
    `JexlScript` | `createScript(String source, String... names)` Creates a Script from a String containing valid JEXL syntax.
    `JexlScript` | `createScript(URL scriptUrl)` Creates a Script from a `URL` containing valid JEXL syntax.
    `JexlScript` | `createScript(URL scriptUrl, String... names)` Creates a Script from a `URL` containing valid JEXL syntax.
    `abstract JexlArithmetic` | `getArithmetic()` Gets this engine underlying `JexlArithmetic`.
    `abstract Charset` | `getCharset()` Gets the charset used for parsing.
    `abstract Object` | `getProperty(JexlContext context, Object bean, String expr)` Accesses properties of a bean using an expression.
    `abstract Object` | `getProperty(Object bean, String expr)` Accesses properties of a bean using an expression.
    `static JexlContext.ThreadLocal` | `getThreadContext()` Accesses the current thread local context.
    `static JexlEngine` | `getThreadEngine()` Accesses the current thread local engine.
    `abstract JexlUberspect` | `getUberspect()` Gets this engine underlying `JexlUberspect`.
    `abstract Object` | `invokeMethod(Object obj, String meth, Object... args)` Invokes an object's method by name and arguments.
    `abstract boolean` | `isCancellable()` Checks whether this engine will throw JexlException.Cancel (true) or return null (false) when interrupted during an execution.
    `abstract boolean` | `isDebug()` Checks whether this engine is in debug mode.
    `abstract boolean` | `isSilent()` Checks whether this engine throws JexlException during evaluation.
    `abstract boolean` | `isStrict()` Checks whether this engine considers unknown variables, methods, functions and constructors as errors.
    `abstract <T> T` | `newInstance(Class<? extends T> clazz, Object... args)` Creates a new instance of an object using the most appropriate constructor based on the arguments.
    `abstract Object` | `newInstance(String clazz, Object... args)` Creates a new instance of an object using the most appropriate constructor based on the arguments.
    `protected String` | `readSource(File file)` Reads a JEXL source from a File.
    `protected String` | `readSource(URL url)` Reads a JEXL source from an URL.
    `abstract void` | `setClassLoader(ClassLoader loader)` Sets the class loader used to discover classes in 'new' expressions.
    `abstract void` | `setProperty(JexlContext context, Object bean, String expr, Object value)` Assign properties of a bean using an expression.
    `abstract void` | `setProperty(Object bean, String expr, Object value)` Assign properties of a bean using an expression.
    `static void` | `setThreadContext(JexlContext.ThreadLocal tls)` Sets the current thread local context.
    `protected static String` | `toString(BufferedReader reader)` Creates a string from a reader.

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

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

- - ### Field Detail

    - #### TRY_FAILED

          public static final Object TRY_FAILED

      A marker singleton for invocation failures in tryInvoke.

    - #### CONTEXT

          protected static final ThreadLocal<JexlContext.ThreadLocal> CONTEXT

      The thread local context.

    - #### ENGINE

          protected static final ThreadLocal<JexlEngine> ENGINE

      The thread local engine.

    - #### DEFAULT_FEATURES

          public static final JexlFeatures DEFAULT_FEATURES

      Default features.

    - #### EMPTY_CONTEXT

          public static final JexlContext EMPTY_CONTEXT

      An empty/static/non-mutable JexlContext singleton used instead of null context.

    - #### EMPTY_NS

          public static final JexlContext.NamespaceResolver EMPTY_NS

      An empty/static/non-mutable JexlNamespace singleton used instead of null namespace.

  - ### Constructor Detail

    - #### JexlEngine

          public JexlEngine()

  - ### Method Detail

    - #### getThreadContext

          public static JexlContext.ThreadLocal getThreadContext()

      Accesses the current thread local context.
      Returns:
        the context or null

    - #### getThreadEngine

          public static JexlEngine getThreadEngine()

      Accesses the current thread local engine.

      Advanced: you should only use this to retrieve the engine within a method/ctor called through the evaluation of a script/expression.

      Returns:
        the engine or null

    - #### setThreadContext

          public static void setThreadContext(JexlContext.ThreadLocal tls)

      Sets the current thread local context.

      This should only be used carefully, for instance when re-evaluating a "stored" script that requires a given Namespace resolver. Remember to synchronize access if context is shared between threads.

      Parameters:
        `tls` - the thread local context to set

    - #### getCharset

          public abstract Charset getCharset()

      Gets the charset used for parsing.
      Returns:
        the charset

    - #### getUberspect

          public abstract JexlUberspect getUberspect()

      Gets this engine underlying `JexlUberspect`.
      Returns:
        the uberspect

    - #### getArithmetic

          public abstract JexlArithmetic getArithmetic()

      Gets this engine underlying `JexlArithmetic`.
      Returns:
        the arithmetic

    - #### isDebug

          public abstract boolean isDebug()

      Checks whether this engine is in debug mode.
      Returns:
        true if debug is on, false otherwise

    - #### isSilent

          public abstract boolean isSilent()

      Checks whether this engine throws JexlException during evaluation.
      Returns:
        true if silent, false (default) otherwise

    - #### isStrict

          public abstract boolean isStrict()

      Checks whether this engine considers unknown variables, methods, functions and constructors as errors.
      Returns:
        true if strict, false otherwise

    - #### isCancellable

          public abstract boolean isCancellable()

      Checks whether this engine will throw JexlException.Cancel (true) or return null (false) when interrupted during an execution.
      Returns:
        true if cancellable, false otherwise

    - #### setClassLoader

          public abstract void setClassLoader(ClassLoader loader)

      Sets the class loader used to discover classes in 'new' expressions.

      This method is not thread safe; it may be called after JexlEngine initialization and allow scripts to use new classes definitions.

      Parameters:
        `loader` - the class loader to use

    - #### createJxltEngine

          public JxltEngine createJxltEngine()

      Creates a new `JxltEngine` instance using this engine.
      Returns:
        a JEXL Template engine

    - #### createJxltEngine

          public JxltEngine createJxltEngine(boolean noScript)

      Creates a new `JxltEngine` instance using this engine.
      Parameters:
        `noScript` - whether the JxltEngine only allows Jexl expressions or scripts
      Returns:
        a JEXL Template engine

    - #### createJxltEngine

          public abstract JxltEngine createJxltEngine(boolean noScript,
                                                      int cacheSize,
                                                      char immediate,
                                                      char deferred)

      Creates a new instance of `JxltEngine` using this engine.
      Parameters:
        `noScript` - whether the JxltEngine only allows JEXL expressions or scripts
        `cacheSize` - the number of expressions in this cache, default is 256
        `immediate` - the immediate template expression character, default is '$'
        `deferred` - the deferred template expression character, default is '#'
      Returns:
        a JEXL Template engine

    - #### clearCache

          public abstract void clearCache()

      Clears the expression cache.

    - #### createExpression

          public abstract JexlExpression createExpression(JexlInfo info,
                                                          String expression)

      Creates an JexlExpression from a String containing valid JEXL syntax. This method parses the expression which must contain either a reference or an expression.
      Parameters:
        `info` - An info structure to carry debugging information if needed
        `expression` - A String containing valid JEXL syntax
      Returns:
        An `JexlExpression` which can be evaluated using a `JexlContext`
      Throws:
        `JexlException` - if there is a problem parsing the script

    - #### createExpression

          public final JexlExpression createExpression(String expression)

      Creates a JexlExpression from a String containing valid JEXL syntax. This method parses the expression which must contain either a reference or an expression.
      Parameters:
        `expression` - A String containing valid JEXL syntax
      Returns:
        An `JexlExpression` which can be evaluated using a `JexlContext`
      Throws:
        `JexlException` - if there is a problem parsing the script

    - #### createScript

          public abstract JexlScript createScript(JexlFeatures features,
                                                  JexlInfo info,
                                                  String source,
                                                  String... names)

      Creates a JexlScript from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `features` - A set of features that will be enforced during parsing
        `info` - An info structure to carry debugging information if needed
        `source` - A string containing valid JEXL syntax
        `names` - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation
      Returns:
        A `JexlScript` which can be executed using a `JexlContext`
      Throws:
        `JexlException` - if there is a problem parsing the script

    - #### createScript

          public final JexlScript createScript(JexlInfo info,
                                               String source,
                                               String... names)

      Creates a JexlScript from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `info` - An info structure to carry debugging information if needed
        `source` - A string containing valid JEXL syntax
        `names` - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation
      Returns:
        A `JexlScript` which can be executed using a `JexlContext`
      Throws:
        `JexlException` - if there is a problem parsing the script

    - #### createScript

          public final JexlScript createScript(String scriptText)

      Creates a Script from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `scriptText` - A String containing valid JEXL syntax
      Returns:
        A `JexlScript` which can be executed using a `JexlContext`
      Throws:
        `JexlException` - if there is a problem parsing the script.

    - #### createScript

          public final JexlScript createScript(String source,
                                               String... names)

      Creates a Script from a String containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `source` - A String containing valid JEXL syntax
        `names` - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation
      Returns:
        A `JexlScript` which can be executed using a `JexlContext`
      Throws:
        `JexlException` - if there is a problem parsing the script

    - #### createScript

          public final JexlScript createScript(File scriptFile)

      Creates a Script from a `File` containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `scriptFile` - A `File` containing valid JEXL syntax. Must not be null. Must be a readable file.
      Returns:
        A `JexlScript` which can be executed with a `JexlContext`.
      Throws:
        `JexlException` - if there is a problem reading or parsing the script.

    - #### createScript

          public final JexlScript createScript(File scriptFile,
                                               String... names)

      Creates a Script from a `File` containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `scriptFile` - A `File` containing valid JEXL syntax. Must not be null. Must be a readable file.
        `names` - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation.
      Returns:
        A `JexlScript` which can be executed with a `JexlContext`.
      Throws:
        `JexlException` - if there is a problem reading or parsing the script.

    - #### createScript

          public final JexlScript createScript(JexlInfo info,
                                               File scriptFile,
                                               String... names)

      Creates a Script from a `File` containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `info` - An info structure to carry debugging information if needed
        `scriptFile` - A `File` containing valid JEXL syntax. Must not be null. Must be a readable file.
        `names` - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation.
      Returns:
        A `JexlScript` which can be executed with a `JexlContext`.
      Throws:
        `JexlException` - if there is a problem reading or parsing the script.

    - #### createScript

          public final JexlScript createScript(URL scriptUrl)

      Creates a Script from a `URL` containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `scriptUrl` - A `URL` containing valid JEXL syntax. Must not be null.
      Returns:
        A `JexlScript` which can be executed with a `JexlContext`.
      Throws:
        `JexlException` - if there is a problem reading or parsing the script.

    - #### createScript

          public final JexlScript createScript(URL scriptUrl,
                                               String... names)

      Creates a Script from a `URL` containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `scriptUrl` - A `URL` containing valid JEXL syntax. Must not be null.
        `names` - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation.
      Returns:
        A `JexlScript` which can be executed with a `JexlContext`.
      Throws:
        `JexlException` - if there is a problem reading or parsing the script.

    - #### createScript

          public final JexlScript createScript(JexlInfo info,
                                               URL scriptUrl,
                                               String... names)

      Creates a Script from a `URL` containing valid JEXL syntax. This method parses the script and validates the syntax.
      Parameters:
        `info` - An info structure to carry debugging information if needed
        `scriptUrl` - A `URL` containing valid JEXL syntax. Must not be null.
        `names` - The script parameter names used during parsing; a corresponding array of arguments containing values should be used during evaluation.
      Returns:
        A `JexlScript` which can be executed with a `JexlContext`.
      Throws:
        `JexlException` - if there is a problem reading or parsing the script.

    - #### getProperty

          public abstract Object getProperty(Object bean,
                                             String expr)

      Accesses properties of a bean using an expression.

      jexl.get(myobject, "foo.bar"); should equate to myobject.getFoo().getBar(); (or myobject.getFoo().get("bar"))

      If the JEXL engine is silent, errors will be logged through its logger as warning.

      Parameters:
        `bean` - the bean to get properties from
        `expr` - the property expression
      Returns:
        the value of the property
      Throws:
        `JexlException` - if there is an error parsing the expression or during evaluation

    - #### getProperty

          public abstract Object getProperty(JexlContext context,
                                             Object bean,
                                             String expr)

      Accesses properties of a bean using an expression.

      If the JEXL engine is silent, errors will be logged through its logger as warning.

      Parameters:
        `context` - the evaluation context
        `bean` - the bean to get properties from
        `expr` - the property expression
      Returns:
        the value of the property
      Throws:
        `JexlException` - if there is an error parsing the expression or during evaluation

    - #### setProperty

          public abstract void setProperty(Object bean,
                                           String expr,
                                           Object value)

      Assign properties of a bean using an expression.

      jexl.set(myobject, "foo.bar", 10); should equate to myobject.getFoo().setBar(10); (or myobject.getFoo().put("bar", 10) )

      If the JEXL engine is silent, errors will be logged through its logger as warning.

      Parameters:
        `bean` - the bean to set properties in
        `expr` - the property expression
        `value` - the value of the property
      Throws:
        `JexlException` - if there is an error parsing the expression or during evaluation

    - #### setProperty

          public abstract void setProperty(JexlContext context,
                                           Object bean,
                                           String expr,
                                           Object value)

      Assign properties of a bean using an expression.

      If the JEXL engine is silent, errors will be logged through its logger as warning.

      Parameters:
        `context` - the evaluation context
        `bean` - the bean to set properties in
        `expr` - the property expression
        `value` - the value of the property
      Throws:
        `JexlException` - if there is an error parsing the expression or during evaluation

    - #### invokeMethod

          public abstract Object invokeMethod(Object obj,
                                              String meth,
                                              Object... args)

      Invokes an object's method by name and arguments.
      Parameters:
        `obj` - the method's invoker object
        `meth` - the method's name
        `args` - the method's arguments
      Returns:
        the method returned value or null if it failed and engine is silent
      Throws:
        `JexlException` - if method could not be found or failed and engine is not silent

    - #### newInstance

          public abstract <T> T newInstance(Class<? extends T> clazz,
                                            Object... args)

      Creates a new instance of an object using the most appropriate constructor based on the arguments.
      Type Parameters:
        `T` - the type of object
      Parameters:
        `clazz` - the class to instantiate
        `args` - the constructor arguments
      Returns:
        the created object instance or null on failure when silent

    - #### newInstance

          public abstract Object newInstance(String clazz,
                                             Object... args)

      Creates a new instance of an object using the most appropriate constructor based on the arguments.
      Parameters:
        `clazz` - the name of the class to instantiate resolved through this engine's class loader
        `args` - the constructor arguments
      Returns:
        the created object instance or null on failure when silent

    - #### createInfo

          public JexlInfo createInfo(String fn,
                                     int l,
                                     int c)

      Creates a JexlInfo instance.
      Parameters:
        `fn` - url/file/template/script user given name
        `l` - line number
        `c` - column number
      Returns:
        a JexlInfo instance

    - #### createInfo

          public JexlInfo createInfo()

      Create an information structure for dynamic set/get/invoke/new.

      This gathers the class, method and line number of the first calling method outside of o.a.c.jexl3.

      Returns:
        a JexlInfo instance

    - #### toString

          protected static String toString(BufferedReader reader)
                                    throws IOException

      Creates a string from a reader.
      Parameters:
        `reader` - to be read.
      Returns:
        the contents of the reader as a String.
      Throws:
        `IOException` - on any error reading the reader.

    - #### readSource

          protected String readSource(File file)

      Reads a JEXL source from a File.
      Parameters:
        `file` - the script file
      Returns:
        the source

    - #### readSource

          protected String readSource(URL url)

      Reads a JEXL source from an URL.
      Parameters:
        `url` - the script url
      Returns:
        the source

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