Package: ELResolver

ELResolver

name	instruction	branch	complexity	line	method
ELResolver()	M: 3 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%
convertToType(ELContext, Object, Class)	M: 2 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%
invoke(ELContext, Object, Object, Class[], Object[])	M: 2 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%

Coverage

1: /*
2: * Copyright (c) 1997, 2022 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: * Enables customization of variable, property, method call, and type conversion resolution behavior for Jakarta
23: * Expression Language expression evaluation.
24: *
25: * <p>
26: * While evaluating an expression, the <code>ELResolver</code> associated with the {@link ELContext} is consulted to do
27: * the initial resolution of the first variable of an expression. It is also consulted when a <code>.</code> or
28: * <code>[]</code> operator is encountered.
29: *
30: * <p>
31: * For example, in the Jakarta Expression Language expression <code>${employee.lastName}</code>, the
32: * <code>ELResolver</code> determines what object <code>employee</code> refers to, and what it means to get the
33: * <code>lastName</code> property on that object.
34: *
35: * <p>
36: * Most methods in this class accept a <code>base</code> and <code>property</code> parameter. In the case of variable
37: * resolution (e.g. determining what <code>employee</code> refers to in <code>${employee.lastName}</code>), the
38: * <code>base</code> parameter will be <code>null</code> and the <code>property</code> parameter will always be of type
39: * <code>String</code>. In this case, if the <code>property</code> is not a <code>String</code>, the behavior of the
40: * <code>ELResolver</code> is undefined.
41: *
42: * <p>
43: * In the case of property resolution, the <code>base</code> parameter identifies the base object and the
44: * <code>property</code> object identifies the property on that base. For example, in the expression
45: * <code>${employee.lastName}</code>, <code>base</code> is the result of the variable resolution for
46: * <code>employee</code> and <code>property</code> is the string <code>"lastName"</code>. In the expression
47: * <code>${y[x]}</code>, <code>base</code> is the result of the variable resolution for <code>y</code> and
48: * <code>property</code> is the result of the variable resolution for <code>x</code>.
49: *
50: * <p>
51: * In the case of method call resolution, the <code>base</code> parameter identifies the base object and the
52: * <code>method</code> parameter identifies a method on that base. In the case of overloaded methods, the <code>
53: * paramTypes</code> parameter can be optionally used to identify a method. The <code>params</code>parameter are the
54: * parameters for the method call, and can also be used for resolving overloaded methods when the
55: * <code>paramTypes</code> parameter is not specified.
56: *
57: * <p>
58: * In the case of type conversion resolution, the <code>obj</code> parameter identifies the source object and the
59: * <code>targetType</code> parameter identifies the target type the source to covert to.
60: *
61: * <p>
62: * Though only a single <code>ELResolver</code> is associated with an <code>ELContext</code>, there are usually multiple
63: * resolvers considered for any given variable or property resolution. <code>ELResolver</code>s are combined together
64: * using {@link CompositeELResolver}s, to define rich semantics for evaluating an expression.
65: * </p>
66: *
67: * <p>
68: * For the {@link #getValue}, {@link #getType}, {@link #setValue}, and {@link #isReadOnly} methods, an
69: * <code>ELResolver</code> is not responsible for resolving all possible (base, property) pairs. In fact, most resolvers
70: * will only handle a <code>base</code> of a single type. To indicate that a resolver has successfully resolved a
71: * particular (base, property) pair, it must set the <code>propertyResolved</code> property of the
72: * <code>ELContext</code> to <code>true</code>. If it could not handle the given pair, it must leave this property
73: * alone. The caller must ignore the return value of the method if <code>propertyResolved</code> is <code>false</code>.
74: *
75: * <p>
76: * Similarly, for the {@link #convertToType} method an <code>ELResolver</code> must set the
77: * <code>propertyResolved</code> to <code>true</code> to indicate that it handles the conversion of the object to the
78: * target type.
79: *
80: * <p>
81: * The {@link #getCommonPropertyType} method is primarily designed for design-time
82: * tool support, but must handle invocation at runtime as well. The {@link java.beans.Beans#isDesignTime} method can be
83: * used to determine if the resolver is being consulted at design-time or runtime.
84: *
85: * @see CompositeELResolver
86: * @see ELContext#getELResolver
87: * @since Jakarta Server Pages 2.1
88: */
89: public abstract class ELResolver {
90:
91: /**
92: * Attempts to resolve the given <code>property</code> object on the given <code>base</code> object.
93: *
94: * <p>
95: * If this resolver handles the given (base, property) pair, the <code>propertyResolved</code> property of the
96: * <code>ELContext</code> object must be set to <code>true</code> by the resolver, before returning. If this property is
97: * not <code>true</code> after this method is called, the caller should ignore the return value.
98: * </p>
99: *
100: * @param context The context of this evaluation.
101: * @param base The base object whose property value is to be returned, or <code>null</code> to resolve a top-level
102: * variable.
103: * @param property The property or variable to be resolved.
104: *
105: * @return If the <code>propertyResolved</code> property of <code>ELContext</code> was set to <code>true</code>, then
106: * the result of the variable or property resolution; otherwise undefined.
107: *
108: * @throws NullPointerException if context is <code>null</code>
109: * @throws PropertyNotFoundException if the given (base, property) pair is handled by this <code>ELResolver</code> but
110: * the specified variable or property does not exist or is not readable.
111: * @throws ELException if an exception was thrown while performing the property or variable resolution. The thrown
112: * exception must be included as the cause property of this exception, if available.
113: */
114: public abstract Object getValue(ELContext context, Object base, Object property);
115:
116: /**
117: * Attempts to resolve and invoke the given <code>method</code> on the given <code>base</code> object.
118: *
119: * <p>
120: * If this resolver handles the given (base, method) pair, the <code>propertyResolved</code> property of the
121: * <code>ELContext</code> object must be set to <code>true</code> by the resolver, before returning. If this property is
122: * not <code>true</code> after this method is called, the caller should ignore the return value.
123: *
124: * <p>
125: * A default implementation is provided that returns null so that existing classes that extend ELResolver can continue
126: * to function.
127: *
128: * @param context The context of this evaluation.
129: * @param base The bean on which to invoke the method
130: * @param method The simple name of the method to invoke. Will be coerced to a <code>String</code>.
131: * @param paramTypes An array of Class objects identifying the method's formal parameter types, in declared order. Use
132: * an empty array if the method has no parameters. Can be <code>null</code>, in which case the method's formal parameter
133: * types are assumed to be unknown.
134: * @param params The parameters to pass to the method, or <code>null</code> if no parameters.
135: *
136: * @return The result of the method invocation (<code>null</code> if the method has a <code>void</code> return type).
137: *
138: * @throws MethodNotFoundException if no suitable method can be found.
139: * @throws ELException if an exception was thrown while performing (base, method) resolution. The thrown exception must
140: * be included as the cause property of this exception, if available. If the exception thrown is an
141: * <code>InvocationTargetException</code>, extract its <code>cause</code> and pass it to the <code>ELException</code>
142: * constructor.
143: *
144: * @since Jakarta Expression Language 2.2
145: */
146: public Object invoke(ELContext context, Object base, Object method, Class<?>[] paramTypes, Object[] params) {
147: return null;
148: }
149:
150: /**
151: * For a given <code>base</code> and <code>property</code>, attempts to identify the most general type that is
152: * acceptable for an object to be passed as the <code>value</code> parameter in a future call to the {@link #setValue}
153: * method.
154: *
155: * <p>
156: * If this resolver handles the given (base, property) pair, the <code>propertyResolved</code> property of the
157: * <code>ELContext</code> object must be set to <code>true</code> by the resolver, before returning. If this property is
158: * not <code>true</code> after this method is called, the caller should ignore the return value.
159: * </p>
160: *
161: * <p>
162: * This is not always the same as <code>getValue().getClass()</code>. For example, in the case of an
163: * {@link ArrayELResolver}, the <code>getType</code> method will return the element type of the array, which might be a
164: * superclass of the type of the actual element that is currently in the specified array element.
165: * </p>
166: *
167: * <p>
168: * If the resolver or the property is read-only, this method must return {@code null}.
169: * </p>
170: *
171: * @param context The context of this evaluation.
172: * @param base The base object whose property value is to be analyzed, or <code>null</code> to analyze a top-level
173: * variable.
174: * @param property The property or variable to return the acceptable type for.
175: * @return If the <code>propertyResolved</code> property of <code>ELContext</code> was set to <code>true</code>,
176: * the most general acceptable type which must be {@code null} if the either the property or the resolver is
177: * read-only; otherwise undefined
178: * @throws PropertyNotFoundException if the given (base, property) pair is handled by this <code>ELResolver</code> but
179: * the specified variable or property does not exist or is not readable.
180: * @throws ELException if an exception was thrown while performing the property or variable resolution. The thrown
181: * exception must be included as the cause property of this exception, if available.
182: */
183: public abstract Class<?> getType(ELContext context, Object base, Object property);
184:
185: /**
186: * Attempts to set the value of the given <code>property</code> object on the given <code>base</code> object.
187: *
188: * <p>
189: * If this resolver handles the given (base, property) pair, the <code>propertyResolved</code> property of the
190: * <code>ELContext</code> object must be set to <code>true</code> by the resolver, before returning. If this property is
191: * not <code>true</code> after this method is called, the caller can safely assume no value has been set.
192: * </p>
193: *
194: * @param context The context of this evaluation.
195: * @param base The base object whose property value is to be set, or <code>null</code> to set a top-level variable.
196: * @param property The property or variable to be set.
197: * @param value The value to set the property or variable to.
198: * @throws NullPointerException if context is <code>null</code>
199: * @throws PropertyNotFoundException if the given (base, property) pair is handled by this <code>ELResolver</code> but
200: * the specified variable or property does not exist.
201: * @throws PropertyNotWritableException if the given (base, property) pair is handled by this <code>ELResolver</code>
202: * but the specified variable or property is not writable.
203: * @throws ELException if an exception was thrown while attempting to set the property or variable. The thrown exception
204: * must be included as the cause property of this exception, if available.
205: */
206: public abstract void setValue(ELContext context, Object base, Object property, Object value);
207:
208: /**
209: * For a given <code>base</code> and <code>property</code>, attempts to determine whether a call to {@link #setValue}
210: * will always fail.
211: *
212: * <p>
213: * If this resolver handles the given (base, property) pair, the <code>propertyResolved</code> property of the
214: * <code>ELContext</code> object must be set to <code>true</code> by the resolver, before returning. If this property is
215: * not <code>true</code> after this method is called, the caller should ignore the return value.
216: * </p>
217: *
218: * @param context The context of this evaluation.
219: * @param base The base object whose property value is to be analyzed, or <code>null</code> to analyze a top-level
220: * variable.
221: * @param property The property or variable to return the read-only status for.
222: * @return If the <code>propertyResolved</code> property of <code>ELContext</code> was set to <code>true</code>, then
223: * <code>true</code> if the property is read-only or <code>false</code> if not; otherwise undefined.
224: * @throws NullPointerException if context is <code>null</code>
225: * @throws PropertyNotFoundException if the given (base, property) pair is handled by this <code>ELResolver</code> but
226: * the specified variable or property does not exist.
227: * @throws ELException if an exception was thrown while performing the property or variable resolution. The thrown
228: * exception must be included as the cause property of this exception, if available.
229: */
230: public abstract boolean isReadOnly(ELContext context, Object base, Object property);
231:
232: /**
233: * Returns the most general type that this resolver accepts for the <code>property</code> argument, given a
234: * <code>base</code> object. One use for this method is to assist tools in auto-completion.
235: *
236: * <p>
237: * This assists tools in auto-completion and also provides a way to express that the resolver accepts a primitive value,
238: * such as an integer index into an array. For example, the {@link ArrayELResolver} will accept any <code>int</code> as
239: * a <code>property</code>, so the return value would be <code>Integer.class</code>.
240: * </p>
241: *
242: * @param context The context of this evaluation.
243: * @param base The base object to return the most general property type for, or <code>null</code> to enumerate the set
244: * of top-level variables that this resolver can evaluate.
245: * @return <code>null</code> if this <code>ELResolver</code> does not know how to handle the given <code>base</code>
246: * object; otherwise <code>Object.class</code> if any type of <code>property</code> is accepted; otherwise the most
247: * general <code>property</code> type accepted for the given <code>base</code>.
248: */
249: public abstract Class<?> getCommonPropertyType(ELContext context, Object base);
250:
251: /**
252: * Converts an object to a specific type.
253: *
254: * <p>
255: * An <code>ELException</code> is thrown if an error occurs during the conversion.
256: * </p>
257: *
258: * @param context The context of this evaluation.
259: * @param obj The object to convert.
260: * @param targetType The target type for the conversion.
261: * @return object converted to <code>targetType</code>
262: * @throws ELException thrown if errors occur.
263: */
264: public <T> T convertToType(ELContext context, Object obj, Class<T> targetType) {
265: return null;
266: }
267: }