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 }