1 /*
2 * The contents of this file are subject to the terms
3 * of the Common Development and Distribution License
4 * (the "License"). You may not use this file except
5 * in compliance with the License.
6 *
7 * You can obtain a copy of the license at
8 * glassfish/bootstrap/legal/CDDLv1.0.txt or
9 * https://glassfish.dev.java.net/public/CDDLv1.0.html.
10 * See the License for the specific language governing
11 * permissions and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL
14 * HEADER in each file and include the License file at
15 * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
16 * add the following below this CDDL HEADER, with the
17 * fields enclosed by brackets "[]" replaced with your
18 * own identifying information: Portions Copyright [yyyy]
19 * [name of copyright owner]
20 *
21 * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
22 */
23
24 package javax.el;
25
26 import java.util.HashMap;
27 import java.util.Locale;
28
29 /**
30 * Context information for expression evaluation.
31 *
32 * <p>To evaluate an {@link Expression}, an <code>ELContext</code> must be
33 * provided. The <code>ELContext</code> holds:
34 * <ul>
35 * <li>a reference to the base {@link ELResolver} that will be consulted
36 * to resolve model objects and their properties</li>
37 * <li>a reference to {@link FunctionMapper} that will be used
38 * to resolve EL Functions.
39 * <li>a reference to {@link VariableMapper} that will be used
40 * to resolve EL Variables.
41 * <li>a collection of all the relevant context objects for use by
42 * <code>ELResolver</code>s</li>
43 * <li>state information during the evaluation of an expression, such as
44 * whether a property has been resolved yet</li>
45 * </ul></p>
46 *
47 * <p>The collection of context objects is necessary because each
48 * <code>ELResolver</code> may need access to a different context object.
49 * For example, JSP and Faces resolvers need access to a
50 * {@link javax.servlet.jsp.JspContext} and a
51 * {@link javax.faces.context.FacesContext}, respectively.</p>
52 *
53 * <p>Creation of <code>ELContext</code> objects is controlled through
54 * the underlying technology. For example, in JSP the
55 * <code>JspContext.getELContext()</code> factory method is used.
56 * Some technologies provide the ability to add an {@link ELContextListener}
57 * so that applications and frameworks can ensure their own context objects
58 * are attached to any newly created <code>ELContext</code>.</p>
59 *
60 * <p>Because it stores state during expression evaluation, an
61 * <code>ELContext</code> object is not thread-safe. Care should be taken
62 * to never share an <code>ELContext</code> instance between two or more
63 * threads.</p>
64 *
65 * @see ELContextListener
66 * @see ELContextEvent
67 * @see ELResolver
68 * @see FunctionMapper
69 * @see VariableMapper
70 * @see javax.servlet.jsp.JspContext
71 * @since JSP 2.1
72 */
73 public abstract class ELContext {
74
75 /**
76 * Called to indicate that a <code>ELResolver</code> has successfully
77 * resolved a given (base, property) pair.
78 *
79 * <p>The {@link CompositeELResolver} checks this property to determine
80 * whether it should consider or skip other component resolvers.</p>
81 *
82 * @see CompositeELResolver
83 * @param resolved true if the property has been resolved, or false if
84 * not.
85 */
86 public void setPropertyResolved(boolean resolved) {
87 this.resolved = resolved;
88 }
89
90 /**
91 * Returns whether an {@link ELResolver} has successfully resolved a
92 * given (base, property) pair.
93 *
94 * <p>The {@link CompositeELResolver} checks this property to determine
95 * whether it should consider or skip other component resolvers.</p>
96 *
97 * @see CompositeELResolver
98 * @return true if the property has been resolved, or false if not.
99 */
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 /**
213 * Retrieves the <code>VariableMapper</code> associated with this
214 * <code>ELContext</code>.
215 *
216 * @return The variable mapper to be consulted for the resolution of
217 * EL variables.
218 */
219 public abstract VariableMapper getVariableMapper();
220
221 private boolean resolved;
222 private HashMap map = new HashMap();
223
224
225 }
226
Save This Page