001: /*
002: * The contents of this file are subject to the terms
003: * of the Common Development and Distribution License
004: * (the "License"). You may not use this file except
005: * in compliance with the License.
006: *
007: * You can obtain a copy of the license at
008: * glassfish/bootstrap/legal/CDDLv1.0.txt or
009: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
010: * See the License for the specific language governing
011: * permissions and limitations under the License.
012: *
013: * When distributing Covered Code, include this CDDL
014: * HEADER in each file and include the License file at
015: * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
016: * add the following below this CDDL HEADER, with the
017: * fields enclosed by brackets "[]" replaced with your
018: * own identifying information: Portions Copyright [yyyy]
019: * [name of copyright owner]
020: *
021: * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
022: */
023:
024: package javax.el;
025:
026: /**
027: * An <code>Expression</code> that can get or set a value.
028: *
029: * <p>In previous incarnations of this API, expressions could only be
030: * read. <code>ValueExpression</code> objects can now be used both to
031: * retrieve a value and to set a value. Expressions that can have a value
032: * set on them are referred to as l-value expressions. Those that
033: * cannot are referred to as r-value expressions. Not all r-value expressions
034: * can be used as l-value expressions (e.g. <code>"${1+1}"</code> or
035: * <code>"${firstName} ${lastName}"</code>). See the EL Specification for
036: * details. Expressions that cannot be used as l-values must always
037: * return <code>true</code> from <code>isReadOnly()</code>.</p>
038: *
039: * <p>The <code>{@link ExpressionFactory#createValueExpression}</code> method
040: * can be used to parse an expression string and return a concrete instance
041: * of <code>ValueExpression</code> that encapsulates the parsed expression.
042: * The {@link FunctionMapper} is used at parse time, not evaluation time,
043: * so one is not needed to evaluate an expression using this class.
044: * However, the {@link ELContext} is needed at evaluation time.</p>
045: *
046: * <p>The {@link #getValue}, {@link #setValue}, {@link #isReadOnly} and
047: * {@link #getType} methods will evaluate the expression each time they are
048: * called. The {@link ELResolver} in the <code>ELContext</code> is used to
049: * resolve the top-level variables and to determine the behavior of the
050: * <code>.</code> and <code>[]</code> operators. For any of the four methods,
051: * the {@link ELResolver#getValue} method is used to resolve all properties
052: * up to but excluding the last one. This provides the <code>base</code>
053: * object. At the last resolution, the <code>ValueExpression</code> will
054: * call the corresponding {@link ELResolver#getValue},
055: * {@link ELResolver#setValue}, {@link ELResolver#isReadOnly} or
056: * {@link ELResolver#getType} method, depending on which was called on
057: * the <code>ValueExpression</code>.
058: * </p>
059: *
060: * <p>See the notes about comparison, serialization and immutability in
061: * the {@link Expression} javadocs.
062: *
063: * @see ELResolver
064: * @see Expression
065: * @see ExpressionFactory
066: * @since JSP 2.1
067: */
068: public abstract class ValueExpression extends Expression {
069:
070: /**
071: * Evaluates the expression relative to the provided context, and
072: * returns the resulting value.
073: *
074: * <p>The resulting value is automatically coerced to the type
075: * returned by <code>getExpectedType()</code>, which was
076: * provided to the <code>ExpressionFactory</code> when this
077: * expression was created.</p>
078: *
079: * @param context The context of this evaluation.
080: * @return The result of the expression evaluation.
081: * @throws NullPointerException if context is <code>null</code>.
082: * @throws PropertyNotFoundException if one of the property
083: * resolutions failed because a specified variable or property
084: * does not exist or is not readable.
085: * @throws ELException if an exception was thrown while performing
086: * property or variable resolution. The thrown exception
087: * must be included as the cause property of this exception, if
088: * available.
089: */
090: public abstract Object getValue(ELContext context);
091:
092: /**
093: * Evaluates the expression relative to the provided context, and
094: * sets the result to the provided value.
095: *
096: * @param context The context of this evaluation.
097: * @param value The new value to be set.
098: * @throws NullPointerException if context is <code>null</code>.
099: * @throws PropertyNotFoundException if one of the property
100: * resolutions failed because a specified variable or property
101: * does not exist or is not readable.
102: * @throws PropertyNotWritableException if the final variable or
103: * property resolution failed because the specified
104: * variable or property is not writable.
105: * @throws ELException if an exception was thrown while attempting to
106: * set the property or variable. The thrown exception
107: * must be included as the cause property of this exception, if
108: * available.
109: */
110: public abstract void setValue(ELContext context, Object value);
111:
112: /**
113: * Evaluates the expression relative to the provided context, and
114: * returns <code>true</code> if a call to {@link #setValue} will
115: * always fail.
116: *
117: * @param context The context of this evaluation.
118: * @return <code>true</code> if the expression is read-only or
119: * <code>false</code> if not.
120: * @throws NullPointerException if context is <code>null</code>.
121: * @throws PropertyNotFoundException if one of the property
122: * resolutions failed because a specified variable or property
123: * does not exist or is not readable.
124: * @throws ELException if an exception was thrown while performing
125: * property or variable resolution. The thrown exception
126: * must be included as the cause property of this exception, if
127: * available.
128: * * @throws NullPointerException if context is <code>null</code>
129: */
130: public abstract boolean isReadOnly(ELContext context);
131:
132: /**
133: * Evaluates the expression relative to the provided context, and
134: * returns the most general type that is acceptable for an object to be
135: * passed as the <code>value</code> parameter in a future call
136: * to the {@link #setValue} method.
137: *
138: * <p>This is not always the same as <code>getValue().getClass()</code>.
139: * For example, in the case of an expression that references an
140: * array element, the <code>getType</code> method will return the
141: * element type of the array, which might be a superclass of the type
142: * of the actual element that is currently in the specified
143: * array element.</p>
144: *
145: * @param context The context of this evaluation.
146: * @return the most general acceptable type; otherwise undefined.
147: * @throws NullPointerException if context is <code>null</code>.
148: * @throws PropertyNotFoundException if one of the property
149: * resolutions failed because a specified variable or property
150: * does not exist or is not readable.
151: * @throws ELException if an exception was thrown while performing
152: * property or variable resolution. The thrown exception
153: * must be included as the cause property of this exception, if
154: * available.
155: */
156: public abstract Class<?> getType(ELContext context);
157:
158: /**
159: * Returns the type the result of the expression will be coerced to
160: * after evaluation.
161: *
162: * @return the <code>expectedType</code> passed to the
163: * <code>ExpressionFactory.createValueExpression</code> method
164: * that created this <code>ValueExpression</code>.
165: */
166: public abstract Class<?> getExpectedType();
167: }
|