pagecontext.java

JSWDK服务器

/*
 * @(#)PageContext.java	1.16 99/05/28
 * 
 * Copyright (c) 1999 Sun Microsystems, Inc. All Rights Reserved.
 * 
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 * 
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
 * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
 * THIS SOFTWARE OR ITS DERIVATIVES.
 * 
 * CopyrightVersion 1.0
 */
 
package javax.servlet.jsp;

import java.io.IOException;

import java.util.Enumeration;

import javax.servlet.Servlet;
import javax.servlet.ServletConfig;
import javax.servlet.ServletContext;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpSession;

/**
 * <p>
 * A PageContext instance provides access to all the namespaces associated with
 * a JSP page, provides access to several page attributes, as well as a layer above the
 * implementation details.
 * <p>
 * An instance of an implementation dependent subclass of this abstract base
 * class is created by a JSP implementation class at the begining of it's
 * <code> _jspService() </code> method via an implementation default 
 * <code> JspFactory </code>, as follows:
 *</p>
 *<p>
 *<p>
 *<code>
 *<pre>
 * public class foo implements Servlet {
 *
 * // ...
 *
 *public void _jspService(HttpServletRequest request,
 *			HttpServletResponse response)
 *       throws IOException, ServletException {
 *
 *    JspFactory  factory     = JspFactory.getDefaultFactory();
 *    PageContext pageContext = factory.getPageContext(
					this,
					request,
					response,
					null,  // errorPageURL
					false, // needsSession
					JspWriter.DEFAULT_BUFFER,
					true   // autoFlush
			        );
 *
 *    // initialize implicit variables for scripting env ...
 *
 *    HttpSession session = pageContext.getSession();
 *    JspWriter   out     = pageContext.getOut();
 *    Object      page    = this;
 *
 *    try {
 *        // body of translated JSP here ...
 *    } catch (Exception e) {
 *        out.clear();
 *        pageContext.handlePageException(e);
 *    } finally {
 *        out.close();
 *	  factory.releasePageContext(pageContext);
 *    }
 *}
 *</pre>
 * </code>
 * </p>
 * <p>
 * The <code> PageContext </code> class is an abstract class, designed to be
 * extended to provide implementation dependent implementations thereof, by
 * conformant JSP engine runtime environments. A PageContext instance is 
 * obtained by a JSP implementation class by calling the JspFactory.getPageContext() method, and is released by calling JspFactory.releasePageContext().
 * </p>
 * <p>
 * The PageContext provides a number of facilities to the page/component author and
 * page implementor, including:
 * <td>
 * <li>a single API to manage the various scoped namespaces
 * <li>a number of convenience API's to access various public objects
 * <li>a mechanism to obtain the JspWriter for output
 * <li>a mechanism to manage session usage by the page
 * <li>a mechanism to expose page directive attributes to the scripting environment
 * <li>mechanisms to forward or include the current request to other active components in the application
 * <li>a mechanism to handle errorpage exception processing
 * </td>
 * </p>
 *
 */

abstract public class PageContext {

    /**
     * page scope: (this is the default) the named reference remains available
     * in this PageContext until the return from the current Servlet.service()
     * invocation.
     */

    public static final int PAGE_SCOPE		= 1;

    /**
     * request scope: the named reference remains available from the ServletRequest
     * associated with the Servlet that until the current request is completed.
     */

    public static final int REQUEST_SCOPE	= 2;

    /**
     * session scope (only valid if this page participates in a session):
     * the named reference remains available from the HttpSession (if any)
     * associated with the Servlet until the HttpSession is invalidated.
     */

    public static final int SESSION_SCOPE	= 3;

    /**
     * application scope: named reference remains available in the 
     * ServletContext until it is reclaimed.
     */

    public static final int APPLICATION_SCOPE	= 4;

    /**
     * name used to store the Servlet in this PageContext's nametables
     */

    public static final String	PAGE		= "javax.servlet.jsp.jspPage";

    /**
     * name used to store this PageContext in it's own name tables
     */

    public static final String	PAGECONTEXT	= "javax.servlet.jsp.jspPageContext";

    /**
     * name used to store ServletRequest in PageContext name table
     */

    public static final String	REQUEST		= "javax.servlet.jsp.jspRequest";

    /**
     * name used to store ServletResponse in PageContext name table
     */

    public static final String	RESPONSE	= "javax.servlet.jsp.jspResponse";

    /**
     * name used to store ServletConfig in PageContext name table
     */

    public static final String	CONFIG		= "javax.servlet.jsp.jspConfig";

    /**
     * name used to store HttpSession in PageContext name table
     */

    public static final String	SESSION		= "javax.servlet.jsp.jspSession";
    /**
     * name used to store current JspWriter in PageContext name table
     */

    public static final String	OUT		= "javax.servlet.jsp.jspOut";

    /**
     * name used to store ServletContext in PageContext name table
     */

    public static final String	APPLICATION	= "javax.servlet.jsp.jspApplication";

    /**
     * name used to store uncaught exception in ServletRequest attribute list and PageContext name table
     */

    public static final String	EXCEPTION	= "javax.servlet.jsp.jspException";

    /**
     * <p>
     * The initialize emthod is called to initialize an uninitialized PageContext
     * so that it may be used by a JSP Implementation class to service an
     * incoming request and response wihtin it's _jspService() method.
     * </p>
     * <p>
     * This method is typically called from JspFactory.getPageContext() in
     * order to initialize state.
     * </p>
     *
     * @param servlet The Servlet that is associated with this PageContext
     * @param request The currently pending request for this Servlet
     * @param response The currently pending response for this Servlet
     * @param errorPageURL The value of the errorpage attribute from the page directive or null
     * @param needsSession The value of the session attribute from the page directive
     * @param bufferSize The value of the buffer attribute from the page directive
     * @param autoFlush The value of the autoflush attribute from the page directive
     *
     * @throws IOException during creation of JspWriter
     * @throws IllegalStateException if out not correctly initialized
     */
 
    abstract public void initialize(Servlet servlet, ServletRequest request, ServletResponse response, String errorPageURL, boolean needsSession, int bufferSize, boolean autoFlush)  throws IOException, IllegalStateException, IllegalArgumentException;

    /**
     * <p>
     * This method shall "reset" the internal state of a PageContext, releasing
     * all internal references, and preparing the PageContext for potential
     * reuse by a later invocation of initialize(). This method is typically
     * called from JspFactory.releasePageContext().
     * </p>
     *
     * <p> subclasses shall envelope this method </p>
     *