View Javadoc

1   /**
2    *
3    * Copyright 2003-2004 The Apache Software Foundation
4    *
5    *  Licensed under the Apache License, Version 2.0 (the "License");
6    *  you may not use this file except in compliance with the License.
7    *  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   *  Unless required by applicable law or agreed to in writing, software
12   *  distributed under the License is distributed on an "AS IS" BASIS,
13   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   *  See the License for the specific language governing permissions and
15   *  limitations under the License.
16   */
17  
18  //
19  // This source code implements specifications defined by the Java
20  // Community Process. In order to remain compliant with the specification
21  // DO NOT add / change / or delete method signatures!
22  //
23  
24  package javax.servlet.jsp;
25  
26  import java.io.IOException;
27  
28  import javax.servlet.Servlet;
29  import javax.servlet.ServletConfig;
30  import javax.servlet.ServletContext;
31  import javax.servlet.ServletException;
32  import javax.servlet.ServletRequest;
33  import javax.servlet.ServletResponse;
34  
35  import javax.servlet.http.HttpSession;
36  
37  import javax.servlet.jsp.tagext.BodyContent;
38  
39  /**
40   * <p>
41   * PageContext extends JspContext to provide useful context information for
42   * when JSP technology is used in a Servlet environment.
43   * <p>
44   * A PageContext instance provides access to all the namespaces associated
45   * with a JSP page, provides access to several page attributes, as well as
46   * a layer above the implementation details.  Implicit objects are added
47   * to the pageContext automatically.
48   *
49   * <p> The <code> PageContext </code> class is an abstract class, designed to be
50   * extended to provide implementation dependent implementations thereof, by
51   * conformant JSP engine runtime environments. A PageContext instance is 
52   * obtained by a JSP implementation class by calling the
53   * JspFactory.getPageContext() method, and is released by calling
54   * JspFactory.releasePageContext().
55   *
56   * <p> An example of how PageContext, JspFactory, and other classes can be
57   * used  within a JSP Page Implementation object is given elsewhere.
58   *
59   * <p>
60   * The PageContext provides a number of facilities to the page/component 
61   * author and page implementor, including:
62   * <ul>
63   * <li>a single API to manage the various scoped namespaces
64   * <li>a number of convenience API's to access various public objects
65   * <li>a mechanism to obtain the JspWriter for output
66   * <li>a mechanism to manage session usage by the page
67   * <li>a mechanism to expose page directive attributes to the scripting 
68   *     environment
69   * <li>mechanisms to forward or include the current request to other active 
70   *     components in the application
71   * <li>a mechanism to handle errorpage exception processing
72   * </ul>
73   *
74   * <p><B>Methods Intended for Container Generated Code</B>
75   * <p>Some methods are intended to be used by the code generated by the
76   * container, not by code written by JSP page authors, or JSP tag library 
77   * authors.
78   * <p>The methods supporting <B>lifecycle</B> are <code>initialize()</code>
79   * and <code>release()</code>
80   *
81   * <p>
82   * The following methods enable the <B>management of nested</B> JspWriter 
83   * streams to implement Tag Extensions: <code>pushBody()</code>
84   *
85   * <p><B>Methods Intended for JSP authors</B>
86   * <p>
87   * The following methods provide <B>convenient access</B> to implicit objects:
88   * <code>getException()</code>,  <code>getPage()</code>
89   * <code>getRequest()</code>,  <code>getResponse()</code>,
90   * <code>getSession()</code>,  <code>getServletConfig()</code>
91   * and <code>getServletContext()</code>.
92   *
93   * <p>
94   * The following methods provide support for <B>forwarding, inclusion
95   * and error handling</B>:
96   * <code>forward()</code>,  <code>include()</code>,
97   * and  <code>handlePageException()</code>.
98   */
99  
100 abstract public class PageContext 
101     extends JspContext
102 {
103     
104     /**
105      * Sole constructor. (For invocation by subclass constructors, 
106      * typically implicit.)
107      */
108     public PageContext() {
109     }
110     
111     /**
112      * Page scope: (this is the default) the named reference remains available
113      * in this PageContext until the return from the current Servlet.service()
114      * invocation.
115      */
116 
117     public static final int PAGE_SCOPE		= 1;
118 
119     /**
120      * Request scope: the named reference remains available from the 
121      * ServletRequest associated with the Servlet until the current request 
122      * is completed.
123      */
124 
125     public static final int REQUEST_SCOPE	= 2;
126 
127     /**
128      * Session scope (only valid if this page participates in a session):
129      * the named reference remains available from the HttpSession (if any)
130      * associated with the Servlet until the HttpSession is invalidated.
131      */
132 
133     public static final int SESSION_SCOPE	= 3;
134 
135     /**
136      * Application scope: named reference remains available in the 
137      * ServletContext until it is reclaimed.
138      */
139 
140     public static final int APPLICATION_SCOPE	= 4;
141 
142     /**
143      * Name used to store the Servlet in this PageContext's nametables.
144      */
145 
146     public static final String PAGE = "javax.servlet.jsp.jspPage";
147 
148     /**
149      * Name used to store this PageContext in it's own name table.
150      */
151 
152     public static final String PAGECONTEXT = "javax.servlet.jsp.jspPageContext";
153 
154     /**
155      * Name used to store ServletRequest in PageContext name table.
156      */
157 
158     public static final String REQUEST = "javax.servlet.jsp.jspRequest";
159 
160     /**
161      * Name used to store ServletResponse in PageContext name table.
162      */
163 
164     public static final String RESPONSE = "javax.servlet.jsp.jspResponse";
165 
166     /**
167      * Name used to store ServletConfig in PageContext name table.
168      */
169 
170     public static final String CONFIG = "javax.servlet.jsp.jspConfig";
171 
172     /**
173      * Name used to store HttpSession in PageContext name table.
174      */
175 
176     public static final String SESSION = "javax.servlet.jsp.jspSession";
177     /**
178      * Name used to store current JspWriter in PageContext name table.
179      */
180 
181     public static final String OUT = "javax.servlet.jsp.jspOut";
182 
183     /**
184      * Name used to store ServletContext in PageContext name table.
185      */
186 
187     public static final String APPLICATION = "javax.servlet.jsp.jspApplication";
188 
189     /**
190      * Name used to store uncaught exception in ServletRequest attribute 
191      * list and PageContext name table.
192      */
193 
194     public static final String EXCEPTION = "javax.servlet.jsp.jspException";
195 
196     /**
197      * <p>
198      * The initialize method is called to initialize an uninitialized PageContext
199      * so that it may be used by a JSP Implementation class to service an
200      * incoming request and response within it's _jspService() method.
201      *
202      * <p>
203      * This method is typically called from JspFactory.getPageContext() in
204      * order to initialize state.
205      *
206      * <p>
207      * This method is required to create an initial JspWriter, and associate
208      * the "out" name in page scope with this newly created object.
209      *
210      * <p>
211      * This method should not be used by page  or tag library authors.
212      *
213      * @param servlet The Servlet that is associated with this PageContext
214      * @param request The currently pending request for this Servlet
215      * @param response The currently pending response for this Servlet
216      * @param errorPageURL The value of the errorpage attribute from the page 
217      *     directive or null
218      * @param needsSession The value of the session attribute from the 
219      *     page directive
220      * @param bufferSize The value of the buffer attribute from the page 
221      *     directive
222      * @param autoFlush The value of the autoflush attribute from the page 
223      *     directive
224      *
225      * @throws IOException during creation of JspWriter
226      * @throws IllegalStateException if out not correctly initialized
227      * @throws IllegalArgumentException If one of the given parameters
228      *     is invalid
229      */
230  
231     abstract public void initialize(Servlet servlet, ServletRequest request, 
232         ServletResponse response, String errorPageURL, boolean needsSession, 
233         int bufferSize, boolean autoFlush)  
234         throws IOException, IllegalStateException, IllegalArgumentException;
235 
236     /**
237      * <p>
238      * This method shall "reset" the internal state of a PageContext, releasing
239      * all internal references, and preparing the PageContext for potential
240      * reuse by a later invocation of initialize(). This method is typically
241      * called from JspFactory.releasePageContext().
242      *
243      * <p>
244      * Subclasses shall envelope this method.
245      *
246      * <p>
247      * This method should not be used by page  or tag library authors.
248      *
249      */
250 
251     abstract public void release();
252 
253     /**
254      * The current value of the session object (an HttpSession).
255      *
256      * @return the HttpSession for this PageContext or null
257      */
258 
259     abstract public HttpSession getSession();
260 
261     /**
262      * The current value of the page object (In a Servlet environment, 
263      * this is an instance of javax.servlet.Servlet).
264      *
265      * @return the Page implementation class instance associated 
266      *     with this PageContext
267      */
268 
269     abstract public Object getPage();
270 
271 
272     /**
273      * The current value of the request object (a ServletRequest).
274      *
275      * @return The ServletRequest for this PageContext
276      */
277 
278     abstract public ServletRequest getRequest();
279 
280     /**
281      * The current value of the response object (a ServletResponse).
282      *
283      * @return the ServletResponse for this PageContext
284      */
285 
286     abstract public ServletResponse getResponse();
287 
288     /**
289      * The current value of the exception object (an Exception).
290      *
291      * @return any exception passed to this as an errorpage
292      */
293 
294     abstract public Exception getException();
295 
296     /**
297      * The ServletConfig instance.
298      *
299      * @return the ServletConfig for this PageContext
300      */
301 
302     abstract public ServletConfig getServletConfig();
303 
304     /**
305      * The ServletContext instance.
306      * 
307      * @return the ServletContext for this PageContext
308      */
309 
310     abstract public ServletContext getServletContext();
311 
312     /**
313      * <p>
314      * This method is used to re-direct, or "forward" the current 
315      * ServletRequest and ServletResponse to another active component in 
316      * the application.
317      * </p>
318      * <p>
319      * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
320      * is calculated relative to the DOCROOT of the <code> ServletContext </code>
321      * for this JSP. If the path does not begin with a "/" then the URL 
322      * specified is calculated relative to the URL of the request that was
323      * mapped to the calling JSP.
324      * </p>
325      * <p>
326      * It is only valid to call this method from a <code> Thread </code>
327      * executing within a <code> _jspService(...) </code> method of a JSP.
328      * </p>
329      * <p>
330      * Once this method has been called successfully, it is illegal for the
331      * calling <code> Thread </code> to attempt to modify the <code>
332      * ServletResponse </code> object.  Any such attempt to do so, shall result
333      * in undefined behavior. Typically, callers immediately return from 
334      * <code> _jspService(...) </code> after calling this method.
335      * </p>
336      *
337      * @param relativeUrlPath specifies the relative URL path to the target 
338      *     resource as described above
339      *
340      * @throws IllegalStateException if <code> ServletResponse </code> is not 
341      *     in a state where a forward can be performed
342      * @throws ServletException if the page that was forwarded to throws
343      *     a ServletException
344      * @throws IOException if an I/O error occurred while forwarding
345      */
346 
347     abstract public void forward(String relativeUrlPath) 
348         throws ServletException, IOException;
349 
350     /**
351      * <p>
352      * Causes the resource specified to be processed as part of the current
353      * ServletRequest and ServletResponse being processed by the calling Thread.
354      * The output of the target resources processing of the request is written
355      * directly to the ServletResponse output stream.
356      * </p>
357      * <p>
358      * The current JspWriter "out" for this JSP is flushed as a side-effect
359      * of this call, prior to processing the include.
360      * </p>
361      * <p>
362      * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
363      * is calculated relative to the DOCROOT of the <code>ServletContext</code>
364      * for this JSP. If the path does not begin with a "/" then the URL 
365      * specified is calculated relative to the URL of the request that was
366      * mapped to the calling JSP.
367      * </p>
368      * <p>
369      * It is only valid to call this method from a <code> Thread </code>
370      * executing within a <code> _jspService(...) </code> method of a JSP.
371      * </p>
372      *
373      * @param relativeUrlPath specifies the relative URL path to the target 
374      *     resource to be included
375      *
376      * @throws ServletException if the page that was forwarded to throws
377      *     a ServletException
378      * @throws IOException if an I/O error occurred while forwarding
379      */
380     abstract public void include(String relativeUrlPath) 
381         throws ServletException, IOException;
382 
383     /**
384      * <p>
385      * Causes the resource specified to be processed as part of the current
386      * ServletRequest and ServletResponse being processed by the calling Thread.
387      * The output of the target resources processing of the request is written
388      * directly to the current JspWriter returned by a call to getOut().
389      * </p>
390      * <p>
391      * If flush is true, The current JspWriter "out" for this JSP 
392      * is flushed as a side-effect of this call, prior to processing 
393      * the include.  Otherwise, the JspWriter "out" is not flushed.
394      * </p>
395      * <p>
396      * If the <i>relativeUrlPath</i> begins with a "/" then the URL specified
397      * is calculated relative to the DOCROOT of the <code>ServletContext</code>
398      * for this JSP. If the path does not begin with a "/" then the URL 
399      * specified is calculated relative to the URL of the request that was
400      * mapped to the calling JSP.
401      * </p>
402      * <p>
403      * It is only valid to call this method from a <code> Thread </code>
404      * executing within a <code> _jspService(...) </code> method of a JSP.
405      * </p>
406      *
407      * @param relativeUrlPath specifies the relative URL path to the 
408      *     target resource to be included
409      * @param flush True if the JspWriter is to be flushed before the include,
410      *     or false if not.
411      *
412      * @throws ServletException if the page that was forwarded to throws
413      *     a ServletException
414      * @throws IOException if an I/O error occurred while forwarding
415      * @since 2.0
416      */
417     abstract public void include(String relativeUrlPath, boolean flush) 
418 	throws ServletException, IOException;
419 
420     /**
421      * <p>
422      * This method is intended to process an unhandled 'page' level
423      * exception by forwarding the exception to the specified
424      * error page for this JSP.  If forwarding is not possible (for
425      * example because the response has already been committed), an
426      * implementation dependent mechanism should be used to invoke
427      * the error page (e.g. "including" the error page instead).
428      *
429      * <p>
430      * If no error page is defined in the page, the exception should
431      * be rethrown so that the standard servlet error handling
432      * takes over.
433      *
434      * <p>
435      * A JSP implementation class shall typically clean up any local state
436      * prior to invoking this and will return immediately thereafter. It is
437      * illegal to generate any output to the client, or to modify any 
438      * ServletResponse state after invoking this call.
439      *
440      * <p>
441      * This method is kept for backwards compatiblity reasons.  Newly
442      * generated code should use PageContext.handlePageException(Throwable).
443      *
444      * @param e the exception to be handled
445      *
446      * @throws ServletException if an error occurs while invoking the error page
447      * @throws IOException if an I/O error occurred while invoking the error
448      *     page
449      * @throws NullPointerException if the exception is null
450      *
451      * @see #handlePageException(Throwable)
452      */
453 
454     abstract public void handlePageException(Exception e) 
455         throws ServletException, IOException;
456 
457     /**
458      * <p>
459      * This method is intended to process an unhandled 'page' level
460      * exception by forwarding the exception to the specified
461      * error page for this JSP.  If forwarding is not possible (for
462      * example because the response has already been committed), an
463      * implementation dependent mechanism should be used to invoke
464      * the error page (e.g. "including" the error page instead).
465      *
466      * <p>
467      * If no error page is defined in the page, the exception should
468      * be rethrown so that the standard servlet error handling
469      * takes over.
470      *
471      * <p>
472      * This method is intended to process an unhandled "page" level exception
473      * by redirecting the exception to either the specified error page for this
474      * JSP, or if none was specified, to perform some implementation dependent
475      * action.
476      *
477      * <p>
478      * A JSP implementation class shall typically clean up any local state
479      * prior to invoking this and will return immediately thereafter. It is
480      * illegal to generate any output to the client, or to modify any 
481      * ServletResponse state after invoking this call.
482      *
483      * @param t the throwable to be handled
484      *
485      * @throws ServletException if an error occurs while invoking the error page
486      * @throws IOException if an I/O error occurred while invoking the error
487      *     page
488      * @throws NullPointerException if the exception is null
489      *
490      * @see #handlePageException(Exception)
491      */
492 
493     abstract public void handlePageException(Throwable t) 
494         throws ServletException, IOException;
495 
496     /**
497      * Return a new BodyContent object, save the current "out" JspWriter,
498      * and update the value of the "out" attribute in the page scope
499      * attribute namespace of the PageContext.
500      *
501      * @return the new BodyContent
502      */
503 
504     public BodyContent pushBody() {
505         return null; // XXX to implement
506     }
507          
508 
509     /**
510      * Provides convenient access to error information.
511      *
512      * @return an ErrorData instance containing information about the 
513      * error, as obtained from the request attributes, as per the 
514      * Servlet specification.  If this is not an error page (that is,
515      * if the isErrorPage attribute of the page directive is not set
516      * to "true"), the information is meaningless.
517      *
518      * @since 2.0
519      */
520     public ErrorData getErrorData() {
521 	return new ErrorData( 
522 	    (Throwable)getRequest().getAttribute( "javax.servlet.error.exception" ),
523 	    ((Integer)getRequest().getAttribute( 
524 		"javax.servlet.error.status_code" )).intValue(),
525 	    (String)getRequest().getAttribute( "javax.servlet.error.request_uri" ),
526 	    (String)getRequest().getAttribute( "javax.servlet.error.servlet_name" ) );
527     }
528     
529 }