Package 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
  Description
  `static final class`
  `JexlEngine.EmptyContext`
  The empty context class, public for instrospection.
  `static final 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
  Description
  `protected static final ThreadLocal<JexlContext.ThreadLocal>`
  `CONTEXT`
  The thread local context.
  `static final JexlFeatures`
  `DEFAULT_FEATURES`
  Default features.
  `static final JexlContext`
  `EMPTY_CONTEXT`
  An empty/static/non-mutable JexlContext singleton used instead of null context.
  `static final JexlContext.NamespaceResolver`
  `EMPTY_NS`
  An empty/static/non-mutable JexlNamespace singleton used instead of null namespace.
  `protected static final ThreadLocal<JexlEngine>`
  `ENGINE`
  The thread local engine.
  `static final Object`
  `TRY_FAILED`
  A marker singleton for invocation failures in tryInvoke.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JexlEngine()`
  Default constructor

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `clearCache()`
  Clears the expression cache.
  `final JexlExpression`
  `createExpression(String expression)`
  Creates a JexlExpression from a String containing valid JEXL syntax.
  `abstract JexlExpression`
  `createExpression(JexlInfo info, String expression)`
  Creates an 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.
  `final JexlScript`
  `createScript(File scriptFile)`
  Creates a Script from a `File` containing valid JEXL syntax.
  `final JexlScript`
  `createScript(File scriptFile, String... names)`
  Creates a Script from a `File` containing valid JEXL syntax.
  `final JexlScript`
  `createScript(String scriptText)`
  Creates a Script from a String containing valid JEXL syntax.
  `final JexlScript`
  `createScript(String source, String... names)`
  Creates a Script from a String containing valid JEXL syntax.
  `final JexlScript`
  `createScript(URL scriptUrl)`
  Creates a Script from a `URL` containing valid JEXL syntax.
  `final JexlScript`
  `createScript(URL scriptUrl, String... names)`
  Creates a Script from a `URL` 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.
  `final JexlScript`
  `createScript(JexlInfo info, File scriptFile, String... names)`
  Creates a Script from a `File` containing valid JEXL syntax.
  `final JexlScript`
  `createScript(JexlInfo info, String source, String... names)`
  Creates a JexlScript from a String containing valid JEXL syntax.
  `final JexlScript`
  `createScript(JexlInfo info, 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(Object bean, String expr)`
  Accesses properties of a bean using an expression.
  `abstract Object`
  `getProperty(JexlContext context, 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(Object bean, String expr, Object value)`
  Assign properties of a bean using an expression.
  `abstract void`
  `setProperty(JexlContext context, 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 Details

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

  - ### JexlEngine

    public JexlEngine()
    Default constructor

- ## Method Details

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

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

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

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

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

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

  - ### 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 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, 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(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(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.

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

  - ### getArithmetic

    public abstract JexlArithmetic getArithmetic()
    Gets this engine underlying `JexlArithmetic`.
    Returns:
      the arithmetic

  - ### getCharset

    public abstract Charset getCharset()
    Gets the charset used for parsing.
    Returns:
      the charset

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

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

  - ### getUberspect

    public abstract JexlUberspect getUberspect()
    Gets this engine underlying `JexlUberspect`.
    Returns:
      the uberspect

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

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

  - ### isDebug

    public abstract boolean isDebug()
    Checks whether this engine is in debug mode.

    If set to true which is the default, when calling `newInstance(java.lang.Class<? extends T>, java.lang.Object...)`, `invokeMethod(java.lang.Object, java.lang.String, java.lang.Object...)`, `setProperty(org.apache.commons.jexl3.JexlContext, java.lang.Object, java.lang.String, java.lang.Object)`, `getProperty(org.apache.commons.jexl3.JexlContext, java.lang.Object, java.lang.String)` or if no `JexlInfo` instance is provided when creating a script and an error occurs during execution, the error message will contain the stack-trace (class/method/line) location of the caller for the methods, of the creator for the script; this may not be desirable in rare environments where vulnerability assessments are strict.

    Returns:
      true if debug is on, false otherwise
    See Also:
      - `JexlBuilder.debug(boolean)`

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

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

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

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

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

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