/*
 * The Apache Software License, Version 1.1
 *
 * Copyright (c) 1999 The Apache Software Foundation.  All rights 
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution, if
 *    any, must include the following acknowlegement:  
 *       "This product includes software developed by the 
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowlegement may appear in the software itself,
 *    if and wherever such third-party acknowlegements normally appear.
 *
 * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
 *    Foundation" must not be used to endorse or promote products derived
 *    from this software without prior written permission. For written 
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache"
 *    nor may "Apache" appear in their names without prior written
 *    permission of the Apache Group.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */ 
 
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;

import javax.servlet.jsp.tagext.BodyContent;

/**
 * <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>
     * <p>
     * This method is required to create an initial JspWriter, and associate
     * the "out" name in page scope with this newly created object.
     * </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