1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * Portions Copyright Apache Software Foundation.
7 *
8 * The contents of this file are subject to the terms of either the GNU
9 * General Public License Version 2 only ("GPL") or the Common Development
10 * and Distribution License("CDDL") (collectively, the "License"). You
11 * may not use this file except in compliance with the License. You can obtain
12 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
13 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
14 * language governing permissions and limitations under the License.
15 *
16 * When distributing the software, include this License Header Notice in each
17 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
18 * Sun designates this particular file as subject to the "Classpath" exception
19 * as provided by Sun in the GPL Version 2 section of the License file that
20 * accompanied this code. If applicable, add the following below the License
21 * Header, with the fields enclosed by brackets [] replaced by your own
22 * identifying information: "Portions Copyrighted [year]
23 * [name of copyright owner]"
24 *
25 * Contributor(s):
26 *
27 * If you wish your version of this file to be governed by only the CDDL or
28 * only the GPL Version 2, indicate your decision by adding "[Contributor]
29 * elects to include this software in this distribution under the [CDDL or GPL
30 * Version 2] license." If you don't indicate a single choice of license, a
31 * recipient has the option to distribute your version of this file under
32 * either the CDDL, the GPL Version 2 or to extend the choice of license to
33 * its licensees as provided above. However, if you add GPL Version 2 code
34 * and therefore, elected the GPL Version 2 license, then the option applies
35 * only if the new code is made subject to such option by the copyright
36 * holder.
37 */
38
39 package javax.servlet.jsp.el;
40
41 import javax.servlet;
42 import javax.servlet.jsp;
43 import javax.servlet.jsp.tagext;
44 import java.util.Map;
45
46 /**
47 * <p>The abstract base class for an expression-language evaluator.
48 * Classes that implement an expression language expose their functionality
49 * via this abstract class.</p>
50 *
51 * <p>An instance of the ExpressionEvaluator can be obtained via the
52 * JspContext / PageContext</p>
53 *
54 * <p>The parseExpression() and evaluate() methods must be thread-safe.
55 * That is, multiple threads may call these methods on the same
56 * ExpressionEvaluator object simultaneously. Implementations should
57 * synchronize access if they depend on transient state. Implementations
58 * should not, however, assume that only one object of each
59 * ExpressionEvaluator type will be instantiated; global caching should
60 * therefore be static.</p>
61 *
62 * <p>Only a single EL expression, starting with '${' and ending with
63 * '}', can be parsed or evaluated at a time. EL expressions
64 * cannot be mixed with static text. For example, attempting to
65 * parse or evaluate "<code>abc${1+1}def${1+1}ghi</code>" or even
66 * "<code>${1+1}${1+1}</code>" will cause an <code>ELException</code> to
67 * be thrown.</p>
68 *
69 * <p>The following are examples of syntactically legal EL expressions:
70 *
71 * <ul>
72 * <li><code>${person.lastName}</code></li>
73 * <li><code>${8 * 8}</code></li>
74 * <li><code>${my:reverse('hello')}</code></li>
75 * </ul>
76 * </p>
77 *
78 * @since 2.0
79 */
80 public abstract class ExpressionEvaluator {
81
82 /**
83 * Prepare an expression for later evaluation. This method should perform
84 * syntactic validation of the expression; if in doing so it detects
85 * errors, it should raise an ELParseException.
86 *
87 * @param expression The expression to be evaluated.
88 * @param expectedType The expected type of the result of the evaluation
89 * @param fMapper A FunctionMapper to resolve functions found in
90 * the expression. It can be null, in which case no functions
91 * are supported for this invocation. The ExpressionEvaluator
92 * must not hold on to the FunctionMapper reference after
93 * returning from <code>parseExpression()</code>. The
94 * <code>Expression</code> object returned must invoke the same
95 * functions regardless of whether the mappings in the
96 * provided <code>FunctionMapper</code> instance change between
97 * calling <code>ExpressionEvaluator.parseExpression()</code>
98 * and <code>Expression.evaluate()</code>.
99 * @return The Expression object encapsulating the arguments.
100 *
101 * @exception ELException Thrown if parsing errors were found.
102 */
103 public abstract Expression parseExpression( String expression,
104 Class expectedType,
105 FunctionMapper fMapper )
106 throws ELException;
107
108
109 /**
110 * Evaluates an expression. This method may perform some syntactic
111 * validation and, if so, it should raise an ELParseException error if
112 * it encounters syntactic errors. EL evaluation errors should cause
113 * an ELException to be raised.
114 *
115 * @param expression The expression to be evaluated.
116 * @param expectedType The expected type of the result of the evaluation
117 * @param vResolver A VariableResolver instance that can be used at
118 * runtime to resolve the name of implicit objects into Objects.
119 * @param fMapper A FunctionMapper to resolve functions found in
120 * the expression. It can be null, in which case no functions
121 * are supported for this invocation.
122 * @return The result of the expression evaluation.
123 *
124 * @exception ELException Thrown if the expression evaluation failed.
125 */
126 public abstract Object evaluate( String expression,
127 Class expectedType,
128 VariableResolver vResolver,
129 FunctionMapper fMapper )
130 throws ELException;
131 }
132
Save This Page