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