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