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