PageContext.java
上传用户:tanyanyong
上传日期:2013-06-23
资源大小:1355k
文件大小:18k
源码类别:

电子政务应用

开发平台:

MultiPlatform

  1. /*
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 1999 The Apache Software Foundation.  All rights 
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer. 
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution, if
  20.  *    any, must include the following acknowlegement:  
  21.  *       "This product includes software developed by the 
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowlegement may appear in the software itself,
  24.  *    if and wherever such third-party acknowlegements normally appear.
  25.  *
  26.  * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
  27.  *    Foundation" must not be used to endorse or promote products derived
  28.  *    from this software without prior written permission. For written 
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache"
  32.  *    nor may "Apache" appear in their names without prior written
  33.  *    permission of the Apache Group.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  *
  54.  */ 
  55.  
  56. package javax.servlet.jsp;
  57. import java.io.IOException;
  58. import java.util.Enumeration;
  59. import javax.servlet.Servlet;
  60. import javax.servlet.ServletConfig;
  61. import javax.servlet.ServletContext;
  62. import javax.servlet.ServletException;
  63. import javax.servlet.ServletRequest;
  64. import javax.servlet.ServletResponse;
  65. import javax.servlet.http.HttpServletRequest;
  66. import javax.servlet.http.HttpSession;
  67. import javax.servlet.jsp.tagext.BodyContent;
  68. /**
  69.  * <p>
  70.  * A PageContext instance provides access to all the namespaces associated with
  71.  * a JSP page, provides access to several page attributes, as well as a layer above the
  72.  * implementation details.
  73.  * <p>
  74.  * An instance of an implementation dependent subclass of this abstract base
  75.  * class is created by a JSP implementation class at the begining of it's
  76.  * <code> _jspService() </code> method via an implementation default 
  77.  * <code> JspFactory </code>, as follows:
  78.  *</p>
  79.  *<p>
  80.  *<p>
  81.  *<code>
  82.  *<pre>
  83.  * public class foo implements Servlet {
  84.  *
  85.  * // ...
  86.  *
  87.  *public void _jspService(HttpServletRequest request,
  88.  * HttpServletResponse response)
  89.  *       throws IOException, ServletException {
  90.  *
  91.  *    JspFactory  factory     = JspFactory.getDefaultFactory();
  92.  *    PageContext pageContext = factory.getPageContext(
  93. this,
  94. request,
  95. response,
  96. null,  // errorPageURL
  97. false, // needsSession
  98. JspWriter.DEFAULT_BUFFER,
  99. true   // autoFlush
  100.         );
  101.  *
  102.  *    // initialize implicit variables for scripting env ...
  103.  *
  104.  *    HttpSession session = pageContext.getSession();
  105.  *    JspWriter   out     = pageContext.getOut();
  106.  *    Object      page    = this;
  107.  *
  108.  *    try {
  109.  *        // body of translated JSP here ...
  110.  *    } catch (Exception e) {
  111.  *        out.clear();
  112.  *        pageContext.handlePageException(e);
  113.  *    } finally {
  114.  *        out.close();
  115.  *   factory.releasePageContext(pageContext);
  116.  *    }
  117.  *}
  118.  *</pre>
  119.  * </code>
  120.  * </p>
  121.  * <p>
  122.  * The <code> PageContext </code> class is an abstract class, designed to be
  123.  * extended to provide implementation dependent implementations thereof, by
  124.  * conformant JSP engine runtime environments. A PageContext instance is 
  125.  * obtained by a JSP implementation class by calling the JspFactory.getPageContext() method, and is released by calling JspFactory.releasePageContext().
  126.  * </p>
  127.  * <p>
  128.  * The PageContext provides a number of facilities to the page/component author and
  129.  * page implementor, including:
  130.  * <td>
  131.  * <li>a single API to manage the various scoped namespaces
  132.  * <li>a number of convenience API's to access various public objects
  133.  * <li>a mechanism to obtain the JspWriter for output
  134.  * <li>a mechanism to manage session usage by the page
  135.  * <li>a mechanism to expose page directive attributes to the scripting environment
  136.  * <li>mechanisms to forward or include the current request to other active components in the application
  137.  * <li>a mechanism to handle errorpage exception processing
  138.  * </td>
  139.  * </p>
  140.  *
  141.  */
  142. abstract public class PageContext {
  143.     /**
  144.      * page scope: (this is the default) the named reference remains available
  145.      * in this PageContext until the return from the current Servlet.service()
  146.      * invocation.
  147.      */
  148.     public static final int PAGE_SCOPE = 1;
  149.     /**
  150.      * request scope: the named reference remains available from the ServletRequest
  151.      * associated with the Servlet that until the current request is completed.
  152.      */
  153.     public static final int REQUEST_SCOPE = 2;
  154.     /**
  155.      * session scope (only valid if this page participates in a session):
  156.      * the named reference remains available from the HttpSession (if any)
  157.      * associated with the Servlet until the HttpSession is invalidated.
  158.      */
  159.     public static final int SESSION_SCOPE = 3;
  160.     /**
  161.      * application scope: named reference remains available in the 
  162.      * ServletContext until it is reclaimed.
  163.      */
  164.     public static final int APPLICATION_SCOPE = 4;
  165.     /**
  166.      * name used to store the Servlet in this PageContext's nametables
  167.      */
  168.     public static final String PAGE = "javax.servlet.jsp.jspPage";
  169.     /**
  170.      * name used to store this PageContext in it's own name tables
  171.      */
  172.     public static final String PAGECONTEXT = "javax.servlet.jsp.jspPageContext";
  173.     /**
  174.      * name used to store ServletRequest in PageContext name table
  175.      */
  176.     public static final String REQUEST = "javax.servlet.jsp.jspRequest";
  177.     /**
  178.      * name used to store ServletResponse in PageContext name table
  179.      */
  180.     public static final String RESPONSE = "javax.servlet.jsp.jspResponse";
  181.     /**
  182.      * name used to store ServletConfig in PageContext name table
  183.      */
  184.     public static final String CONFIG = "javax.servlet.jsp.jspConfig";
  185.     /**
  186.      * name used to store HttpSession in PageContext name table
  187.      */
  188.     public static final String SESSION = "javax.servlet.jsp.jspSession";
  189.     /**
  190.      * name used to store current JspWriter in PageContext name table
  191.      */
  192.     public static final String OUT = "javax.servlet.jsp.jspOut";
  193.     /**
  194.      * name used to store ServletContext in PageContext name table
  195.      */
  196.     public static final String APPLICATION = "javax.servlet.jsp.jspApplication";
  197.     /**
  198.      * name used to store uncaught exception in ServletRequest attribute list and PageContext name table
  199.      */
  200.     public static final String EXCEPTION = "javax.servlet.jsp.jspException";
  201.     /**
  202.      * <p>
  203.      * The initialize emthod is called to initialize an uninitialized PageContext
  204.      * so that it may be used by a JSP Implementation class to service an
  205.      * incoming request and response wihtin it's _jspService() method.
  206.      * </p>
  207.      * <p>
  208.      * This method is typically called from JspFactory.getPageContext() in
  209.      * order to initialize state.
  210.      * </p>
  211.      * <p>
  212.      * This method is required to create an initial JspWriter, and associate
  213.      * the "out" name in page scope with this newly created object.
  214.      * </p>
  215.      *
  216.      * @param servlet The Servlet that is associated with this PageContext
  217.      * @param request The currently pending request for this Servlet
  218.      * @param response The currently pending response for this Servlet
  219.      * @param errorPageURL The value of the errorpage attribute from the page directive or null
  220.      * @param needsSession The value of the session attribute from the page directive
  221.      * @param bufferSize The value of the buffer attribute from the page directive
  222.      * @param autoFlush The value of the autoflush attribute from the page directive
  223.      *
  224.      * @throws IOException during creation of JspWriter
  225.      * @throws IllegalStateException if out not correctly initialized
  226.      */
  227.  
  228.     abstract public void initialize(Servlet servlet, ServletRequest request, ServletResponse response, String errorPageURL, boolean needsSession, int bufferSize, boolean autoFlush)  throws IOException, IllegalStateException, IllegalArgumentException;
  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.      * </p>
  236.      *
  237.      * <p> subclasses shall envelope this method </p>
  238.      *
  239.      */
  240.     abstract public void release();
  241.     /**
  242.      * register the name and object specified with page scope semantics
  243.      * 
  244.      * @throws NullPointerException if the name or object is null
  245.      */
  246.     abstract public void setAttribute(String name, Object attribute);
  247.     /**
  248.      * register the name and object specified with appropriate scope semantics
  249.      * 
  250.      * @param name the name of the attribute to set
  251.      * @param o    the object to associate with the name
  252.      * @param scope the scope with which to associate the name/object
  253.      * 
  254.      * @throws NullPointerException if the name or object is null
  255.      * @throws IllegalArgumentException if the scope is invalid
  256.      *
  257.      */
  258.     abstract public void setAttribute(String name, Object o, int scope);
  259.     /**
  260.      * <p>return the object associated with the name in the page scope or null </p>
  261.      *
  262.      * @param name the name of the attribute to get
  263.      * 
  264.      * @throws NullPointerException if the name is null
  265.      * @throws IllegalArgumentException if the scope is invalid
  266.      */
  267.     abstract public Object getAttribute(String name);
  268.     /**
  269.      * <p>return the object associated with the name in the specifed scope or null </p>
  270.      *
  271.      * @param name the name of the attribute to set
  272.      * @param scope the scope with which to associate the name/object
  273.      * 
  274.      * @throws NullPointerException if the name is null
  275.      * @throws IllegalArgumentException if the scope is invalid
  276.      */
  277.     abstract public Object getAttribute(String name, int scope);
  278.     /**
  279.      * <p>
  280.      * Searches for the named attribute in page, request, session (if valid),
  281.      * and application scope(s) in order and returns the value associated or
  282.      * null.
  283.      * </p>
  284.      *
  285.      * @return the value associated or null
  286.      */
  287.     abstract public Object findAttribute(String name);
  288.     /**
  289.      * remove the object reference associated with the specified name
  290.      */
  291.     abstract public void removeAttribute(String name);
  292.     /**
  293.      * remove the object reference associated with the specified name
  294.      */
  295.     abstract public void removeAttribute(String name, int scope);
  296.     /**
  297.      * @return the scope of the object associated with the name specified or 0
  298.      */
  299.     abstract public int getAttributesScope(String name);
  300.     /**
  301.      * @return an enumeration of names (java.lang.String) of all the attributes the specified scope
  302.      */
  303.     abstract public Enumeration getAttributeNamesInScope(int scope);
  304.     /**
  305.      * @return the current JspWriter stream being used for client response
  306.      */
  307.     abstract public JspWriter getOut();
  308.     /**
  309.      * @return the HttpSession for this PageContext or null
  310.      */
  311.     abstract public HttpSession getSession();
  312.     /**
  313.      * @return the Page implementation class instance (Servlet)  associated with this PageContext
  314.      */
  315.     abstract public Object getPage();
  316.     /**
  317.      * @return The ServletRequest for this PageContext
  318.      */
  319.     abstract public ServletRequest getRequest();
  320.     /**
  321.      * @return the ServletResponse for this PageContext
  322.      */
  323.     abstract public ServletResponse getResponse();
  324.     /**
  325.      * @return any exception passed to this as an errorpage
  326.      */
  327.     abstract public Exception getException();
  328.     /**
  329.      * @return the ServletConfig for this PageContext
  330.      */
  331.     abstract public ServletConfig getServletConfig();
  332.     /**
  333.      * @return the ServletContext for this PageContext
  334.      */
  335.     abstract public ServletContext getServletContext();
  336.     /**
  337.      * <p>
  338.      * This method is used to re-direct, or "forward" the current ServletRequest and ServletResponse to another active component in the application.
  339.      * </p>
  340.      * <p>
  341.      * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
  342.      * is calculated relative to the DOCROOT of the <code> ServletContext </code>
  343.      * for this JSP. If the path does not begin with a "/" then the URL 
  344.      * specified is calculated relative to the URL of the request that was
  345.      * mapped to the calling JSP.
  346.      * </p>
  347.      * <p>
  348.      * It is only valid to call this method from a <code> Thread </code>
  349.      * executing within a <code> _jspService(...) </code> method of a JSP.
  350.      * </p>
  351.      * <p>
  352.      * Once this method has been called successfully, it is illegal for the
  353.      * calling <code> Thread </code> to attempt to modify the <code>
  354.      * ServletResponse </code> object.  Any such attempt to do so, shall result
  355.      * in undefined behavior. Typically, callers immediately return from 
  356.      * <code> _jspService(...) </code> after calling this method.
  357.      * </p>
  358.      *
  359.      * @param relativeUrlPath specifies the relative URL path to the target resource as described above
  360.      *
  361.      * @throws ServletException
  362.      * @throws IOException
  363.      *
  364.      * @throws IllegalArgumentException if target resource URL is unresolvable
  365.      * @throws IllegalStateException if <code> ServletResponse </code> is not in a state where a forward can be performed
  366.      * @throws SecurityException if target resource cannot be accessed by caller
  367.      */
  368.     abstract public void forward(String relativeUrlPath) throws ServletException, IOException;
  369.     /**
  370.      * <p>
  371.      * Causes the resource specified to be processed as part of the current
  372.      * ServletRequest and ServletResponse being processed by the calling Thread.
  373.      * The output of the target resources processing of the request is written
  374.      * directly to the ServletResponse output stream.
  375.      * </p>
  376.      * <p>
  377.      * The current JspWriter "out" for this JSP is flushed as a side-effect
  378.      * of this call, prior to processing the include.
  379.      * </p>
  380.      * <p>
  381.      * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
  382.      * is calculated relative to the DOCROOT of the <code> ServletContext </code>
  383.      * for this JSP. If the path does not begin with a "/" then the URL 
  384.      * specified is calculated relative to the URL of the request that was
  385.      * mapped to the calling JSP.
  386.      * </p>
  387.      * <p>
  388.      * It is only valid to call this method from a <code> Thread </code>
  389.      * executing within a <code> _jspService(...) </code> method of a JSP.
  390.      * </p>
  391.      *
  392.      * @param relativeUrlPath specifies the relative URL path to the target resource to be included
  393.      *
  394.      * @throws ServletException
  395.      * @throws IOException
  396.      *
  397.      * @throws IllegalArgumentException if the target resource URL is unresolvable
  398.      * @throws SecurityException if target resource cannot be accessed by caller
  399.      *
  400.      */
  401.     abstract public void include(String relativeUrlPath) throws ServletException, IOException;
  402.     /**
  403.      * <p>
  404.      * This method is intended to process an unhandled "page" level exception
  405.      * by redirecting the exception to either the specified error page for this
  406.      * JSP, or if none was specified, to perform some implementation dependent
  407.      * action.
  408.      * </p>
  409.      * <p>
  410.      * A JSP implementation class shall typically clean up any local state
  411.      * prior to invoking this and will return immediately thereafter. It is
  412.      * illegal to generate any output to the client, or to modify any 
  413.      * ServletResponse state after invoking this call.
  414.      * </p>
  415.      *
  416.      * @param e the exception to be handled
  417.      *
  418.      * @throws ServletException
  419.      * @throws IOException
  420.      *
  421.      * @throws NullPointerException if the exception is null
  422.      * @throws SecurityException if target resource cannot be accessed by caller
  423.      */
  424.     abstract public void handlePageException(Exception e) throws ServletException, IOException;
  425.     /**
  426.      * Return a new BodyContent object, save the current "out" JspWriter,
  427.      * and update the value of the "out" attribute in the page scope
  428.      * attribute namespace of the PageContext
  429.      *
  430.      * @return the new BodyContent
  431.      */
  432.     public BodyContent pushBody() {
  433.         return null; // XXX to implement
  434.     }
  435.          
  436.     /**
  437.      * Return the previous JspWriter "out" saved by the matching
  438.      * pushBody(), and update the value of the "out" attribute in
  439.      * the page scope attribute namespace of the PageConxtext
  440.      *
  441.      * @return the saved JspWriter.
  442.      */
  443.     public JspWriter popBody() {
  444.         return null; // XXX to implement
  445.     }
  446.     
  447. }