org.apache.commons.jexl3
Class JexlEngine

java.lang.Object
  extended by 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:

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


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