javax.servlet.jsp.PageContext类

javax.servlet.jsp.PageContext源码

java.lang.Object
	|--javax.servlet.jsp.JspContext
		|--javax.servlet.jsp.PageContext

/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements.  See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License.  You may obtain a copy of the License at
*
*     http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

package javax.servlet.jsp;

import java.io.IOException;

import javax.servlet.RequestDispatcher;
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.HttpSession;
import javax.servlet.jsp.tagext.BodyContent;

/**
 * <p>
 * PageContext extends JspContext to provide useful context information for
 * when JSP technology is used in a Servlet environment.
 
 PageContext继承了JspContext类，当在Servlet环境中使用JSP技术，这提供了很有用的信息。
 
 * <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.  Implicit objects are added
 * to the pageContext automatically.
 
 PageContext实例提供对与JSP页面关联的所有名称空间的访问,提供对几个页面属性的访问，以及对实现细节之上的层的访问（指的就是四大域对象）。
 隐式对象被自动添加到pageContext中（指的就是九大内置对象）。
 
 * <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().
 
 PageContext类是一个抽象类，专门用来被继承，然后提供与其相关的实现，符合JSP的运行环境。
 JspFactory.getPageContext()方法可以创建PageContext实例
 JspFactory.releasePageContext()方法可以释放PageContext实例
 
 * <p> An example of how PageContext, JspFactory, and other classes can be
 * used  within a JSP Page Implementation object is given elsewhere.
 
 在其他地方指明了在一个JSP页面实现对象中如何使用PageContext, JspFactory和其他类。
 
 * <p>
 * The PageContext provides a number of facilities to the page/component
 * author and page implementor, including:
 
 PageContext提供了页面和组件的作者提供了很多的工具，包括：
 
 * <ul>
 * <li>a single API to manage the various scoped namespaces
 
 >> 一个单独的API用来管理不同范围的名称空间
 
 * <li>a number of convenience API's to access various public objects
 
 >> 许多便利的API可以访问各种公共对象
 
 * <li>a mechanism to obtain the JspWriter for output
 
 >> 可以获取JspWirter实现输出的机制
 
 * <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
 
 >> 处理错误页面异常的机制
 
 * </ul>
 *
 * <p><B>Methods Intended for Container Generated Code</B>
 * <p>Some methods are intended to be used by the code generated by the
 * container, not by code written by JSP page authors, or JSP tag library
 * authors.
 * <p>The methods supporting <B>lifecycle</B> are <code>initialize()</code>
 * and <code>release()</code>
 
 容器生成代码的方法：
 initializa()
 release()
 
 * <p>
 * The following methods enable the <B>management of nested</B> JspWriter
 * streams to implement Tag Extensions: <code>pushBody()</code>

嵌套管理：
pushBody()
 
 
 * <p><B>Methods Intended for JSP authors</B>
 * <p>
 * The following methods provide <B>convenient access</B> to implicit objects:
 * <code>getException()</code>,  <code>getPage()</code>
 * <code>getRequest()</code>,  <code>getResponse()</code>,
 * <code>getSession()</code>,  <code>getServletConfig()</code>
 * and <code>getServletContext()</code>.
 
 针对JSP作者的方法：
 getException()
 getPage()
 getRequest()
 getResponse()
 getSession()
 getServletConfig()
 getServletContext()
 
 
 * <p>
 * The following methods provide support for <B>forwarding, inclusion
 * and error handling</B>:
 * <code>forward()</code>,  <code>include()</code>,
 * and  <code>handlePageException()</code>.
 
 其余的方法用来：请求转发，包含，处理页面异常：
 
 forward()
 include()
 handlePageException()
 
 
 
 */

public abstract class PageContext extends JspContext{

    /**
     * Sole constructor. (For invocation by subclass constructors,
     * typically implicit.)
     */
    public PageContext() {
        // NOOP by default
    }

    /**************************************四大域***********************************/
    /**
     * Page scope: (this is the default) the named reference remains available
     * in this PageContext until the return from the current Servlet.service()
     * invocation.
     */
    
    // 默认为Page域（最小域），直到从当前的Servelet.service()启用返回都有效

    public static final int PAGE_SCOPE = 1;

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

    // Request域，直到当前请求结束都有效
    
    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.
     */

    // Session域（仅当此页面参与会话才有效）
    // HttpSession无效时则终止
    
    public static final int SESSION_SCOPE = 3;

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

    // Application域，直到被回收都有效
    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 table.
     */

    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 method 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 within it's _jspService() method.
     *
     * <p>
     * This method is typically called from JspFactory.getPageContext() in
     * order to initialize state.
     *
     * <p>
     * This method is required to create an initial JspWriter, and associate
     * the "out" name in page scope with this newly created object.
     * <p>
     * This method should not be used by page  or tag library authors.
     *
     * @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
     * @throws IllegalArgumentException If one of the given parameters
     *     is invalid
     */

    public abstract 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>
     * Subclasses shall envelope this method.
     *
     * <p>
     * This method should not be used by page  or tag library authors.
     *
     */

    public abstract void release();

    /**
     * The current value of the session object (an HttpSession).
     *
     * @return the HttpSession for this PageContext or null
     */

    public abstract HttpSession getSession();

    /**
     * The current value of the page object (In a Servlet environment,
     * this is an instance of javax.servlet.Servlet).
     *
     * @return the Page implementation class instance associated
     *     with this PageContext
     */

    public abstract Object getPage();


    /**
     * The current value of the request object (a ServletRequest).
     *
     * @return The ServletRequest for this PageContext
     */

    public abstract ServletRequest getRequest();

    /**
     * The current value of the response object (a ServletResponse).
     *
     * @return the ServletResponse for this PageContext
     */

    public abstract ServletResponse getResponse();

    /**
     * The current value of the exception object (an Exception).
     *
     * @return any exception passed to this as an errorpage
     */

    public abstract Exception getException();

    /**
     * The ServletConfig instance.
     *
     * @return the ServletConfig for this PageContext
     */

    public abstract ServletConfig getServletConfig();

    /**
     * The ServletContext instance.
     *
     * @return the ServletContext for this PageContext
     */

    public abstract ServletContext getServletContext();

    /**
     * <p>
     * This method is used to re-direct, or "forward" the current
     * ServletRequest and ServletResponse to another active component in
     * the application.
     * </p>
     * <p>
     * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
     * is calculated relative to the DOCROOT of the <code> ServletContext </code>
     * for this JSP. If the path does not begin with a "/" then the URL
     * specified is calculated relative to the URL of the request that was
     * mapped to the calling JSP.
     * </p>
     * <p>
     * It is only valid to call this method from a <code> Thread </code>
     * executing within a <code> _jspService(...) </code> method of a JSP.
     * </p>
     * <p>
     * Once this method has been called successfully, it is illegal for the
     * calling <code> Thread </code> to attempt to modify the <code>
     * ServletResponse </code> object.  Any such attempt to do so, shall result
     * in undefined behavior. Typically, callers immediately return from
     * <code> _jspService(...) </code> after calling this method.
     * </p>
     *
     * @param relativeUrlPath specifies the relative URL path to the target
     *     resource as described above
     *
     * @throws IllegalStateException if <code> ServletResponse </code> is not
     *     in a state where a forward can be performed
     * @throws ServletException if the page that was forwarded to throws
     *     a ServletException
     * @throws IOException if an I/O error occurred while forwarding
     */

    public abstract void forward(String relativeUrlPath)
        throws ServletException, IOException;

    /**
     * <p>
     * Causes the resource specified to be processed as part of the current
     * ServletRequest and ServletResponse being processed by the calling Thread.
     * The output of the target resources processing of the request is written
     * directly to the ServletResponse output stream.
     * </p>
     * <p>
     * The current JspWriter "out" for this JSP is flushed as a side-effect
     * of this call, prior to processing the include.
     * </p>
     * <p>
     * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
     * is calculated relative to the DOCROOT of the <code>ServletContext</code>
     * for this JSP. If the path does not begin with a "/" then the URL
     * specified is calculated relative to the URL of the request that was
     * mapped to the calling JSP.
     * </p>
     * <p>
     * It is only valid to call this method from a <code> Thread </code>
     * executing within a <code> _jspService(...) </code> method of a JSP.
     * </p>
     *
     * @param relativeUrlPath specifies the relative URL path to the target
     *     resource to be included
     *
     * @throws ServletException if the page that was forwarded to throws
     *     a ServletException
     * @throws IOException if an I/O error occurred while forwarding
     */
    public abstract void include(String relativeUrlPath)
        throws ServletException, IOException;

    /**
     * <p>
     * Causes the resource specified to be processed as part of the current
     * ServletRequest and ServletResponse being processed by the calling Thread.
     * The output of the target resources processing of the request is written
     * directly to the current JspWriter returned by a call to getOut().
     * </p>
     * <p>
     * If flush is true, The current JspWriter "out" for this JSP
     * is flushed as a side-effect of this call, prior to processing
     * the include.  Otherwise, the JspWriter "out" is not flushed.
     * </p>
     * <p>
     * If the <i>relativeUrlPath</i> begins with a "/" then the URL specified
     * is calculated relative to the DOCROOT of the <code>ServletContext</code>
     * for this JSP. If the path does not begin with a "/" then the URL
     * specified is calculated relative to the URL of the request that was
     * mapped to the calling JSP.
     * </p>
     * <p>
     * It is only valid to call this method from a <code> Thread </code>
     * executing within a <code> _jspService(...) </code> method of a JSP.
     * </p>
     *
     * @param relativeUrlPath specifies the relative URL path to the
     *     target resource to be included
     * @param flush True if the JspWriter is to be flushed before the include,
     *     or false if not.
     *
     * @throws ServletException if the page that was forwarded to throws
     *     a ServletException
     * @throws IOException if an I/O error occurred while forwarding
     * @since 2.0
     */
    public abstract void include(String relativeUrlPath, boolean flush)
        throws ServletException, IOException;

    /**
     * <p>
     * This method is intended to process an unhandled 'page' level
     * exception by forwarding the exception to the specified
     * error page for this JSP.  If forwarding is not possible (for
     * example because the response has already been committed), an
     * implementation dependent mechanism should be used to invoke
     * the error page (e.g. "including" the error page instead).
     *
     * <p>
     * If no error page is defined in the page, the exception should
     * be rethrown so that the standard servlet error handling
     * takes over.
     *
     * <p>
     * A JSP implementation class shall typically clean up any local state
     * prior to invoking this and will return immediately thereafter. It is
     * illegal to generate any output to the client, or to modify any
     * ServletResponse state after invoking this call.
     *
     * <p>
     * This method is kept for backwards compatibility reasons.  Newly
     * generated code should use PageContext.handlePageException(Throwable).
     *
     * @param e the exception to be handled
     *
     * @throws ServletException if an error occurs while invoking the error page
     * @throws IOException if an I/O error occurred while invoking the error
     *     page
     * @throws NullPointerException if the exception is null
     *
     * @see #handlePageException(Throwable)
     */

    public abstract void handlePageException(Exception e)
        throws ServletException, IOException;

    /**
     * <p>
     * This method is intended to process an unhandled 'page' level
     * exception by forwarding the exception to the specified
     * error page for this JSP.  If forwarding is not possible (for
     * example because the response has already been committed), an
     * implementation dependent mechanism should be used to invoke
     * the error page (e.g. "including" the error page instead).
     *
     * <p>
     * If no error page is defined in the page, the exception should
     * be rethrown so that the standard servlet error handling
     * takes over.
     *
     * <p>
     * This method is intended to process an unhandled "page" level exception
     * by redirecting the exception to either the specified error page for this
     * JSP, or if none was specified, to perform some implementation dependent
     * action.
     *
     * <p>
     * A JSP implementation class shall typically clean up any local state
     * prior to invoking this and will return immediately thereafter. It is
     * illegal to generate any output to the client, or to modify any
     * ServletResponse state after invoking this call.
     *
     * @param t the throwable to be handled
     *
     * @throws ServletException if an error occurs while invoking the error page
     * @throws IOException if an I/O error occurred while invoking the error
     *     page
     * @throws NullPointerException if the exception is null
     *
     * @see #handlePageException(Exception)
     */

    public abstract void handlePageException(Throwable t)
        throws ServletException, IOException;

    /**
     * Return a new BodyContent object, save the current "out" JspWriter,
     * and update the value of the "out" attribute in the page scope
     * attribute namespace of the PageContext.
     *
     * @return the new BodyContent
     */

    public BodyContent pushBody() {
        return null; // XXX to implement
    }


    /**
     * Provides convenient access to error information.
     *
     * @return an ErrorData instance containing information about the
     * error, as obtained from the request attributes, as per the
     * Servlet specification.  If this is not an error page (that is,
     * if the isErrorPage attribute of the page directive is not set
     * to "true"), the information is meaningless.
     *
     * @since 2.0
     */
    public ErrorData getErrorData() {
        int status = 0;

        Integer status_code = (Integer)getRequest().getAttribute(
                RequestDispatcher.ERROR_STATUS_CODE);
        // Avoid NPE if attribute is not set
        if (status_code != null) {
            status = status_code.intValue();
        }

        return new ErrorData(
            (Throwable)getRequest().getAttribute(
                    RequestDispatcher.ERROR_EXCEPTION),
            status,
            (String)getRequest().getAttribute(
                    RequestDispatcher.ERROR_REQUEST_URI),
            (String)getRequest().getAttribute(
                    RequestDispatcher.ERROR_SERVLET_NAME)
            );
    }

}

四大域

域	作用范围
page域	只能在当前jsp页面使用（当前页面，同时也是最小域）
request域	在同一个请求中使用（转发）
session域	当前会话有效
application域	整个web应用都有效

九大内置对象

具体参考：

JSP的9大内置对象和4大域对象（作用域）

jsp四大作用域和九大对象

JSP九大内置对象及其作用以及四大域对象

对象名称	类型	作用域
page	javax.servlet.jsp.jspPage	page
pageContext	javax.servlet.jsp.jspPageContext	page
request	javax.servlet.jsp.jspRequest	request
response	javax.servlet.jsp.jspResponse	page
config	javax.servlet.jsp.jspConfig	page
session	javax.servlet.jsp.jspSession	session
out	javax.servlet.jsp.jspOut	page
application	javax.servlet.jsp.jspApplication	application
exception	javax.servlet.jsp.jspException	page

page

代表jsp页面本身，只有在当前页面才是合法的，对应this关键字。

pageContext

pageContext对象可以获取其余8大对象。容器自动创建pageContext对象，可以在jsp页面中直接调用pageContext。

request

该对象封装了客户端向服务器端发送的请求参数，例如在FORM表单中填写的信息。封装了由浏览器或者其他客户端生成的Http请求的细节（参数，属性和数据等）。

response

该对象代表了服务端对客户端的响应，封装了返回给Http客户端的输出。

config

该对象代表了JSP的配置信息。

session

session对象是一个JSP内置对象，它在第一个JSP页面被装载时自动创建，完成会话期管理。从一个客户打开浏览器并连接到服务器开始，到客户关闭浏览器离开这个服务器结束，被称为一个会话。

out

该对象代表了向客户端发送数据的对象。

application

服务器启动后就产生了这个application对象，当客户在所访问的网站的各个页面之间浏览时，这个application对象都是同一个，直到服务器关闭。但是与session不同的是，所有客户的application对象都是同一个，即所有客户共享这个内置的application对象。

exception

该对象代表其他页面中的异常和错误。

内置方法

initialize()

release()

getSession()

getPage()

getRequest()

getResponse()

getException

getServletConfig()

getServletContext()

forward()

include()

handlePageException()

pushBody()

getErrorData()