Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.jexl3
Class JexlEngine

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

Direct Known Subclasses:
  Engine

    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
`static interface` | `JexlEngine.Options` Script evaluation options.

Field Summary
`protected static ThreadLocal<JexlContext.ThreadLocal>` | `CONTEXT` The thread local context.
`static JexlContext` | `EMPTY_CONTEXT` An empty/static/non-mutable JexlContext used instead of null context.
`static JexlContext.NamespaceResolver` | `EMPTY_NS` An empty/static/non-mutable JexlNamesapce used instead of null namespace.
`static Object` | `TRY_FAILED` A marker for invocation failures in tryInvoke.

Constructor Summary
`JexlEngine()`

Method Summary
`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.
`JexlScript` | `createScript(JexlInfo info, File scriptFile, String[] names)` Creates a Script from a `File` containing valid JEXL syntax.
`abstract 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 scriptText, 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.
`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 for invocation failures in tryInvoke.

### CONTEXT

    protected static final ThreadLocal<JexlContext.ThreadLocal> CONTEXT

  The thread local context.

### EMPTY_CONTEXT

    public static final JexlContext EMPTY_CONTEXT

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

### EMPTY_NS

    public static final JexlContext.NamespaceResolver EMPTY_NS

  An empty/static/non-mutable JexlNamesapce 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

### 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 should be called as an optional step of the JexlEngine initialization code before expression creation & evaluation.

  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

### createScript

    public abstract 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

### 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 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 scriptText,
                                         String... names)

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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