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 javax.servlet.jsp.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 }
|