001    /**
002     *
003     * Copyright 2003-2004 The Apache Software Foundation
004     *
005     *  Licensed under the Apache License, Version 2.0 (the "License");
006     *  you may not use this file except in compliance with the License.
007     *  You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     *  Unless required by applicable law or agreed to in writing, software
012     *  distributed under the License is distributed on an "AS IS" BASIS,
013     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     *  See the License for the specific language governing permissions and
015     *  limitations under the License.
016     */
017    
018    //
019    // This source code implements specifications defined by the Java
020    // Community Process. In order to remain compliant with the specification
021    // DO NOT add / change / or delete method signatures!
022    //
023    
024    package javax.servlet.jsp;
025    
026    import java.util.Enumeration;
027    
028    import javax.servlet.jsp.el.ExpressionEvaluator;
029    import javax.servlet.jsp.el.VariableResolver;
030    
031    /**
032     * <p>
033     * <code>JspContext</code> serves as the base class for the 
034     * PageContext class and abstracts all information that is not specific
035     * to servlets.  This allows for Simple Tag Extensions to be used
036     * outside of the context of a request/response Servlet.
037     * <p>
038     * The JspContext provides a number of facilities to the 
039     * page/component author and page implementor, including:
040     * <ul>
041     * <li>a single API to manage the various scoped namespaces
042     * <li>a mechanism to obtain the JspWriter for output
043     * <li>a mechanism to expose page directive attributes to the 
044     *     scripting environment
045     * </ul>
046     *
047     * <p><B>Methods Intended for Container Generated Code</B>
048     * <p>
049     * The following methods enable the <B>management of nested</B> JspWriter 
050     * streams to implement Tag Extensions: <code>pushBody()</code> and
051     * <code>popBody()</code>
052     *
053     * <p><B>Methods Intended for JSP authors</B>
054     * <p>
055     * Some methods provide <B>uniform access</B> to the diverse objects
056     * representing scopes.
057     * The implementation must use the underlying machinery
058     * corresponding to that scope, so information can be passed back and
059     * forth between the underlying environment (e.g. Servlets) and JSP pages.
060     * The methods are:
061     * <code>setAttribute()</code>,  <code>getAttribute()</code>,
062     * <code>findAttribute()</code>,  <code>removeAttribute()</code>,
063     * <code>getAttributesScope()</code> and 
064     * <code>getAttributeNamesInScope()</code>.
065     * 
066     * <p>
067     * The following methods provide <B>convenient access</B> to implicit objects:
068     * <code>getOut()</code>
069     *
070     * <p>
071     * The following methods provide <B>programmatic access</b> to the 
072     * Expression Language evaluator:
073     * <code>getExpressionEvaluator()</code>, <code>getVariableResolver()</code>
074     *
075     * @since 2.0
076     */
077    
078    public abstract class JspContext {
079    
080        /**
081         * Sole constructor. (For invocation by subclass constructors, 
082         * typically implicit.)
083         */
084        public JspContext() {
085        }
086        
087        /** 
088         * Register the name and value specified with page scope semantics.
089         * If the value passed in is <code>null</code>, this has the same 
090         * effect as calling 
091         * <code>removeAttribute( name, PageContext.PAGE_SCOPE )</code>.
092         *
093         * @param name the name of the attribute to set
094         * @param value the value to associate with the name, or null if the
095         *     attribute is to be removed from the page scope.
096         * @throws NullPointerException if the name is null
097         */
098    
099        abstract public void setAttribute(String name, Object value);
100    
101        /**
102         * Register the name and value specified with appropriate 
103         * scope semantics.  If the value passed in is <code>null</code>, 
104         * this has the same effect as calling
105         * <code>removeAttribute( name, scope )</code>.
106         * 
107         * @param name the name of the attribute to set
108         * @param value the object to associate with the name, or null if
109         *     the attribute is to be removed from the specified scope.
110         * @param scope the scope with which to associate the name/object
111         * 
112         * @throws NullPointerException if the name is null
113         * @throws IllegalArgumentException if the scope is invalid
114         * @throws IllegalStateException if the scope is 
115         *     PageContext.SESSION_SCOPE but the page that was requested
116         *     does not participate in a session or the session has been
117         *     invalidated.
118         */
119    
120        abstract public void setAttribute(String name, Object value, int scope);
121    
122        /**
123         * Returns the object associated with the name in the page scope or null
124         * if not found.
125         *
126         * @param name the name of the attribute to get
127         * @return the object associated with the name in the page scope 
128         *     or null if not found.
129         * 
130         * @throws NullPointerException if the name is null
131         */
132    
133        abstract public Object getAttribute(String name);
134    
135        /**
136         * Return the object associated with the name in the specified
137         * scope or null if not found.
138         *
139         * @param name the name of the attribute to set
140         * @param scope the scope with which to associate the name/object
141         * @return the object associated with the name in the specified
142         *     scope or null if not found.
143         * 
144         * @throws NullPointerException if the name is null
145         * @throws IllegalArgumentException if the scope is invalid 
146         * @throws IllegalStateException if the scope is 
147         *     PageContext.SESSION_SCOPE but the page that was requested
148         *     does not participate in a session or the session has been
149         *     invalidated.
150         */
151    
152        abstract public Object getAttribute(String name, int scope);
153    
154        /**
155         * Searches for the named attribute in page, request, session (if valid),
156         * and application scope(s) in order and returns the value associated or
157         * null.
158         *
159         * @param name the name of the attribute to search for
160         * @return the value associated or null
161         * @throws NullPointerException if the name is null
162         */
163    
164        abstract public Object findAttribute(String name);
165    
166        /**
167         * Remove the object reference associated with the given name
168         * from all scopes.  Does nothing if there is no such object.
169         *
170         * @param name The name of the object to remove.
171         * @throws NullPointerException if the name is null
172         */
173    
174        abstract public void removeAttribute(String name);
175    
176        /**
177         * Remove the object reference associated with the specified name
178         * in the given scope.  Does nothing if there is no such object.
179         *
180         * @param name The name of the object to remove.
181         * @param scope The scope where to look.
182         * @throws IllegalArgumentException if the scope is invalid
183         * @throws IllegalStateException if the scope is 
184         *     PageContext.SESSION_SCOPE but the page that was requested
185         *     does not participate in a session or the session has been
186         *     invalidated.
187         * @throws NullPointerException if the name is null
188         */
189    
190        abstract public void removeAttribute(String name, int scope);
191    
192        /**
193         * Get the scope where a given attribute is defined.
194         *
195         * @param name the name of the attribute to return the scope for
196         * @return the scope of the object associated with the name specified or 0
197         * @throws NullPointerException if the name is null
198         */
199    
200        abstract public int getAttributesScope(String name);
201    
202        /**
203         * Enumerate all the attributes in a given scope.
204         *
205         * @param scope the scope to enumerate all the attributes for
206         * @return an enumeration of names (java.lang.String) of all the 
207         *     attributes the specified scope
208         * @throws IllegalArgumentException if the scope is invalid
209         * @throws IllegalStateException if the scope is 
210         *     PageContext.SESSION_SCOPE but the page that was requested
211         *     does not participate in a session or the session has been
212         *     invalidated.
213         */
214    
215        abstract public Enumeration getAttributeNamesInScope(int scope);
216    
217        /**
218         * The current value of the out object (a JspWriter).
219         *
220         * @return the current JspWriter stream being used for client response
221         */
222        abstract public JspWriter getOut();
223        
224        /**
225         * Provides programmatic access to the ExpressionEvaluator.
226         * The JSP Container must return a valid instance of an 
227         * ExpressionEvaluator that can parse EL expressions.
228         *
229         * @return A valid instance of an ExpressionEvaluator.
230         * @since 2.0
231         */
232        public abstract ExpressionEvaluator getExpressionEvaluator();
233        
234        /**
235         * Returns an instance of a VariableResolver that provides access to the
236         * implicit objects specified in the JSP specification using this JspContext
237         * as the context object.
238         *
239         * @return A valid instance of a VariableResolver.
240         * @since 2.0
241         */
242        public abstract VariableResolver getVariableResolver();
243        
244        /**
245         * Return a new JspWriter object that sends output to the
246         * provided Writer.  Saves the current "out" JspWriter,
247         * and updates the value of the "out" attribute in the
248         * page scope attribute namespace of the JspContext.
249         * <p>The returned JspWriter must implement all methods and
250         * behave as though it were unbuffered.  More specifically:
251         * <ul>
252         *   <li>clear() must throw an IOException</li>
253         *   <li>clearBuffer() does nothing</li>
254         *   <li>getBufferSize() always returns 0</li>
255         *   <li>getRemaining() always returns 0</li>
256         * </ul>
257         * </p>
258         *
259         * @param writer The Writer for the returned JspWriter to send
260         *     output to.
261         * @return a new JspWriter that writes to the given Writer.
262         * @since 2.0
263         */
264        public JspWriter pushBody( java.io.Writer writer ) {
265            return null; // XXX to implement
266        }
267        
268        /**
269         * Return the previous JspWriter "out" saved by the matching
270         * pushBody(), and update the value of the "out" attribute in
271         * the page scope attribute namespace of the JspContext.
272         *
273         * @return the saved JspWriter.
274         */
275        public JspWriter popBody() {
276            return null; // XXX to implement
277        }
278    }