001: /*
002: * Copyright 2004 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.jbpm.jpdl.el;
018:
019: /**
020: * <p>The abstract base class for an expression-language evaluator.
021: * Classes that implement an expression language expose their functionality
022: * via this abstract class.</p>
023: *
024: * <p>An instance of the ExpressionEvaluator can be obtained via the
025: * JspContext / PageContext</p>
026: *
027: * <p>The parseExpression() and evaluate() methods must be thread-safe.
028: * That is, multiple threads may call these methods on the same
029: * ExpressionEvaluator object simultaneously. Implementations should
030: * synchronize access if they depend on transient state. Implementations
031: * should not, however, assume that only one object of each
032: * ExpressionEvaluator type will be instantiated; global caching should
033: * therefore be static.</p>
034: *
035: * <p>Only a single EL expression, starting with '${' and ending with
036: * '}', can be parsed or evaluated at a time. EL expressions
037: * cannot be mixed with static text. For example, attempting to
038: * parse or evaluate "<code>abc${1+1}def${1+1}ghi</code>" or even
039: * "<code>${1+1}${1+1}</code>" will cause an <code>ELException</code> to
040: * be thrown.</p>
041: *
042: * <p>The following are examples of syntactically legal EL expressions:
043: *
044: * <ul>
045: * <li><code>${person.lastName}</code></li>
046: * <li><code>${8 * 8}</code></li>
047: * <li><code>${my:reverse('hello')}</code></li>
048: * </ul>
049: * </p>
050: *
051: * @since 2.0
052: */
053: public abstract class ExpressionEvaluator {
054:
055: /**
056: * Prepare an expression for later evaluation. This method should perform
057: * syntactic validation of the expression; if in doing so it detects
058: * errors, it should raise an ELParseException.
059: *
060: * @param expression The expression to be evaluated.
061: * @param expectedType The expected type of the result of the evaluation
062: * @param fMapper A FunctionMapper to resolve functions found in
063: * the expression. It can be null, in which case no functions
064: * are supported for this invocation. The ExpressionEvaluator
065: * must not hold on to the FunctionMapper reference after
066: * returning from <code>parseExpression()</code>. The
067: * <code>Expression</code> object returned must invoke the same
068: * functions regardless of whether the mappings in the
069: * provided <code>FunctionMapper</code> instance change between
070: * calling <code>ExpressionEvaluator.parseExpression()</code>
071: * and <code>Expression.evaluate()</code>.
072: * @return The Expression object encapsulating the arguments.
073: *
074: * @exception ELException Thrown if parsing errors were found.
075: */
076: public abstract Expression parseExpression(String expression,
077: Class expectedType, FunctionMapper fMapper)
078: throws ELException;
079:
080: /**
081: * Evaluates an expression. This method may perform some syntactic
082: * validation and, if so, it should raise an ELParseException error if
083: * it encounters syntactic errors. EL evaluation errors should cause
084: * an ELException to be raised.
085: *
086: * @param expression The expression to be evaluated.
087: * @param expectedType The expected type of the result of the evaluation
088: * @param vResolver A VariableResolver instance that can be used at
089: * runtime to resolve the name of implicit objects into Objects.
090: * @param fMapper A FunctionMapper to resolve functions found in
091: * the expression. It can be null, in which case no functions
092: * are supported for this invocation.
093: * @return The result of the expression evaluation.
094: *
095: * @exception ELException Thrown if the expression evaluation failed.
096: */
097: public abstract Object evaluate(String expression,
098: Class expectedType, VariableResolver vResolver,
099: FunctionMapper fMapper) throws ELException;
100: }
|