View Javadoc

    1   /**
    2    *
    3    * Copyright 2003-2004 The Apache Software Foundation
    4    *
    5    *  Licensed under the Apache License, Version 2.0 (the "License");
    6    *  you may not use this file except in compliance with the License.
    7    *  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   *  Unless required by applicable law or agreed to in writing, software
    12   *  distributed under the License is distributed on an "AS IS" BASIS,
    13   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   *  See the License for the specific language governing permissions and
    15   *  limitations under the License.
    16   */
    17
    18  //
    19  // This source code implements specifications defined by the Java
    20  // Community Process. In order to remain compliant with the specification
    21  // DO NOT add / change / or delete method signatures!
    22  //
    23
    24  package javax.servlet.jsp;
    25
    26  import java.io.IOException;
    27
    28  import javax.servlet.Servlet;
    29  import javax.servlet.ServletConfig;
    30  import javax.servlet.ServletContext;
    31  import javax.servlet.ServletException;
    32  import javax.servlet.ServletRequest;
    33  import javax.servlet.ServletResponse;
    34  import javax.servlet.http.HttpSession;
    35  import javax.servlet.jsp.tagext.BodyContent;
    36
    37  /**
    38   * <p>
    39   * PageContext extends JspContext to provide useful context information for
    40   * when JSP technology is used in a Servlet environment.
    41   * <p>
    42   * A PageContext instance provides access to all the namespaces associated
    43   * with a JSP page, provides access to several page attributes, as well as
    44   * a layer above the implementation details.  Implicit objects are added
    45   * to the pageContext automatically.
    46   *
    47   * <p> The <code> PageContext </code> class is an abstract class, designed to be
    48   * extended to provide implementation dependent implementations thereof, by
    49   * conformant JSP engine runtime environments. A PageContext instance is
    50   * obtained by a JSP implementation class by calling the
    51   * JspFactory.getPageContext() method, and is released by calling
    52   * JspFactory.releasePageContext().
    53   *
    54   * <p> An example of how PageContext, JspFactory, and other classes can be
    55   * used  within a JSP Page Implementation object is given elsewhere.
    56   *
    57   * <p>
    58   * The PageContext provides a number of facilities to the page/component
    59   * author and page implementor, including:
    60   * <ul>
    61   * <li>a single API to manage the various scoped namespaces
    62   * <li>a number of convenience API's to access various public objects
    63   * <li>a mechanism to obtain the JspWriter for output
    64   * <li>a mechanism to manage session usage by the page
    65   * <li>a mechanism to expose page directive attributes to the scripting
    66   *     environment
    67   * <li>mechanisms to forward or include the current request to other active
    68   *     _components in the application
    69   * <li>a mechanism to handle errorpage exception processing
    70   * </ul>
    71   *
    72   * <p><B>Methods Intended for Container Generated Code</B>
    73   * <p>Some methods are intended to be used by the code generated by the
    74   * container, not by code written by JSP page authors, or JSP tag library
    75   * authors.
    76   * <p>The methods supporting <B>lifecycle</B> are <code>initialize()</code>
    77   * and <code>release()</code>
    78   *
    79   * <p>
    80   * The following methods enable the <B>management of nested</B> JspWriter
    81   * streams to implement Tag Extensions: <code>pushBody()</code>
    82   *
    83   * <p><B>Methods Intended for JSP authors</B>
    84   * <p>
    85   * The following methods provide <B>convenient access</B> to implicit objects:
    86   * <code>getException()</code>,  <code>getPage()</code>
    87   * <code>getRequest()</code>,  <code>getResponse()</code>,
    88   * <code>getSession()</code>,  <code>getServletConfig()</code>
    89   * and <code>getServletContext()</code>.
    90   *
    91   * <p>
    92   * The following methods provide support for <B>forwarding, inclusion
    93   * and error handling</B>:
    94   * <code>forward()</code>,  <code>include()</code>,
    95   * and  <code>handlePageException()</code>.
    96   */
    97
    98  abstract public class PageContext
    99      extends JspContext
    100 {
    101
    102     /**
    103      * Sole constructor. (For invocation by subclass constructors,
    104      * typically implicit.)
    105      */
    106     public PageContext() {
    107     }
    108
    109     /**
    110      * Page scope: (this is the default) the named reference remains available
    111      * in this PageContext until the return from the current Servlet.service()
    112      * invocation.
    113      */
    114
    115     public static final int PAGE_SCOPE		= 1;
    116
    117     /**
    118      * Request scope: the named reference remains available from the
    119      * ServletRequest associated with the Servlet until the current request
    120      * is completed.
    121      */
    122
    123     public static final int REQUEST_SCOPE	= 2;
    124
    125     /**
    126      * Session scope (only valid if this page participates in a session):
    127      * the named reference remains available from the HttpSession (if any)
    128      * associated with the Servlet until the HttpSession is invalidated.
    129      */
    130
    131     public static final int SESSION_SCOPE	= 3;
    132
    133     /**
    134      * Application scope: named reference remains available in the
    135      * ServletContext until it is reclaimed.
    136      */
    137
    138     public static final int APPLICATION_SCOPE	= 4;
    139
    140     /**
    141      * Name used to store the Servlet in this PageContext's nametables.
    142      */
    143
    144     public static final String PAGE = "javax.servlet.jsp.jspPage";
    145
    146     /**
    147      * Name used to store this PageContext in it's own name table.
    148      */
    149
    150     public static final String PAGECONTEXT = "javax.servlet.jsp.jspPageContext";
    151
    152     /**
    153      * Name used to store ServletRequest in PageContext name table.
    154      */
    155
    156     public static final String REQUEST = "javax.servlet.jsp.jspRequest";
    157
    158     /**
    159      * Name used to store ServletResponse in PageContext name table.
    160      */
    161
    162     public static final String RESPONSE = "javax.servlet.jsp.jspResponse";
    163
    164     /**
    165      * Name used to store ServletConfig in PageContext name table.
    166      */
    167
    168     public static final String CONFIG = "javax.servlet.jsp.jspConfig";
    169
    170     /**
    171      * Name used to store HttpSession in PageContext name table.
    172      */
    173
    174     public static final String SESSION = "javax.servlet.jsp.jspSession";
    175     /**
    176      * Name used to store current JspWriter in PageContext name table.
    177      */
    178
    179     public static final String OUT = "javax.servlet.jsp.jspOut";
    180
    181     /**
    182      * Name used to store ServletContext in PageContext name table.
    183      */
    184
    185     public static final String APPLICATION = "javax.servlet.jsp.jspApplication";
    186
    187     /**
    188      * Name used to store uncaught exception in ServletRequest attribute
    189      * list and PageContext name table.
    190      */
    191
    192     public static final String EXCEPTION = "javax.servlet.jsp.jspException";
    193
    194     /**
    195      * <p>
    196      * The initialize method is called to initialize an uninitialized PageContext
    197      * so that it may be used by a JSP Implementation class to service an
    198      * incoming request and response within it's _jspService() method.
    199      *
    200      * <p>
    201      * This method is typically called from JspFactory.getPageContext() in
    202      * order to initialize state.
    203      *
    204      * <p>
    205      * This method is required to create an initial JspWriter, and associate
    206      * the "out" name in page scope with this newly created object.
    207      *
    208      * <p>
    209      * This method should not be used by page  or tag library authors.
    210      *
    211      * @param servlet The Servlet that is associated with this PageContext
    212      * @param request The currently pending request for this Servlet
    213      * @param response The currently pending response for this Servlet
    214      * @param errorPageURL The value of the errorpage attribute from the page
    215      *     directive or null
    216      * @param needsSession The value of the session attribute from the
    217      *     page directive
    218      * @param bufferSize The value of the buffer attribute from the page
    219      *     directive
    220      * @param autoFlush The value of the autoflush attribute from the page
    221      *     directive
    222      *
    223      * @throws IOException during creation of JspWriter
    224      * @throws IllegalStateException if out not correctly initialized
    225      * @throws IllegalArgumentException If one of the given parameters
    226      *     is invalid
    227      */
    228
    229     abstract public void initialize(Servlet servlet, ServletRequest request,
    230         ServletResponse response, String errorPageURL, boolean needsSession,
    231         int bufferSize, boolean autoFlush)
    232         throws IOException, IllegalStateException, IllegalArgumentException;
    233
    234     /**
    235      * <p>
    236      * This method shall "reset" the internal state of a PageContext, releasing
    237      * all internal references, and preparing the PageContext for potential
    238      * reuse by a later invocation of initialize(). This method is typically
    239      * called from JspFactory.releasePageContext().
    240      *
    241      * <p>
    242      * Subclasses shall envelope this method.
    243      *
    244      * <p>
    245      * This method should not be used by page  or tag library authors.
    246      *
    247      */
    248
    249     abstract public void release();
    250
    251     /**
    252      * The current value of the session object (an HttpSession).
    253      *
    254      * @return the HttpSession for this PageContext or null
    255      */
    256
    257     abstract public HttpSession getSession();
    258
    259     /**
    260      * The current value of the page object (In a Servlet environment,
    261      * this is an instance of javax.servlet.Servlet).
    262      *
    263      * @return the Page implementation class instance associated
    264      *     with this PageContext
    265      */
    266
    267     abstract public Object getPage();
    268
    269
    270     /**
    271      * The current value of the request object (a ServletRequest).
    272      *
    273      * @return The ServletRequest for this PageContext
    274      */
    275
    276     abstract public ServletRequest getRequest();
    277
    278     /**
    279      * The current value of the response object (a ServletResponse).
    280      *
    281      * @return the ServletResponse for this PageContext
    282      */
    283
    284     abstract public ServletResponse getResponse();
    285
    286     /**
    287      * The current value of the exception object (an Exception).
    288      *
    289      * @return any exception passed to this as an errorpage
    290      */
    291
    292     abstract public Exception getException();
    293
    294     /**
    295      * The ServletConfig instance.
    296      *
    297      * @return the ServletConfig for this PageContext
    298      */
    299
    300     abstract public ServletConfig getServletConfig();
    301
    302     /**
    303      * The ServletContext instance.
    304      *
    305      * @return the ServletContext for this PageContext
    306      */
    307
    308     abstract public ServletContext getServletContext();
    309
    310     /**
    311      * <p>
    312      * This method is used to re-direct, or "forward" the current
    313      * ServletRequest and ServletResponse to another active component in
    314      * the application.
    315      * </p>
    316      * <p>
    317      * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
    318      * is calculated relative to the DOCROOT of the <code> ServletContext </code>
    319      * for this JSP. If the path does not begin with a "/" then the URL
    320      * specified is calculated relative to the URL of the request that was
    321      * mapped to the calling JSP.
    322      * </p>
    323      * <p>
    324      * It is only valid to call this method from a <code> Thread </code>
    325      * executing within a <code> _jspService(...) </code> method of a JSP.
    326      * </p>
    327      * <p>
    328      * Once this method has been called successfully, it is illegal for the
    329      * calling <code> Thread </code> to attempt to modify the <code>
    330      * ServletResponse </code> object.  Any such attempt to do so, shall result
    331      * in undefined behavior. Typically, callers immediately return from
    332      * <code> _jspService(...) </code> after calling this method.
    333      * </p>
    334      *
    335      * @param relativeUrlPath specifies the relative URL path to the target
    336      *     resource as described above
    337      *
    338      * @throws IllegalStateException if <code> ServletResponse </code> is not
    339      *     in a state where a forward can be performed
    340      * @throws ServletException if the page that was forwarded to throws
    341      *     a ServletException
    342      * @throws IOException if an I/O error occurred while forwarding
    343      */
    344
    345     abstract public void forward(String relativeUrlPath)
    346         throws ServletException, IOException;
    347
    348     /**
    349      * <p>
    350      * Causes the resource specified to be processed as part of the current
    351      * ServletRequest and ServletResponse being processed by the calling Thread.
    352      * The output of the target resources processing of the request is written
    353      * directly to the ServletResponse output stream.
    354      * </p>
    355      * <p>
    356      * The current JspWriter "out" for this JSP is flushed as a side-effect
    357      * of this call, prior to processing the include.
    358      * </p>
    359      * <p>
    360      * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
    361      * is calculated relative to the DOCROOT of the <code>ServletContext</code>
    362      * for this JSP. If the path does not begin with a "/" then the URL
    363      * specified is calculated relative to the URL of the request that was
    364      * mapped to the calling JSP.
    365      * </p>
    366      * <p>
    367      * It is only valid to call this method from a <code> Thread </code>
    368      * executing within a <code> _jspService(...) </code> method of a JSP.
    369      * </p>
    370      *
    371      * @param relativeUrlPath specifies the relative URL path to the target
    372      *     resource to be included
    373      *
    374      * @throws ServletException if the page that was forwarded to throws
    375      *     a ServletException
    376      * @throws IOException if an I/O error occurred while forwarding
    377      */
    378     abstract public void include(String relativeUrlPath)
    379         throws ServletException, IOException;
    380
    381     /**
    382      * <p>
    383      * Causes the resource specified to be processed as part of the current
    384      * ServletRequest and ServletResponse being processed by the calling Thread.
    385      * The output of the target resources processing of the request is written
    386      * directly to the current JspWriter returned by a call to getOut().
    387      * </p>
    388      * <p>
    389      * If flush is true, The current JspWriter "out" for this JSP
    390      * is flushed as a side-effect of this call, prior to processing
    391      * the include.  Otherwise, the JspWriter "out" is not flushed.
    392      * </p>
    393      * <p>
    394      * If the <i>relativeUrlPath</i> begins with a "/" then the URL specified
    395      * is calculated relative to the DOCROOT of the <code>ServletContext</code>
    396      * for this JSP. If the path does not begin with a "/" then the URL
    397      * specified is calculated relative to the URL of the request that was
    398      * mapped to the calling JSP.
    399      * </p>
    400      * <p>
    401      * It is only valid to call this method from a <code> Thread </code>
    402      * executing within a <code> _jspService(...) </code> method of a JSP.
    403      * </p>
    404      *
    405      * @param relativeUrlPath specifies the relative URL path to the
    406      *     target resource to be included
    407      * @param flush True if the JspWriter is to be flushed before the include,
    408      *     or false if not.
    409      *
    410      * @throws ServletException if the page that was forwarded to throws
    411      *     a ServletException
    412      * @throws IOException if an I/O error occurred while forwarding
    413      * @since 2.0
    414      */
    415     abstract public void include(String relativeUrlPath, boolean flush)
    416 	throws ServletException, IOException;
    417
    418     /**
    419      * <p>
    420      * This method is intended to process an unhandled 'page' level
    421      * exception by forwarding the exception to the specified
    422      * error page for this JSP.  If forwarding is not possible (for
    423      * example because the response has already been committed), an
    424      * implementation dependent mechanism should be used to invoke
    425      * the error page (e.g. "including" the error page instead).
    426      *
    427      * <p>
    428      * If no error page is defined in the page, the exception should
    429      * be rethrown so that the standard servlet error handling
    430      * takes over.
    431      *
    432      * <p>
    433      * A JSP implementation class shall typically clean up any local state
    434      * prior to invoking this and will return immediately thereafter. It is
    435      * illegal to generate any output to the client, or to modify any
    436      * ServletResponse state after invoking this call.
    437      *
    438      * <p>
    439      * This method is kept for backwards compatiblity reasons.  Newly
    440      * generated code should use PageContext.handlePageException(Throwable).
    441      *
    442      * @param e the exception to be handled
    443      *
    444      * @throws ServletException if an error occurs while invoking the error page
    445      * @throws IOException if an I/O error occurred while invoking the error
    446      *     page
    447      * @throws NullPointerException if the exception is null
    448      *
    449      * @see #handlePageException(Throwable)
    450      */
    451
    452     abstract public void handlePageException(Exception e)
    453         throws ServletException, IOException;
    454
    455     /**
    456      * <p>
    457      * This method is intended to process an unhandled 'page' level
    458      * exception by forwarding the exception to the specified
    459      * error page for this JSP.  If forwarding is not possible (for
    460      * example because the response has already been committed), an
    461      * implementation dependent mechanism should be used to invoke
    462      * the error page (e.g. "including" the error page instead).
    463      *
    464      * <p>
    465      * If no error page is defined in the page, the exception should
    466      * be rethrown so that the standard servlet error handling
    467      * takes over.
    468      *
    469      * <p>
    470      * This method is intended to process an unhandled "page" level exception
    471      * by redirecting the exception to either the specified error page for this
    472      * JSP, or if none was specified, to perform some implementation dependent
    473      * action.
    474      *
    475      * <p>
    476      * A JSP implementation class shall typically clean up any local state
    477      * prior to invoking this and will return immediately thereafter. It is
    478      * illegal to generate any output to the client, or to modify any
    479      * ServletResponse state after invoking this call.
    480      *
    481      * @param t the throwable to be handled
    482      *
    483      * @throws ServletException if an error occurs while invoking the error page
    484      * @throws IOException if an I/O error occurred while invoking the error
    485      *     page
    486      * @throws NullPointerException if the exception is null
    487      *
    488      * @see #handlePageException(Exception)
    489      */
    490
    491     abstract public void handlePageException(Throwable t)
    492         throws ServletException, IOException;
    493
    494     /**
    495      * Return a new BodyContent object, save the current "out" JspWriter,
    496      * and update the value of the "out" attribute in the page scope
    497      * attribute namespace of the PageContext.
    498      *
    499      * @return the new BodyContent
    500      */
    501
    502     public BodyContent pushBody() {
    503         return null; // XXX to implement
    504     }
    505
    506
    507     /**
    508      * Provides convenient access to error information.
    509      *
    510      * @return an ErrorData instance containing information about the
    511      * error, as obtained from the request attributes, as per the
    512      * Servlet specification.  If this is not an error page (that is,
    513      * if the isErrorPage attribute of the page directive is not set
    514      * to "true"), the information is meaningless.
    515      *
    516      * @since 2.0
    517      */
    518     public ErrorData getErrorData() {
    519 	return new ErrorData(
    520 	    (Throwable)getRequest().getAttribute( "javax.servlet.error.exception" ),
    521 	    ((Integer)getRequest().getAttribute(
    522 		"javax.servlet.error.status_code" )).intValue(),
    523 	    (String)getRequest().getAttribute( "javax.servlet.error.request_uri" ),
    524 	    (String)getRequest().getAttribute( "javax.servlet.error.servlet_name" ) );
    525     }
    526
    527 }