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