org.apache.commons.jexl3.internal
Class Engine

java.lang.Object
  extended by org.apache.commons.jexl3.JexlEngine
      extended by org.apache.commons.jexl3.internal.Engine

public class Engine
extends JexlEngine

A JexlEngine implementation.

Since:
2.0

Nested Class Summary
protected static class Engine.VarCollector
          Utility class to collect variables.
 
Nested classes/interfaces inherited from class org.apache.commons.jexl3.JexlEngine
JexlEngine.Options
 
Field Summary
protected  JexlArithmetic arithmetic
          The JexlArithmetic instance.
protected  SoftCache<String,ASTJexlScript> cache
          The expression cache.
protected  int cacheThreshold
          The expression max length to hit the cache.
protected  boolean cancellable
          Whether expressions evaluated by this engine will throw JexlException.Cancel (true) or return null (false) when interrupted.
protected  Charset charset
          The default charset.
protected  boolean debug
          Whether error messages will carry debugging information.
protected  Map<String,Object> functions
          The map of 'prefix:function' to object implementing the namespaces.
protected  TemplateEngine jxlt
          The default jxlt engine.
protected  org.apache.commons.logging.Log logger
          The Log to which all JexlEngine messages will be logged.
protected  Parser parser
          The Parser; when parsing expressions, this engine uses the parser if it is not already in use otherwise it will create a new temporary one.
protected  AtomicBoolean parsing
          The atomic parsing flag; true whilst parsing.
protected  boolean silent
          Whether expressions evaluated by this engine will throw exceptions (false) or return null (true) on errors.
protected  boolean strict
          Whether this engine considers unknown variables, methods and constructors as errors.
protected  JexlUberspect uberspect
          The JexlUberspect instance.
 
Fields inherited from class org.apache.commons.jexl3.JexlEngine
CONTEXT, EMPTY_CONTEXT, EMPTY_NS, TRY_FAILED
 
Constructor Summary
Engine()
          Creates an engine with default arguments.
Engine(JexlBuilder conf)
          Creates a JEXL engine using the provided JexlBuilder.
 
Method Summary
 void clearCache()
          Clears the expression cache.
 Script createExpression(JexlInfo info, String expression)
          Creates an JexlExpression from a String containing valid JEXL syntax.
protected  Interpreter createInterpreter(JexlContext context, Scope.Frame frame)
          Creates an interpreter.
 TemplateEngine createJxltEngine(boolean noScript, int cacheSize, char immediate, char deferred)
          Creates a new instance of JxltEngine using this engine.
 Script createScript(JexlInfo info, String scriptText, String[] names)
          Creates a JexlScript from a String containing valid JEXL syntax.
protected  Object doCreateInstance(Object clazz, Object... args)
          Creates a new instance of an object using the most appropriate constructor based on the arguments.
 JexlArithmetic getArithmetic()
          Gets this engine underlying JexlArithmetic.
 Charset getCharset()
          Gets the charset used for parsing.
protected  String[] getLocalVariables(JexlScript script)
          Gets the array of local variable from a script.
protected  String[] getParameters(JexlScript script)
          Gets the array of parameters from a script.
 Object getProperty(JexlContext context, Object bean, String expr)
          Accesses properties of a bean using an expression.
 Object getProperty(Object bean, String expr)
          Accesses properties of a bean using an expression.
 JexlUberspect getUberspect()
          Gets this engine underlying JexlUberspect.
static Uberspect getUberspect(org.apache.commons.logging.Log logger, JexlUberspect.ResolverStrategy strategy)
          Gets the default instance of Uberspect.
protected  Set<List<String>> 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.
 Object invokeMethod(Object obj, String meth, Object... args)
          Invokes an object's method by name and arguments.
 boolean isCancellable()
          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.
 Object newInstance(String clazz, Object... args)
          Creates a new instance of an object using the most appropriate constructor based on the arguments.
protected  ASTJexlScript parse(JexlInfo info, String src, Scope scope, boolean registers, boolean expression)
          Parses an expression.
protected  JexlContext.ThreadLocal putThreadLocal(JexlContext.ThreadLocal tls)
          Swaps the current thread local context.
 void setClassLoader(ClassLoader loader)
          Sets the class loader used to discover classes in 'new' expressions.
 void setProperty(JexlContext context, Object bean, String expr, Object value)
          Assign properties of a bean using an expression.
 void setProperty(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.
 
Methods inherited from class org.apache.commons.jexl3.JexlEngine
createExpression, createInfo, createInfo, createJxltEngine, createJxltEngine, createScript, createScript, createScript, createScript, createScript, createScript, createScript, createScript, getThreadContext, readSource, readSource, setThreadContext, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

uberspect

protected final JexlUberspect uberspect
The JexlUberspect instance.


arithmetic

protected final JexlArithmetic arithmetic
The JexlArithmetic instance.


logger

protected final org.apache.commons.logging.Log logger
The Log to which all JexlEngine messages will be logged.


parsing

protected final AtomicBoolean parsing
The atomic parsing flag; true whilst parsing.


parser

protected final Parser parser
The Parser; when parsing expressions, this engine uses the parser if it is not already in use otherwise it will create a new temporary one.


strict

protected final boolean strict
Whether this engine considers unknown variables, methods and constructors as errors.


silent

protected final boolean silent
Whether expressions evaluated by this engine will throw exceptions (false) or return null (true) on errors. Default is false.


cancellable

protected final boolean cancellable
Whether 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 debug
Whether error messages will carry debugging information.


functions

protected final Map<String,Object> functions
The map of 'prefix:function' to object implementing the namespaces.


cache

protected final SoftCache<String,ASTJexlScript> cache
The expression cache.


cacheThreshold

protected final int cacheThreshold
The expression max length to hit the cache.


charset

protected final Charset charset
The default charset.


jxlt

protected volatile TemplateEngine jxlt
The default jxlt engine.

Constructor Detail

Engine

public Engine()
Creates an engine with default arguments.


Engine

public Engine(JexlBuilder conf)
Creates a JEXL engine using the provided JexlBuilder.

Parameters:
conf - the builder
Method Detail

getUberspect

public static Uberspect getUberspect(org.apache.commons.logging.Log logger,
                                     JexlUberspect.ResolverStrategy strategy)
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.

Parameters:
logger - the logger to use for the underlying Uberspect
strategy - the property resolver strategy
Returns:
Uberspect the default uberspector instance.

getUberspect

public JexlUberspect getUberspect()
Description copied from class: JexlEngine
Gets this engine underlying JexlUberspect.

Specified by:
getUberspect in class JexlEngine
Returns:
the uberspect

getArithmetic

public JexlArithmetic getArithmetic()
Description copied from class: JexlEngine
Gets this engine underlying JexlArithmetic.

Specified by:
getArithmetic in class JexlEngine
Returns:
the arithmetic

isDebug

public boolean isDebug()
Description copied from class: JexlEngine
Checks whether this engine is in debug mode.

Specified by:
isDebug in class JexlEngine
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 class JexlEngine
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 class JexlEngine
Returns:
true if strict, false otherwise

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 class JexlEngine
Returns:
true if cancellable, false otherwise

setClassLoader

public void setClassLoader(ClassLoader loader)
Description copied from class: JexlEngine
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.

Specified by:
setClassLoader in class JexlEngine
Parameters:
loader - the class loader to use

getCharset

public Charset getCharset()
Description copied from class: JexlEngine
Gets the charset used for parsing.

Specified by:
getCharset in class JexlEngine
Returns:
the charset

createJxltEngine

public TemplateEngine createJxltEngine(boolean noScript,
                                       int cacheSize,
                                       char immediate,
                                       char deferred)
Description copied from class: JexlEngine
Creates a new instance of JxltEngine using this engine.

Specified by:
createJxltEngine in class JexlEngine
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 void clearCache()
Description copied from class: JexlEngine
Clears the expression cache.

Specified by:
clearCache in class JexlEngine

createInterpreter

protected Interpreter createInterpreter(JexlContext context,
                                        Scope.Frame frame)
Creates an interpreter.

Parameters:
context - a JexlContext; if null, the empty context is used instead.
frame - the interpreter frame
Returns:
an Interpreter

createScript

public Script createScript(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 class JexlEngine
Parameters:
info - An info structure to carry debugging information if needed
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

createExpression

public Script createExpression(JexlInfo info,
                               String expression)
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 class JexlEngine
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

getProperty

public Object getProperty(Object bean,
                          String expr)
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 class JexlEngine
Parameters:
bean - the bean to get properties from
expr - the property expression
Returns:
the value of the property

getProperty

public Object getProperty(JexlContext context,
                          Object bean,
                          String expr)
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 class JexlEngine
Parameters:
context - the evaluation context
bean - the bean to get properties from
expr - the property expression
Returns:
the value of the property

setProperty

public void setProperty(Object bean,
                        String expr,
                        Object value)
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 class JexlEngine
Parameters:
bean - the bean to set properties in
expr - the property expression
value - the value of the property

setProperty

public void setProperty(JexlContext context,
                        Object bean,
                        String expr,
                        Object value)
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 class JexlEngine
Parameters:
context - the evaluation context
bean - the bean to set properties in
expr - the property expression
value - the value of the property

invokeMethod

public Object invokeMethod(Object obj,
                           String meth,
                           Object... args)
Description copied from class: JexlEngine
Invokes an object's method by name and arguments.

Specified by:
invokeMethod in class JexlEngine
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

newInstance

public <T> T newInstance(Class<? extends T> clazz,
                         Object... args)
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 class JexlEngine
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 Object newInstance(String clazz,
                          Object... args)
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 class JexlEngine
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

doCreateInstance

protected Object doCreateInstance(Object clazz,
                                  Object... args)
Creates a new instance of an object using the most appropriate constructor based on the arguments.

Parameters:
clazz - the class to instantiate
args - the constructor arguments
Returns:
the created object instance or null on failure when silent

putThreadLocal

protected JexlContext.ThreadLocal putThreadLocal(JexlContext.ThreadLocal tls)
Swaps the current thread local context.

Parameters:
tls - the context or null
Returns:
the previous thread local context

getVariables

protected Set<List<String>> getVariables(ASTJexlScript script)
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

protected void getVariables(ASTJexlScript script,
                            JexlNode node,
                            Engine.VarCollector collector)
Fills up the list of variables accessed by a node.

Parameters:
script - the owning script
node - the node
collector - the variable collector

getParameters

protected String[] getParameters(JexlScript script)
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

getLocalVariables

protected String[] getLocalVariables(JexlScript script)
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

parse

protected ASTJexlScript parse(JexlInfo info,
                              String src,
                              Scope scope,
                              boolean registers,
                              boolean expression)
Parses an expression.

Parameters:
info - information structure
src - the expression to parse
scope - the script frame
registers - whether the parser should allow the unnamed '#number' syntax for 'registers'
expression - whether the parser allows scripts or only expressions
Returns:
the parsed tree
Throws:
JexlException - if any error occurred during parsing

trimSource

protected String trimSource(CharSequence str)
Trims the source from front and ending spaces.

Parameters:
str - expression to clean
Returns:
trimmed expression ending in a semi-colon

jxlt

protected TemplateEngine jxlt()
Gets and/or creates a default template engine.

Returns:
a template engine


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