Class UnifiedJEXL
- java.lang.Object
-
- org.apache.commons.jexl2.UnifiedJEXL
-
public final class UnifiedJEXL extends java.lang.Object
An evaluator similar to the Unified EL evaluator used in JSP/JSF based on JEXL. It is intended to be used in configuration modules, XML based frameworks or JSP taglibs and facilitate the implementation of expression evaluation.An expression can mix immediate, deferred and nested sub-expressions as well as string constants;
- The "immediate" syntax is of the form
"...${jexl-expr}..."
- The "deferred" syntax is of the form
"...#{jexl-expr}..."
- The "nested" syntax is of the form
"...#{...${jexl-expr0}...}..."
- The "composite" syntax is of the form
"...${jexl-expr0}... #{jexl-expr1}..."
Deferred & immediate expression carry different intentions:
- An immediate expression indicate that evaluation is intended to be performed close to the definition/parsing point.
- A deferred expression indicate that evaluation is intended to occur at a later stage.
For instance:
"Hello ${name}, now is #{time}"
is a composite "deferred" expression since one of its subexpressions is deferred. Furthermore, this (composite) expression intent is to perform two evaluations; one close to its definition and another one in a later phase.The API reflects this feature in 2 methods, prepare and evaluate. The prepare method will evaluate the immediate subexpression and return an expression that contains only the deferred subexpressions (& constants), a prepared expression. Such a prepared expression is suitable for a later phase evaluation that may occur with a different JexlContext. Note that it is valid to call evaluate without prepare in which case the same JexlContext is used for the 2 evaluation phases.
In the most common use-case where deferred expressions are to be kept around as properties of objects, one should parse & prepare an expression before storing it and evaluate it each time the property storing it is accessed.
Note that nested expression use the JEXL syntax as in:
"#{${bar}+'.charAt(2)'}"
The most common mistake leading to an invalid expression being the following:"#{${bar}charAt(2)}"
Also note that methods that parse evaluate expressions may throw unchecked exceptions; The
UnifiedJEXL.Exception
are thrown when the engine instance is in "non-silent" mode but since these are RuntimeException, user-code should catch them where appropriate.- Since:
- 2.0
- The "immediate" syntax is of the form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
UnifiedJEXL.Exception
The sole type of (runtime) exception the UnifiedJEXL can throw.class
UnifiedJEXL.Expression
The abstract base class for all expressions, immediate '${...}' and deferred '#{...}'.class
UnifiedJEXL.Template
A Template is a script that evaluates by writing its content through a Writer.class
UnifiedJEXL.TemplateContext
The type of context to use during evaluation of templates.
-
Constructor Summary
Constructors Constructor Description UnifiedJEXL(JexlEngine aJexl)
Creates a new instance of UnifiedJEXL with a default size cache.UnifiedJEXL(JexlEngine aJexl, int cacheSize)
Creates a new instance of UnifiedJEXL creating a local cache.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
clearCache()
Clears the cache.UnifiedJEXL.Template
createTemplate(java.lang.String source)
Creates a new template.UnifiedJEXL.Template
createTemplate(java.lang.String prefix, java.io.Reader source, java.lang.String... parms)
Creates a new template.UnifiedJEXL.Template
createTemplate(java.lang.String source, java.lang.String... parms)
Creates a new template.JexlEngine
getEngine()
Gets the JexlEngine underlying the UnifiedJEXL.UnifiedJEXL.Expression
parse(java.lang.String expression)
Creates a aUnifiedJEXL.Expression
from an expression string.protected java.util.List<org.apache.commons.jexl2.UnifiedJEXL.TemplateBlock>
readTemplate(java.lang.String prefix, java.io.Reader source)
Reads lines of a template grouping them by typed blocks.protected int
startsWith(java.lang.CharSequence sequence, java.lang.CharSequence pattern)
Whether a sequence starts with a given set of characters (following spaces).
-
-
-
Constructor Detail
-
UnifiedJEXL
public UnifiedJEXL(JexlEngine aJexl)
Creates a new instance of UnifiedJEXL with a default size cache.- Parameters:
aJexl
- the JexlEngine to use.
-
UnifiedJEXL
public UnifiedJEXL(JexlEngine aJexl, int cacheSize)
Creates a new instance of UnifiedJEXL creating a local cache.- Parameters:
aJexl
- the JexlEngine to use.cacheSize
- the number of expressions in this cache
-
-
Method Detail
-
getEngine
public JexlEngine getEngine()
Gets the JexlEngine underlying the UnifiedJEXL.- Returns:
- the JexlEngine
-
clearCache
public void clearCache()
Clears the cache.- Since:
- 2.1
-
parse
public UnifiedJEXL.Expression parse(java.lang.String expression)
Creates a aUnifiedJEXL.Expression
from an expression string. Uses & fills up the expression cache if any.If the underlying JEXL engine is silent, errors will be logged through its logger as warnings.
- Parameters:
expression
- the UnifiedJEXL string expression- Returns:
- the UnifiedJEXL object expression, null if silent and an error occured
- Throws:
UnifiedJEXL.Exception
- if an error occurs and theJexlEngine
is not silent
-
startsWith
protected int startsWith(java.lang.CharSequence sequence, java.lang.CharSequence pattern)
Whether a sequence starts with a given set of characters (following spaces).Space characters at beginning of line before the pattern are discarded.
- Parameters:
sequence
- the sequencepattern
- the pattern to match at start of sequence- Returns:
- the first position after end of pattern if it matches, -1 otherwise
- Since:
- 2.1
-
readTemplate
protected java.util.List<org.apache.commons.jexl2.UnifiedJEXL.TemplateBlock> readTemplate(java.lang.String prefix, java.io.Reader source)
Reads lines of a template grouping them by typed blocks.- Parameters:
prefix
- the directive prefixsource
- the source reader- Returns:
- the list of blocks
- Since:
- 2.1
-
createTemplate
public UnifiedJEXL.Template createTemplate(java.lang.String prefix, java.io.Reader source, java.lang.String... parms)
Creates a new template.- Parameters:
prefix
- the directive prefixsource
- the sourceparms
- the parameter names- Returns:
- the template
- Since:
- 2.1
-
createTemplate
public UnifiedJEXL.Template createTemplate(java.lang.String source, java.lang.String... parms)
Creates a new template.- Parameters:
source
- the sourceparms
- the parameter names- Returns:
- the template
- Since:
- 2.1
-
createTemplate
public UnifiedJEXL.Template createTemplate(java.lang.String source)
Creates a new template.- Parameters:
source
- the source- Returns:
- the template
- Since:
- 2.1
-
-