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