Class JexlEngine
- java.lang.Object
-
- org.apache.commons.jexl3.JexlEngine
-
- Direct Known Subclasses:
Engine
public abstract class JexlEngine extends java.lang.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 class
JexlEngine.EmptyContext
The empty context class, public for instrospection.static class
JexlEngine.EmptyNamespaceResolver
The empty/static/non-mutable JexlNamespace class, public for instrospection.private static class
JexlEngine.FailObject
The failure marker class.static interface
JexlEngine.Options
Deprecated.3.2
-
Field Summary
Fields Modifier and Type Field Description protected static java.lang.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 java.lang.ThreadLocal<JexlEngine>
ENGINE
The thread local engine.private static int
JXLT_CACHE_SIZE
The default Jxlt cache size.static java.lang.Object
TRY_FAILED
A marker singleton for invocation failures in tryInvoke.
-
Constructor Summary
Constructors Constructor Description JexlEngine()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract void
clearCache()
Clears the expression cache.JexlExpression
createExpression(java.lang.String expression)
Creates a JexlExpression from a String containing valid JEXL syntax.abstract JexlExpression
createExpression(JexlInfo info, java.lang.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(java.lang.String fn, int l, int c)
Creates a JexlInfo instance.JxltEngine
createJxltEngine()
Creates a newJxltEngine
instance using this engine.JxltEngine
createJxltEngine(boolean noScript)
Creates a newJxltEngine
instance using this engine.abstract JxltEngine
createJxltEngine(boolean noScript, int cacheSize, char immediate, char deferred)
Creates a new instance ofJxltEngine
using this engine.JexlScript
createScript(java.io.File scriptFile)
Creates a Script from aFile
containing valid JEXL syntax.JexlScript
createScript(java.io.File scriptFile, java.lang.String... names)
Creates a Script from aFile
containing valid JEXL syntax.JexlScript
createScript(java.lang.String scriptText)
Creates a Script from a String containing valid JEXL syntax.JexlScript
createScript(java.lang.String source, java.lang.String... names)
Creates a Script from a String containing valid JEXL syntax.JexlScript
createScript(java.net.URL scriptUrl)
Creates a Script from aURL
containing valid JEXL syntax.JexlScript
createScript(java.net.URL scriptUrl, java.lang.String... names)
Creates a Script from aURL
containing valid JEXL syntax.abstract JexlScript
createScript(JexlFeatures features, JexlInfo info, java.lang.String source, java.lang.String... names)
Creates a JexlScript from a String containing valid JEXL syntax.JexlScript
createScript(JexlInfo info, java.io.File scriptFile, java.lang.String... names)
Creates a Script from aFile
containing valid JEXL syntax.JexlScript
createScript(JexlInfo info, java.lang.String source, java.lang.String... names)
Creates a JexlScript from a String containing valid JEXL syntax.JexlScript
createScript(JexlInfo info, java.net.URL scriptUrl, java.lang.String... names)
Creates a Script from aURL
containing valid JEXL syntax.abstract JexlArithmetic
getArithmetic()
Gets this engine underlyingJexlArithmetic
.abstract java.nio.charset.Charset
getCharset()
Gets the charset used for parsing.abstract java.lang.Object
getProperty(java.lang.Object bean, java.lang.String expr)
Accesses properties of a bean using an expression.abstract java.lang.Object
getProperty(JexlContext context, java.lang.Object bean, java.lang.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 underlyingJexlUberspect
.abstract java.lang.Object
invokeMethod(java.lang.Object obj, java.lang.String meth, java.lang.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(java.lang.Class<? extends T> clazz, java.lang.Object... args)
Creates a new instance of an object using the most appropriate constructor based on the arguments.abstract java.lang.Object
newInstance(java.lang.String clazz, java.lang.Object... args)
Creates a new instance of an object using the most appropriate constructor based on the arguments.protected java.lang.String
readSource(java.io.File file)
Reads a JEXL source from a File.protected java.lang.String
readSource(java.net.URL url)
Reads a JEXL source from an URL.abstract void
setClassLoader(java.lang.ClassLoader loader)
Sets the class loader used to discover classes in 'new' expressions.abstract void
setProperty(java.lang.Object bean, java.lang.String expr, java.lang.Object value)
Assign properties of a bean using an expression.abstract void
setProperty(JexlContext context, java.lang.Object bean, java.lang.String expr, java.lang.Object value)
Assign properties of a bean using an expression.static void
setThreadContext(JexlContext.ThreadLocal tls)
Sets the current thread local context.protected static java.lang.String
toString(java.io.BufferedReader reader)
Creates a string from a reader.
-
-
-
Field Detail
-
TRY_FAILED
public static final java.lang.Object TRY_FAILED
A marker singleton for invocation failures in tryInvoke.
-
CONTEXT
protected static final java.lang.ThreadLocal<JexlContext.ThreadLocal> CONTEXT
The thread local context.
-
ENGINE
protected static final java.lang.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.
-
JXLT_CACHE_SIZE
private static final int JXLT_CACHE_SIZE
The default Jxlt cache size.- See Also:
- Constant Field Values
-
-
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
-
toString
protected static java.lang.String toString(java.io.BufferedReader reader) throws java.io.IOException
Creates a string from a reader.- Parameters:
reader
- to be read.- Returns:
- the contents of the reader as a String.
- Throws:
java.io.IOException
- on any error reading the reader.
-
clearCache
public abstract void clearCache()
Clears the expression cache.
-
createExpression
public abstract JexlExpression createExpression(JexlInfo info, java.lang.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 neededexpression
- A String containing valid JEXL syntax- Returns:
- An
JexlExpression
which can be evaluated using aJexlContext
- Throws:
JexlException
- if there is a problem parsing the script
-
createExpression
public final JexlExpression createExpression(java.lang.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 aJexlContext
- 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(java.lang.String fn, int l, int c)
Creates a JexlInfo instance.- Parameters:
fn
- url/file/template/script user given namel
- line numberc
- column number- Returns:
- a JexlInfo instance
-
createJxltEngine
public JxltEngine createJxltEngine()
Creates a newJxltEngine
instance using this engine.- Returns:
- a JEXL Template engine
-
createJxltEngine
public JxltEngine createJxltEngine(boolean noScript)
Creates a newJxltEngine
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 ofJxltEngine
using this engine.- Parameters:
noScript
- whether the JxltEngine only allows JEXL expressions or scriptscacheSize
- the number of expressions in this cache, default is 256immediate
- 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(java.io.File scriptFile)
Creates a Script from aFile
containing valid JEXL syntax. This method parses the script and validates the syntax.- Parameters:
scriptFile
- AFile
containing valid JEXL syntax. Must not be null. Must be a readable file.- Returns:
- A
JexlScript
which can be executed with aJexlContext
. - Throws:
JexlException
- if there is a problem reading or parsing the script.
-
createScript
public final JexlScript createScript(java.io.File scriptFile, java.lang.String... names)
Creates a Script from aFile
containing valid JEXL syntax. This method parses the script and validates the syntax.- Parameters:
scriptFile
- AFile
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 aJexlContext
. - Throws:
JexlException
- if there is a problem reading or parsing the script.
-
createScript
public abstract JexlScript createScript(JexlFeatures features, JexlInfo info, java.lang.String source, java.lang.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 parsinginfo
- An info structure to carry debugging information if neededsource
- A string containing valid JEXL syntaxnames
- 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 aJexlContext
- Throws:
JexlException
- if there is a problem parsing the script
-
createScript
public final JexlScript createScript(JexlInfo info, java.io.File scriptFile, java.lang.String... names)
Creates a Script from aFile
containing valid JEXL syntax. This method parses the script and validates the syntax.- Parameters:
info
- An info structure to carry debugging information if neededscriptFile
- AFile
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 aJexlContext
. - Throws:
JexlException
- if there is a problem reading or parsing the script.
-
createScript
public final JexlScript createScript(JexlInfo info, java.lang.String source, java.lang.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 neededsource
- A string containing valid JEXL syntaxnames
- 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 aJexlContext
- Throws:
JexlException
- if there is a problem parsing the script
-
createScript
public final JexlScript createScript(JexlInfo info, java.net.URL scriptUrl, java.lang.String... names)
Creates a Script from aURL
containing valid JEXL syntax. This method parses the script and validates the syntax.- Parameters:
info
- An info structure to carry debugging information if neededscriptUrl
- AURL
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 aJexlContext
. - Throws:
JexlException
- if there is a problem reading or parsing the script.
-
createScript
public final JexlScript createScript(java.lang.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 aJexlContext
- Throws:
JexlException
- if there is a problem parsing the script.
-
createScript
public final JexlScript createScript(java.lang.String source, java.lang.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 syntaxnames
- 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 aJexlContext
- Throws:
JexlException
- if there is a problem parsing the script
-
createScript
public final JexlScript createScript(java.net.URL scriptUrl)
Creates a Script from aURL
containing valid JEXL syntax. This method parses the script and validates the syntax.- Parameters:
scriptUrl
- AURL
containing valid JEXL syntax. Must not be null.- Returns:
- A
JexlScript
which can be executed with aJexlContext
. - Throws:
JexlException
- if there is a problem reading or parsing the script.
-
createScript
public final JexlScript createScript(java.net.URL scriptUrl, java.lang.String... names)
Creates a Script from aURL
containing valid JEXL syntax. This method parses the script and validates the syntax.- Parameters:
scriptUrl
- AURL
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 aJexlContext
. - Throws:
JexlException
- if there is a problem reading or parsing the script.
-
getArithmetic
public abstract JexlArithmetic getArithmetic()
Gets this engine underlyingJexlArithmetic
.- Returns:
- the arithmetic
-
getCharset
public abstract java.nio.charset.Charset getCharset()
Gets the charset used for parsing.- Returns:
- the charset
-
getProperty
public abstract java.lang.Object getProperty(JexlContext context, java.lang.Object bean, java.lang.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 contextbean
- the bean to get properties fromexpr
- 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 java.lang.Object getProperty(java.lang.Object bean, java.lang.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 fromexpr
- 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 underlyingJexlUberspect
.- Returns:
- the uberspect
-
invokeMethod
public abstract java.lang.Object invokeMethod(java.lang.Object obj, java.lang.String meth, java.lang.Object... args)
Invokes an object's method by name and arguments.- Parameters:
obj
- the method's invoker objectmeth
- the method's nameargs
- 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.- 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
-
newInstance
public abstract <T> T newInstance(java.lang.Class<? extends T> clazz, java.lang.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 instantiateargs
- the constructor arguments- Returns:
- the created object instance or null on failure when silent
-
newInstance
public abstract java.lang.Object newInstance(java.lang.String clazz, java.lang.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 loaderargs
- the constructor arguments- Returns:
- the created object instance or null on failure when silent
-
readSource
protected java.lang.String readSource(java.io.File file)
Reads a JEXL source from a File.- Parameters:
file
- the script file- Returns:
- the source
-
readSource
protected java.lang.String readSource(java.net.URL url)
Reads a JEXL source from an URL.- Parameters:
url
- the script url- Returns:
- the source
-
setClassLoader
public abstract void setClassLoader(java.lang.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, java.lang.Object bean, java.lang.String expr, java.lang.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 contextbean
- the bean to set properties inexpr
- the property expressionvalue
- the value of the property- Throws:
JexlException
- if there is an error parsing the expression or during evaluation
-
setProperty
public abstract void setProperty(java.lang.Object bean, java.lang.String expr, java.lang.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 inexpr
- the property expressionvalue
- the value of the property- Throws:
JexlException
- if there is an error parsing the expression or during evaluation
-
-