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