View Javadoc

    1
    2
    3   /*
    4    * The contents of this file are subject to the terms
    5    * of the Common Development and Distribution License
    6    * (the "License").  You may not use this file except
    7    * in compliance with the License.
    8    *
    9    * You can obtain a copy of the license at
    10   * glassfish/bootstrap/legal/CDDLv1.0.txt or
    11   * https://glassfish.dev.java.net/public/CDDLv1.0.html.
    12   * See the License for the specific language governing
    13   * permissions and limitations under the License.
    14   *
    15   * When distributing Covered Code, include this CDDL
    16   * HEADER in each file and include the License file at
    17   * glassfish/bootstrap/legal/CDDLv1.0.txt.  If applicable,
    18   * add the following below this CDDL HEADER, with the
    19   * fields enclosed by brackets "[]" replaced with your
    20   * own identifying information: Portions Copyright [yyyy]
    21   * [name of copyright owner]
    22   *
    23   * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
    24   *
    25   * Portions Copyright Apache Software Foundation.
    26   */
    27
    28
    29  package javax.servlet;
    30
    31  import java.io.IOException;
    32
    33
    34  /**
    35   * Defines an object that receives requests from the client
    36   * and sends them to any resource (such as a servlet,
    37   * HTML file, or JSP file) on the server. The servlet
    38   * container creates the <code>RequestDispatcher</code> object,
    39   * which is used as a wrapper around a server resource located
    40   * at a particular path or given by a particular name.
    41   *
    42   * <p>This interface is intended to wrap servlets,
    43   * but a servlet container can create <code>RequestDispatcher</code>
    44   * objects to wrap any type of resource.
    45   *
    46   * @author 	Various
    47   *
    48   * @see 	ServletContext#getRequestDispatcher(java.lang.String)
    49   * @see 	ServletContext#getNamedDispatcher(java.lang.String)
    50   * @see 	ServletRequest#getRequestDispatcher(java.lang.String)
    51   *
    52   */
    53
    54  public interface RequestDispatcher {
    55
    56
    57
    58
    59
    60  /**
    61   * Forwards a request from
    62   * a servlet to another resource (servlet, JSP file, or
    63   * HTML file) on the server. This method allows
    64   * one servlet to do preliminary processing of
    65   * a request and another resource to generate
    66   * the response.
    67   *
    68   * <p>For a <code>RequestDispatcher</code> obtained via
    69   * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code>
    70   * object has its path elements and parameters adjusted to match
    71   * the path of the target resource.
    72   *
    73   * <p><code>forward</code> should be called before the response has been
    74   * committed to the client (before response body output has been flushed).
    75   * If the response already has been committed, this method throws
    76   * an <code>IllegalStateException</code>.
    77   * Uncommitted output in the response buffer is automatically cleared
    78   * before the forward.
    79   *
    80   * <p>The request and response parameters must be either the same
    81   * objects as were passed to the calling servlet's service method or be
    82   * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
    83   * that wrap them.
    84   *
    85   *
    86   * @param request		a {@link ServletRequest} object
    87   *				that represents the request the client
    88   * 				makes of the servlet
    89   *
    90   * @param response		a {@link ServletResponse} object
    91   *				that represents the response the servlet
    92   *				returns to the client
    93   *
    94   * @exception ServletException	if the target resource throws this exception
    95   *
    96   * @exception IOException	if the target resource throws this exception
    97   *
    98   * @exception IllegalStateException	if the response was already committed
    99   *
    100  */
    101
    102     public void forward(ServletRequest request, ServletResponse response)
    103 	throws ServletException, IOException;
    104
    105
    106
    107
    108     /**
    109      *
    110      * Includes the content of a resource (servlet, JSP page,
    111      * HTML file) in the response. In essence, this method enables
    112      * programmatic server-side includes.
    113      *
    114      * <p>The {@link ServletResponse} object has its path elements
    115      * and parameters remain unchanged from the caller's. The included
    116      * servlet cannot change the response status code or set headers;
    117      * any attempt to make a change is ignored.
    118      *
    119      * <p>The request and response parameters must be either the same
    120      * objects as were passed to the calling servlet's service method or be
    121      * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
    122      * that wrap them.
    123      *
    124      *
    125      *
    126      * @param request 			a {@link ServletRequest} object
    127      *					that contains the client's request
    128      *
    129      * @param response 			a {@link ServletResponse} object
    130      * 					that contains the servlet's response
    131      *
    132      * @exception ServletException 	if the included resource throws this exception
    133      *
    134      * @exception IOException 		if the included resource throws this exception
    135      *
    136      *
    137      */
    138
    139     public void include(ServletRequest request, ServletResponse response)
    140 	throws ServletException, IOException;
    141 }
    142
    143
    144
    145
    146
    147
    148
    149