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: import java.io.Serializable;
027:
028: /**
029: * Base class for the expression subclasses {@link ValueExpression} and
030: * {@link MethodExpression}, implementing characterstics common to both.
031: *
032: * <p>All expressions must implement the <code>equals()</code> and
033: * <code>hashCode()</code> methods so that two expressions can be compared
034: * for equality. They are redefined abstract in this class to force their
035: * implementation in subclasses.</p>
036: *
037: * <p>All expressions must also be <code>Serializable</code> so that they
038: * can be saved and restored.</p>
039: *
040: * <p><code>Expression</code>s are also designed to be immutable so
041: * that only one instance needs to be created for any given expression
042: * String / {@link FunctionMapper}. This allows a container to pre-create
043: * expressions and not have to re-parse them each time they are evaluated.</p>
044: *
045: * @since JSP 2.1
046: */
047: public abstract class Expression implements Serializable {
048: // Debugging
049:
050: /**
051: * Returns the original String used to create this <code>Expression</code>,
052: * unmodified.
053: *
054: * <p>This is used for debugging purposes but also for the purposes
055: * of comparison (e.g. to ensure the expression in a configuration
056: * file has not changed).</p>
057: *
058: * <p>This method does not provide sufficient information to
059: * re-create an expression. Two different expressions can have exactly
060: * the same expression string but different function mappings.
061: * Serialization should be used to save and restore the state of an
062: * <code>Expression</code>.</p>
063: *
064: * @return The original expression String.
065: */
066: public abstract String getExpressionString();
067:
068: // Comparison
069:
070: /**
071: * Determines whether the specified object is equal to this
072: * <code>Expression</code>.
073: *
074: * <p>The result is <code>true</code> if and only if the argument is
075: * not <code>null</code>, is an <code>Expression</code> object that
076: * is the of the same type (<code>ValueExpression</code> or
077: * <code>MethodExpression</code>), and has an identical parsed
078: * representation.</p>
079: *
080: * <p>Note that two expressions can be equal if their expression
081: * Strings are different. For example, <code>${fn1:foo()}</code>
082: * and <code>${fn2:foo()}</code> are equal if their corresponding
083: * <code>FunctionMapper</code>s mapped <code>fn1:foo</code> and
084: * <code>fn2:foo</code> to the same method.</p>
085: *
086: * @param obj the <code>Object</code> to test for equality.
087: * @return <code>true</code> if <code>obj</code> equals this
088: * <code>Expression</code>; <code>false</code> otherwise.
089: * @see java.util.Hashtable
090: * @see java.lang.Object#equals(java.lang.Object)
091: */
092: public abstract boolean equals(Object obj);
093:
094: /**
095: * Returns the hash code for this <code>Expression</code>.
096: *
097: * <p>See the note in the {@link #equals} method on how two expressions
098: * can be equal if their expression Strings are different. Recall that
099: * if two objects are equal according to the <code>equals(Object)</code>
100: * method, then calling the <code>hashCode</code> method on each of the
101: * two objects must produce the same integer result. Implementations must
102: * take special note and implement <code>hashCode</code> correctly.</p>
103: *
104: * @return The hash code for this <code>Expression</code>.
105: * @see #equals
106: * @see java.util.Hashtable
107: * @see java.lang.Object#hashCode()
108: */
109: public abstract int hashCode();
110:
111: /**
112: * Returns whether this expression was created from only literal text.
113: *
114: * <p>This method must return <code>true</code> if and only if the
115: * expression string this expression was created from contained no
116: * unescaped EL delimeters (<code>${...}</code> or
117: * <code>#{...}</code>).</p>
118: *
119: * @return <code>true</code> if this expression was created from only
120: * literal text; <code>false</code> otherwise.
121: */
122: public abstract boolean isLiteralText();
123: }
|