Class Engine
- Direct Known Subclasses:
Engine32
- Since:
- 2.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
Gets the default instance of Uberspect.protected static class
Utility class to collect variables.Nested classes/interfaces inherited from class org.apache.commons.jexl3.JexlEngine
JexlEngine.EmptyContext, JexlEngine.EmptyNamespaceResolver, JexlEngine.Options
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final JexlArithmetic
TheJexlArithmetic
instance.protected final JexlCache
<Source, ASTJexlScript> The expression cache.protected final IntFunction
<JexlCache<?, ?>> The cache factory method.protected final int
The expression max length to hit the cache.protected final boolean
Whether expressions evaluated by this engine will throw JexlException.Cancel (true) or return null (false) when interrupted.protected final Charset
The default charset.protected final FqcnResolver
The default class name resolver.protected final int
Collect all or only dot references.protected final boolean
Whether error messages will carry debugging information.protected final JexlFeatures
The set of default expression parsing features.The map of 'prefix:function' to object implementing the namespaces.protected TemplateEngine
The default jxlt engine.protected final org.apache.commons.logging.Log
The Log to which all JexlEngine messages will be logged.protected final JexlOptions
A cached version of the options.protected final Parser
TheParser
; when parsing expressions, this engine uses the parser if it is not already in use otherwise it will create a new temporary one.protected final AtomicBoolean
The atomic parsing flag; true whilst parsing.protected static final JexlFeatures
The features allowed for property set/get methods.protected final boolean
Whether this engine considers null in navigation expression as errors.protected final JexlFeatures
The set of default script parsing features.protected final boolean
Whether expressions evaluated by this engine will throw exceptions (false) or return null (true) on errors.protected final int
The maximum stack height.protected final boolean
Whether this engine considers unknown variables, methods and constructors as errors.protected final JexlUberspect
The JexlUberspect instance.Fields inherited from class org.apache.commons.jexl3.JexlEngine
CONTEXT, DEFAULT_FEATURES, EMPTY_CONTEXT, EMPTY_NS, ENGINE, TRY_FAILED
-
Constructor Summary
ConstructorsConstructorDescriptionEngine()
Creates an engine with default arguments.Engine
(JexlBuilder conf) Creates a JEXL engine using the providedJexlBuilder
. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Clears the expression cache.createExpression
(JexlInfo info, String expression) Creates an JexlExpression from a String containing valid JEXL syntax.protected Interpreter
createInterpreter
(JexlContext context, Frame frame, JexlOptions opts) Creates an interpreter.createJxltEngine
(boolean noScript, int cacheSize, char immediate, char deferred) Creates a new instance ofJxltEngine
using this engine.createScript
(JexlFeatures features, JexlInfo info, String scriptText, String... names) Creates a JexlScript from a String containing valid JEXL syntax.protected Interpreter
Creates a template interpreter.protected Object
doCreateInstance
(Object clazz, Object... args) Creates a new instance of an object using the most appropriate constructor based on the arguments.protected JexlOptions
evalOptions
(JexlContext context) Extracts the engine evaluation options from context if available, the engine options otherwise.private JexlOptions
Obsolete version of options evaluation.protected JexlOptions
evalOptions
(ASTJexlScript script, JexlContext context) Compute a script options for evaluation.Gets this engine underlyingJexlArithmetic
.Gets the charset used for parsing.protected String[]
getLocalVariables
(JexlScript script) Gets the array of local variable from a script.(package private) final Object
getNamespace
(String name) Solves a namespace using this engine map of functions.protected String[]
getParameters
(JexlScript script) Gets the array of parameters from a script.getProperty
(Object bean, String expr) Accesses properties of a bean using an expression.getProperty
(JexlContext context, Object bean, String expr) Accesses properties of a bean using an expression.Gets this engine underlyingJexlUberspect
.static Uberspect
getUberspect
(org.apache.commons.logging.Log logger, JexlUberspect.ResolverStrategy strategy) Deprecated.3.3static Uberspect
getUberspect
(org.apache.commons.logging.Log logger, JexlUberspect.ResolverStrategy strategy, JexlPermissions permissions) Gets the default instance of Uberspect.getVariables
(ASTJexlScript script) Gets the list of variables accessed by a script.protected void
getVariables
(ASTJexlScript script, JexlNode node, Engine.VarCollector collector) Fills up the list of variables accessed by a node.invokeMethod
(Object obj, String meth, Object... args) Invokes an object's method by name and arguments.boolean
Checks whether this engine will throw JexlException.Cancel (true) or return null (false) when interrupted during an execution.boolean
isDebug()
Checks whether this engine is in debug mode.boolean
isSilent()
Checks whether this engine throws JexlException during evaluation.boolean
isStrict()
Checks whether this engine considers unknown variables, methods, functions and constructors as errors.protected TemplateEngine
jxlt()
Gets and/or creates a default template engine.<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.newInstance
(String clazz, Object... args) Creates a new instance of an object using the most appropriate constructor based on the arguments.private static <T> T
option
(T conf, T def) Solves an optional option.optionsSet
(JexlOptions opts) Sets options from this engine options.protected ASTJexlScript
Parses an expression.protected ASTJexlScript
parse
(JexlInfo info, JexlFeatures parsingf, String src, Scope scope) Parses an expression.private void
processPragmaModule
(Map<String, Object> ns, String key, Object value, JexlInfo info, JexlContext context) Processes jexl.module.ns pragma.private void
Processes jexl.namespace.ns pragma.protected void
processPragmas
(ASTJexlScript script, JexlContext context, JexlOptions opts) Processes a script pragmas.protected JexlEngine
putThreadEngine
(JexlEngine jexl) Swaps the current thread local engine.protected JexlContext.ThreadLocal
Swaps the current thread local context.void
setClassLoader
(ClassLoader loader) Sets the class loader used to discover classes in 'new' expressions.void
setProperty
(Object bean, String expr, Object value) Assign properties of a bean using an expression.void
setProperty
(JexlContext context, Object bean, String expr, Object value) Assign properties of a bean using an expression.protected String
trimSource
(CharSequence str) Trims the source from front and ending spaces.protected Engine.VarCollector
Creates a collector instance.private void
withValueSet
(Object value, Consumer<Object> consumer) Utility to deal with single value or set of values.Methods inherited from class org.apache.commons.jexl3.JexlEngine
createExpression, createInfo, createInfo, createJxltEngine, createJxltEngine, createScript, createScript, createScript, createScript, createScript, createScript, createScript, createScript, createScript, getThreadContext, getThreadEngine, readSource, readSource, setThreadContext, toString
-
Field Details
-
PROPERTY_FEATURES
The features allowed for property set/get methods. -
logger
protected final org.apache.commons.logging.Log loggerThe Log to which all JexlEngine messages will be logged. -
uberspect
The JexlUberspect instance. -
arithmetic
TheJexlArithmetic
instance. -
functions
The map of 'prefix:function' to object implementing the namespaces. -
classNameSolver
The default class name resolver. -
stackOverflow
protected final int stackOverflowThe maximum stack height. -
strict
protected final boolean strictWhether this engine considers unknown variables, methods and constructors as errors. -
safe
protected final boolean safeWhether this engine considers null in navigation expression as errors. -
silent
protected final boolean silentWhether expressions evaluated by this engine will throw exceptions (false) or return null (true) on errors. Default is false. -
cancellable
protected final boolean cancellableWhether expressions evaluated by this engine will throw JexlException.Cancel (true) or return null (false) when interrupted. Default is true when not silent and strict. -
debug
protected final boolean debugWhether error messages will carry debugging information. -
scriptFeatures
The set of default script parsing features. -
expressionFeatures
The set of default expression parsing features. -
charset
The default charset. -
parsing
The atomic parsing flag; true whilst parsing. -
parser
TheParser
; when parsing expressions, this engine uses the parser if it is not already in use otherwise it will create a new temporary one. -
cacheThreshold
protected final int cacheThresholdThe expression max length to hit the cache. -
cache
The expression cache. -
jxlt
The default jxlt engine. -
collectMode
protected final int collectModeCollect all or only dot references. -
options
A cached version of the options. -
cacheFactory
The cache factory method.
-
-
Constructor Details
-
Engine
public Engine()Creates an engine with default arguments. -
Engine
Creates a JEXL engine using the providedJexlBuilder
.- Parameters:
conf
- the builder
-
-
Method Details
-
getUberspect
@Deprecated public static Uberspect getUberspect(org.apache.commons.logging.Log logger, JexlUberspect.ResolverStrategy strategy) Deprecated.3.3- Parameters:
logger
- the loggerstrategy
- the strategy- Returns:
- an Uberspect instance
-
getUberspect
public static Uberspect getUberspect(org.apache.commons.logging.Log logger, JexlUberspect.ResolverStrategy strategy, JexlPermissions permissions) Gets the default instance of Uberspect.This is lazily initialized to avoid building a default instance if there is no use for it. The main reason for not using the default Uberspect instance is to be able to use a (low level) introspector created with a given logger instead of the default one and even more so for with a different (restricted) set of permissions.
- Parameters:
logger
- the logger to use for the underlying Uberspectstrategy
- the property resolver strategypermissions
- the introspection permissions- Returns:
- Uberspect the default uberspector instance.
- Since:
- 3.3
-
option
private static <T> T option(T conf, T def) Solves an optional option.- Type Parameters:
T
- the option type- Parameters:
conf
- the option as configured, may be nulldef
- the default value if null, shall not be null- Returns:
- conf or def
-
clearCache
public void clearCache()Description copied from class:JexlEngine
Clears the expression cache.- Specified by:
clearCache
in classJexlEngine
-
createExpression
Description copied from class:JexlEngine
Creates an JexlExpression from a String containing valid JEXL syntax. This method parses the expression which must contain either a reference or an expression.- Specified by:
createExpression
in classJexlEngine
- 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
-
createInterpreter
Creates an interpreter.- Parameters:
context
- a JexlContext; if null, the empty context is used instead.frame
- the interpreter frameopts
- the evaluation options- Returns:
- an Interpreter
-
createJxltEngine
public TemplateEngine createJxltEngine(boolean noScript, int cacheSize, char immediate, char deferred) Description copied from class:JexlEngine
Creates a new instance ofJxltEngine
using this engine.- Specified by:
createJxltEngine
in classJexlEngine
- 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 Script createScript(JexlFeatures features, JexlInfo info, String scriptText, String... names) Description copied from class:JexlEngine
Creates a JexlScript from a String containing valid JEXL syntax. This method parses the script and validates the syntax.- Specified by:
createScript
in classJexlEngine
- Parameters:
features
- A set of features that will be enforced during parsinginfo
- An info structure to carry debugging information if neededscriptText
- 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
-
createTemplateInterpreter
Creates a template interpreter.- Parameters:
args
- the template interpreter arguments
-
doCreateInstance
Creates a new instance of an object using the most appropriate constructor based on the arguments.- Parameters:
clazz
- the class to instantiateargs
- the constructor arguments- Returns:
- the created object instance or null on failure when silent
-
evalOptions
Compute a script options for evaluation.This calls processPragma(...).
- Parameters:
script
- the scriptcontext
- the context- Returns:
- the options
-
evalOptions
Extracts the engine evaluation options from context if available, the engine options otherwise.If the context is an options handle and the handled options shared instance flag is false, this method creates a copy of the options making them immutable during execution.
- Parameters:
context
- the context- Returns:
- the options if any
-
evalOptions
Obsolete version of options evaluation.- Parameters:
opts
- the obsolete instance of options- Returns:
- the newer class of options
-
getArithmetic
Description copied from class:JexlEngine
Gets this engine underlyingJexlArithmetic
.- Specified by:
getArithmetic
in classJexlEngine
- Returns:
- the arithmetic
-
getCharset
Description copied from class:JexlEngine
Gets the charset used for parsing.- Specified by:
getCharset
in classJexlEngine
- Returns:
- the charset
-
getLocalVariables
Gets the array of local variable from a script.- Parameters:
script
- the script- Returns:
- the local variables array which may be empty (but not null) if no local variables were defined
- Since:
- 3.0
-
getNamespace
Solves a namespace using this engine map of functions.- Parameters:
name
- the namespoce name- Returns:
- the object associated
-
getParameters
Gets the array of parameters from a script.- Parameters:
script
- the script- Returns:
- the parameters which may be empty (but not null) if no parameters were defined
- Since:
- 3.0
-
getProperty
Description copied from class:JexlEngine
Accesses properties of a bean using an expression.If the JEXL engine is silent, errors will be logged through its logger as warning.
- Specified by:
getProperty
in classJexlEngine
- Parameters:
context
- the evaluation contextbean
- the bean to get properties fromexpr
- the property expression- Returns:
- the value of the property
-
getProperty
Description copied from class:JexlEngine
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.
- Specified by:
getProperty
in classJexlEngine
- Parameters:
bean
- the bean to get properties fromexpr
- the property expression- Returns:
- the value of the property
-
getUberspect
Description copied from class:JexlEngine
Gets this engine underlyingJexlUberspect
.- Specified by:
getUberspect
in classJexlEngine
- Returns:
- the uberspect
-
getVariables
Gets the list of variables accessed by a script.This method will visit all nodes of a script and extract all variables whether they are written in 'dot' or 'bracketed' notation. (a.b is equivalent to a['b']).
- Parameters:
script
- the script- Returns:
- the set of variables, each as a list of strings (ant-ish variables use more than 1 string) or the empty set if no variables are used
-
getVariables
Fills up the list of variables accessed by a node.- Parameters:
script
- the owning scriptnode
- the nodecollector
- the variable collector
-
invokeMethod
Description copied from class:JexlEngine
Invokes an object's method by name and arguments.- Specified by:
invokeMethod
in classJexlEngine
- 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
-
isCancellable
public boolean isCancellable()Description copied from class:JexlEngine
Checks whether this engine will throw JexlException.Cancel (true) or return null (false) when interrupted during an execution.- Specified by:
isCancellable
in classJexlEngine
- Returns:
- true if cancellable, false otherwise
-
isDebug
public boolean isDebug()Description copied from class:JexlEngine
Checks whether this engine is in debug mode.- Specified by:
isDebug
in classJexlEngine
- Returns:
- true if debug is on, false otherwise
-
isSilent
public boolean isSilent()Description copied from class:JexlEngine
Checks whether this engine throws JexlException during evaluation.- Specified by:
isSilent
in classJexlEngine
- Returns:
- true if silent, false (default) otherwise
-
isStrict
public boolean isStrict()Description copied from class:JexlEngine
Checks whether this engine considers unknown variables, methods, functions and constructors as errors.- Specified by:
isStrict
in classJexlEngine
- Returns:
- true if strict, false otherwise
-
jxlt
Gets and/or creates a default template engine.- Returns:
- a template engine
-
newInstance
Description copied from class:JexlEngine
Creates a new instance of an object using the most appropriate constructor based on the arguments.- Specified by:
newInstance
in classJexlEngine
- 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
Description copied from class:JexlEngine
Creates a new instance of an object using the most appropriate constructor based on the arguments.- Specified by:
newInstance
in classJexlEngine
- 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
-
optionsSet
Sets options from this engine options.- Parameters:
opts
- the options to set- Returns:
- the options
-
parse
Parses an expression.- Parameters:
info
- information structureexpr
- whether we parse an expression or a featuresrc
- the expression to parsescope
- the script frame- Returns:
- the parsed tree
- Throws:
JexlException
- if any error occurred during parsing
-
parse
Parses an expression.- Parameters:
info
- information structureparsingf
- the set of parsing featuressrc
- the expression to parsescope
- the script frame- Returns:
- the parsed tree
- Throws:
JexlException
- if any error occurred during parsing
-
processPragmaModule
private void processPragmaModule(Map<String, Object> ns, String key, Object value, JexlInfo info, JexlContext context) Processes jexl.module.ns pragma.If the value is empty, the namespace will be cleared which may be useful to debug and force unload the object bound to the namespace.
- Parameters:
ns
- the namespace mapkey
- the key the namespacevalue
- the value, ie the expression to evaluate and its result bound to the namespaceinfo
- the expression infocontext
- the value-as-expression evaluation context
-
processPragmaNamespace
Processes jexl.namespace.ns pragma.- Parameters:
ns
- the namespace mapkey
- the keyvalue
- the value, ie the class
-
processPragmas
Processes a script pragmas.Only called from options(...)
- Parameters:
script
- the scriptcontext
- the contextopts
- the options
-
putThreadEngine
Swaps the current thread local engine.- Parameters:
jexl
- the engine or null- Returns:
- the previous thread local engine
-
putThreadLocal
Swaps the current thread local context.- Parameters:
tls
- the context or null- Returns:
- the previous thread local context
-
setClassLoader
Description copied from class:JexlEngine
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.
- Specified by:
setClassLoader
in classJexlEngine
- Parameters:
loader
- the class loader to use
-
setProperty
Description copied from class:JexlEngine
Assign properties of a bean using an expression.If the JEXL engine is silent, errors will be logged through its logger as warning.
- Specified by:
setProperty
in classJexlEngine
- Parameters:
context
- the evaluation contextbean
- the bean to set properties inexpr
- the property expressionvalue
- the value of the property
-
setProperty
Description copied from class:JexlEngine
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.
- Specified by:
setProperty
in classJexlEngine
- Parameters:
bean
- the bean to set properties inexpr
- the property expressionvalue
- the value of the property
-
trimSource
Trims the source from front and ending spaces.- Parameters:
str
- expression to clean- Returns:
- trimmed expression ending in a semicolon
-
varCollector
Creates a collector instance.- Returns:
- a collector instance
-
withValueSet
Utility to deal with single value or set of values.- Parameters:
value
- the value or the setconsumer
- the consumer of values
-