Skip to contentPackage: MethodExpression
MethodExpression
Coverage
1: /*
2: * Copyright (c) 1997, 2021 Oracle and/or its affiliates and others.
3: * All rights reserved.
4: * Copyright 2004 The Apache Software Foundation
5: *
6: * Licensed under the Apache License, Version 2.0 (the "License");
7: * you may not use this file except in compliance with the License.
8: * You may obtain a copy of the License at
9: *
10: * http://www.apache.org/licenses/LICENSE-2.0
11: *
12: * Unless required by applicable law or agreed to in writing, software
13: * distributed under the License is distributed on an "AS IS" BASIS,
14: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15: * See the License for the specific language governing permissions and
16: * limitations under the License.
17: */
18:
19: package jakarta.el;
20:
21: /**
22: * An <code>Expression</code> that refers to a method on an object.
23: *
24: * <p>
25: * The {@link ExpressionFactory#createMethodExpression} method can be used to parse an expression string and
26: * return a concrete instance of <code>MethodExpression</code> that encapsulates the parsed expression. The
27: * {@link FunctionMapper} is used at parse time, not evaluation time, so one is not needed to evaluate an expression
28: * using this class. However, the {@link ELContext} is needed at evaluation time.
29: * </p>
30: *
31: * <p>
32: * The {@link #getMethodInfo} and {@link #invoke} methods will evaluate the expression each time they are called. The
33: * {@link ELResolver} in the <code>ELContext</code> is used to resolve the top-level variables and to determine the
34: * behavior of the <code>.</code> and <code>[]</code> operators. For any of the two methods, the
35: * {@link ELResolver#getValue} method is used to resolve all properties up to but excluding the last one. This
36: * provides the <code>base</code> object on which the method appears. If the <code>base</code> object is null, a
37: * <code>PropertyNotFoundException</code> must be thrown. At the last resolution, the final <code>property</code> is
38: * then coerced to a <code>String</code>, which provides the name of the method to be found. A method matching the name
39: * and expected parameters provided at parse time is found and it is either queried or invoked (depending on the method
40: * called on this <code>MethodExpression</code>).
41: * </p>
42: *
43: * <p>
44: * See the notes about comparison, serialization and immutability in the {@link Expression} javadocs.
45: *
46: * @see ELResolver
47: * @see Expression
48: * @see ExpressionFactory
49: * @since Jakarta Server Pages 2.1
50: */
51: public abstract class MethodExpression extends Expression {
52:
53: private static final long serialVersionUID = -1151639017737837708L;
54:
55: // Evaluation
56:
57: /**
58: * Evaluates the expression relative to the provided context, and returns information about the actual referenced
59: * method.
60: *
61: * @param context The context of this evaluation
62: * @return an instance of <code>MethodInfo</code> containing information about the method the expression evaluated to.
63: * @throws NullPointerException if context is <code>null</code>
64: * @throws PropertyNotFoundException if one of the property resolutions failed because a specified variable or property
65: * does not exist or is not readable.
66: * @throws MethodNotFoundException if no suitable method can be found.
67: * @throws ELException if an exception was thrown while performing property or variable resolution. The thrown exception
68: * must be included as the cause property of this exception, if available.
69: */
70: public abstract MethodInfo getMethodInfo(ELContext context);
71:
72: /**
73: * If a String literal is specified as the expression, returns the String literal coerced to the expected return type of
74: * the method signature. An <code>ELException</code> is thrown if <code>expectedReturnType</code> is void or if the
75: * coercion of the String literal to the <code>expectedReturnType</code> yields an error (see Section "1.18 Type
76: * Conversion" of the Jakarta Expression Language specification).
77: *
78: * If not a String literal, evaluates the expression relative to the provided context, invokes the method that was found
79: * using the supplied parameters, and returns the result of the method invocation.
80: *
81: * Any parameters passed to this method is ignored if isLiteralText() or isParametersProvided() is true.
82: *
83: * @param context The context of this evaluation.
84: * @param params The parameters to pass to the method, or <code>null</code> if no parameters.
85: * @return the result of the method invocation (<code>null</code> if the method has a <code>void</code> return type).
86: * @throws NullPointerException if context is <code>null</code>
87: * @throws PropertyNotFoundException if one of the property resolutions failed because a specified variable or property
88: * does not exist or is not readable.
89: * @throws MethodNotFoundException if no suitable method can be found.
90: * @throws ELException if a String literal is specified and expectedReturnType of the MethodExpression is void or if the
91: * coercion of the String literal to the expectedReturnType yields an error (see Section "1.18 Type Conversion").
92: * @throws ELException if an exception was thrown while performing property or variable resolution. The thrown exception
93: * must be included as the cause property of this exception, if available. If the exception thrown is an
94: * <code>InvocationTargetException</code>, extract its <code>cause</code> and pass it to the <code>ELException</code>
95: * constructor.
96: */
97: public abstract Object invoke(ELContext context, Object[] params);
98:
99: /**
100: * Return whether this MethodExpression was created with parameters.
101: *
102: * <p>
103: * This method must return <code>true</code> if and only if parameters are specified in the EL, using the
104: * expr-a.expr-b(...) syntax.
105: *
106: * @return <code>true</code> if the MethodExpression was created with parameters, <code>false</code> otherwise.
107: *
108: * @since Jakarta Expression Language 2.2
109: */
110: public boolean isParametersProvided() {
111: return false;
112: }
113: }