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