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