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 }