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