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.util.HashMap;
027: import java.util.Locale;
028:
029: /**
030: * Context information for expression evaluation.
031: *
032: * <p>To evaluate an {@link Expression}, an <code>ELContext</code> must be
033: * provided. The <code>ELContext</code> holds:
034: * <ul>
035: * <li>a reference to the base {@link ELResolver} that will be consulted
036: * to resolve model objects and their properties</li>
037: * <li>a reference to {@link FunctionMapper} that will be used
038: * to resolve EL Functions.
039: * <li>a reference to {@link VariableMapper} that will be used
040: * to resolve EL Variables.
041: * <li>a collection of all the relevant context objects for use by
042: * <code>ELResolver</code>s</li>
043: * <li>state information during the evaluation of an expression, such as
044: * whether a property has been resolved yet</li>
045: * </ul></p>
046: *
047: * <p>The collection of context objects is necessary because each
048: * <code>ELResolver</code> may need access to a different context object.
049: * For example, JSP and Faces resolvers need access to a
050: * {@link javax.servlet.jsp.JspContext} and a
051: * {@link javax.faces.context.FacesContext}, respectively.</p>
052: *
053: * <p>Creation of <code>ELContext</code> objects is controlled through
054: * the underlying technology. For example, in JSP the
055: * <code>JspContext.getELContext()</code> factory method is used.
056: * Some technologies provide the ability to add an {@link ELContextListener}
057: * so that applications and frameworks can ensure their own context objects
058: * are attached to any newly created <code>ELContext</code>.</p>
059: *
060: * <p>Because it stores state during expression evaluation, an
061: * <code>ELContext</code> object is not thread-safe. Care should be taken
062: * to never share an <code>ELContext</code> instance between two or more
063: * threads.</p>
064: *
065: * @see ELContextListener
066: * @see ELContextEvent
067: * @see ELResolver
068: * @see FunctionMapper
069: * @see VariableMapper
070: * @see javax.servlet.jsp.JspContext
071: * @since JSP 2.1
072: */
073: public abstract class ELContext {
074:
075: /**
076: * Called to indicate that a <code>ELResolver</code> has successfully
077: * resolved a given (base, property) pair.
078: *
079: * <p>The {@link CompositeELResolver} checks this property to determine
080: * whether it should consider or skip other component resolvers.</p>
081: *
082: * @see CompositeELResolver
083: * @param resolved true if the property has been resolved, or false if
084: * not.
085: */
086: public void setPropertyResolved(boolean resolved) {
087: this .resolved = resolved;
088: }
089:
090: /**
091: * Returns whether an {@link ELResolver} has successfully resolved a
092: * given (base, property) pair.
093: *
094: * <p>The {@link CompositeELResolver} checks this property to determine
095: * whether it should consider or skip other component resolvers.</p>
096: *
097: * @see CompositeELResolver
098: * @return true if the property has been resolved, or false if not.
099: */
100: public boolean isPropertyResolved() {
101: return resolved;
102: }
103:
104: /**
105: * Associates a context object with this <code>ELContext</code>.
106: *
107: * <p>The <code>ELContext</code> maintains a collection of context objects
108: * relevant to the evaluation of an expression. These context objects
109: * are used by <code>ELResolver</code>s. This method is used to
110: * add a context object to that collection.</p>
111: *
112: * <p>By convention, the <code>contextObject</code> will be of the
113: * type specified by the <code>key</code>. However, this is not
114: * required and the key is used strictly as a unique identifier.</p>
115: *
116: * @param key The key used by an @{link ELResolver} to identify this
117: * context object.
118: * @param contextObject The context object to add to the collection.
119: * @throws NullPointerException if key is null or contextObject is null.
120: */
121: public void putContext(Class key, Object contextObject) {
122: if ((key == null) || (contextObject == null)) {
123: throw new NullPointerException();
124: }
125: map.put(key, contextObject);
126: }
127:
128: /**
129: * Returns the context object associated with the given key.
130: *
131: * <p>The <code>ELContext</code> maintains a collection of context objects
132: * relevant to the evaluation of an expression. These context objects
133: * are used by <code>ELResolver</code>s. This method is used to
134: * retrieve the context with the given key from the collection.</p>
135: *
136: * <p>By convention, the object returned will be of the type specified by
137: * the <code>key</code>. However, this is not required and the key is
138: * used strictly as a unique identifier.</p>
139: *
140: * @param key The unique identifier that was used to associate the
141: * context object with this <code>ELContext</code>.
142: * @return The context object associated with the given key, or null
143: * if no such context was found.
144: * @throws NullPointerException if key is null.
145: */
146: public Object getContext(Class key) {
147: if (key == null) {
148: throw new NullPointerException();
149: }
150: return map.get(key);
151: }
152:
153: /**
154: * Retrieves the <code>ELResolver</code> associated with this context.
155: *
156: * <p>The <code>ELContext</code> maintains a reference to the
157: * <code>ELResolver</code> that will be consulted to resolve variables
158: * and properties during an expression evaluation. This method
159: * retrieves the reference to the resolver.</p>
160: *
161: * <p>Once an <code>ELContext</code> is constructed, the reference to the
162: * <code>ELResolver</code> associated with the context cannot be changed.</p>
163: *
164: * @return The resolver to be consulted for variable and
165: * property resolution during expression evaluation.
166: */
167: public abstract ELResolver getELResolver();
168:
169: /**
170: * Retrieves the <code>FunctionMapper</code> associated with this
171: * <code>ELContext</code>.
172: *
173: * @return The function mapper to be consulted for the resolution of
174: * EL functions.
175: */
176: public abstract FunctionMapper getFunctionMapper();
177:
178: /**
179: * Holds value of property locale.
180: */
181: private Locale locale;
182:
183: /**
184: * Get the <code>Locale</code> stored by a previous invocation to
185: * {@link #setLocale}. If this method returns non <code>null</code>,
186: * this <code>Locale</code> must be used for all localization needs
187: * in the implementation. The <code>Locale</code> must not be cached
188: * to allow for applications that change <code>Locale</code> dynamically.
189: *
190: * @return The <code>Locale</code> in which this instance is operating.
191: * Used primarily for message localization.
192: */
193:
194: public Locale getLocale() {
195:
196: return this .locale;
197: }
198:
199: /**
200: * Set the <code>Locale</code> for this instance. This method may be
201: * called by the party creating the instance, such as JavaServer
202: * Faces or JSP, to enable the EL implementation to provide localized
203: * messages to the user. If no <code>Locale</code> is set, the implementation
204: * must use the locale returned by <code>Locale.getDefault( )</code>.
205: */
206: public void setLocale(Locale locale) {
207:
208: this .locale = locale;
209: }
210:
211: /**
212: * Retrieves the <code>VariableMapper</code> associated with this
213: * <code>ELContext</code>.
214: *
215: * @return The variable mapper to be consulted for the resolution of
216: * EL variables.
217: */
218: public abstract VariableMapper getVariableMapper();
219:
220: private boolean resolved;
221: private HashMap map = new HashMap();
222:
223: }
|