Package: ValueExpression

ValueExpression

name	instruction	branch	complexity	line	method
ValueExpression()	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%
getValueReference(ELContext)	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, 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 can get or set a value.
23: *
24: * <p>
25: * In previous incarnations of this API, expressions could only be read. <code>ValueExpression</code> objects can now be
26: * used both to retrieve a value and to set a value. Expressions that can have a value set on them are referred to as
27: * l-value expressions. Those that cannot are referred to as r-value expressions. Not all r-value expressions can be
28: * used as l-value expressions (e.g. <code>"${1+1}"</code> or <code>"${firstName} ${lastName}"</code>). See the EL
29: * Specification for details. Expressions that cannot be used as l-values must always return <code>true</code> from
30: * <code>isReadOnly()</code>.
31: * </p>
32: *
33: * <p>
34: * The <code>{@link ExpressionFactory#createValueExpression}</code> method can be used to parse an expression string and
35: * return a concrete instance of <code>ValueExpression</code> that encapsulates the parsed expression. The
36: * {@link FunctionMapper} is used at parse time, not evaluation time, so one is not needed to evaluate an expression
37: * using this class. However, the {@link ELContext} is needed at evaluation time.
38: * </p>
39: *
40: * <p>
41: * The {@link #getValue}, {@link #setValue}, {@link #isReadOnly}, {@link #getType} and {@link #getValueReference}
42: * methods will evaluate the expression each time they are called. The {@link ELResolver} in the <code>ELContext</code>
43: * is used to resolve the top-level variables and to determine the behavior of the <code>.</code> and <code>[]</code>
44: * operators. For any of the five methods, the {@link ELResolver#getValue} method is used to resolve all properties up
45: * to but excluding the last one. This provides the <code>base</code> object. For all methods other than the
46: * {@link #getValueReference} method, at the last resolution, the <code>ValueExpression</code> will call the
47: * corresponding {@link ELResolver#getValue}, {@link ELResolver#setValue}, {@link ELResolver#isReadOnly} or
48: * {@link ELResolver#getType} method, depending on which was called on the <code>ValueExpression</code>. For the
49: * {@link #getValueReference} method, the (base, property) is not resolved by the ELResolver, but an instance of
50: * {@link ValueReference} is created to encapsulate this (base ,property), and returned.
51: * </p>
52: *
53: * <p>
54: * See the notes about comparison, serialization and immutability in the {@link Expression} javadocs.
55: *
56: * @see ELResolver
57: * @see Expression
58: * @see ExpressionFactory
59: *
60: * @since Jakarta Server Pages 2.1
61: */
62: public abstract class ValueExpression extends Expression {
63:
64: private static final long serialVersionUID = -8466802188968516519L;
65:
66: /**
67: * Evaluates the expression relative to the provided context, and returns the resulting value.
68: *
69: * <p>
70: * The resulting value is automatically coerced to the type returned by <code>getExpectedType()</code>, which was
71: * provided to the <code>ExpressionFactory</code> when this expression was created.
72: *
73: * @param context The context of this evaluation.
74: *
75: * @return The result of the expression evaluation.
76: *
77: * @throws NullPointerException if context is <code>null</code>.
78: * @throws PropertyNotFoundException if one of the property resolutions failed because a specified variable or property
79: * does not exist or is not readable.
80: * @throws ELException if an exception was thrown while performing property or variable resolution. The thrown exception
81: * must be included as the cause property of this exception, if available.
82: */
83: public abstract <T> T getValue(ELContext context);
84:
85: /**
86: * Evaluates the expression relative to the provided context, and sets the result to the provided value.
87: *
88: * @param context The context of this evaluation.
89: * @param value The new value to be set.
90: *
91: * @throws NullPointerException if context is <code>null</code>.
92: * @throws PropertyNotFoundException if one of the property resolutions failed because a specified variable or property
93: * does not exist or is not readable.
94: * @throws PropertyNotWritableException if the final variable or property resolution failed because the specified
95: * variable or property is not writable.
96: * @throws ELException if an exception was thrown while attempting to set the property or variable. The thrown exception
97: * must be included as the cause property of this exception, if available.
98: */
99: public abstract void setValue(ELContext context, Object value);
100:
101: /**
102: * Evaluates the expression relative to the provided context, and returns <code>true</code> if a call to
103: * {@link #setValue} will always fail.
104: *
105: * @param context The context of this evaluation.
106: *
107: * @return <code>true</code> if the expression is read-only or <code>false</code> if not.
108: *
109: * @throws NullPointerException if context is <code>null</code>.
110: * @throws PropertyNotFoundException if one of the property resolutions failed because a specified variable or property
111: * does not exist or is not readable.
112: * @throws ELException if an exception was thrown while performing property or variable resolution. The thrown exception
113: * must be included as the cause property of this exception, if available. * @throws NullPointerException if context is
114: * <code>null</code>
115: */
116: public abstract boolean isReadOnly(ELContext context);
117:
118: /**
119: * Evaluates the expression relative to the provided context, and returns the most general type that is acceptable for
120: * an object to be passed as the <code>value</code> parameter in a future call to the {@link #setValue} method.
121: *
122: * <p>
123: * This is not always the same as <code>getValue().getClass()</code>. For example, in the case of an expression that
124: * references an array element, the <code>getType</code> method will return the element type of the array, which might
125: * be a superclass of the type of the actual element that is currently in the specified array element.
126: *
127: * @param context The context of this evaluation.
128: *
129: * @return the most general acceptable type; otherwise undefined.
130: *
131: * @throws NullPointerException if context is <code>null</code>.
132: * @throws PropertyNotFoundException if one of the property resolutions failed because a specified variable or property
133: * does not exist or is not readable.
134: * @throws ELException if an exception was thrown while performing property or variable resolution. The thrown exception
135: * must be included as the cause property of this exception, if available.
136: */
137: public abstract Class<?> getType(ELContext context);
138:
139: /**
140: * Returns the type the result of the expression will be coerced to after evaluation.
141: *
142: * @return the <code>expectedType</code> passed to the <code>ExpressionFactory.createValueExpression</code> method that
143: * created this <code>ValueExpression</code>.
144: */
145: public abstract Class<?> getExpectedType();
146:
147: /**
148: * Returns a {@link ValueReference} for this expression instance.
149: *
150: * @param context the context of this evaluation
151: *
152: * @return the <code>ValueReference</code> for this <code>ValueExpression</code>, or <code>null</code> if this
153: * <code>ValueExpression</code> is not a reference to a base (null or non-null) and a property. If the base is null, and
154: * the property is a Jakarta Expression Language variable, return the <code>ValueReference</code> for the
155: * <code>ValueExpression</code> associated with this Jakarta Expression Language variable.
156: *
157: * @since Jakarta Expression Language 2.2
158: */
159: public ValueReference getValueReference(ELContext context) {
160: return null;
161: }
162: }