org.apache.commons.jexl2
Class UnifiedJEXL

java.lang.Object
  extended by org.apache.commons.jexl2.UnifiedJEXL

public final class UnifiedJEXL
extends 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;

Deferred & immediate expression carry different intentions:

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 ecxeptions; 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

Nested Class Summary
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 '#{...}'.
 
Constructor Summary
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
 JexlEngine getEngine()
          Gets the JexlEngine underlying the UnifiedJEXL.
 UnifiedJEXL.Expression parse(String expression)
          Creates a a UnifiedJEXL.Expression from an expression string.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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

parse

public UnifiedJEXL.Expression parse(String expression)
Creates a a UnifiedJEXL.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 the JexlEngine is not silent


Copyright © 2001-2011 Apache Software Foundation. All Rights Reserved.