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