lib/servlet-api/javax/servlet/RequestDispatcher.java

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one or more
   3  * contributor license agreements.  See the NOTICE file distributed with
   4  * this work for additional information regarding copyright ownership.
   5  * The ASF licenses this file to You under the Apache License, Version 2.0
   6  * (the "License"); you may not use this file except in compliance with
   7  * the License.  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 package javax.servlet;
  18
  19 import java.io.IOException;
  20
  21 /**
  22  * Defines an object that receives requests from the client and sends them to
  23  * any resource (such as a servlet, HTML file, or JSP file) on the server. The
  24  * servlet container creates the <code>RequestDispatcher</code> object, which is
  25  * used as a wrapper around a server resource located at a particular path or
  26  * given by a particular name.
  27  *
  28  * <p>
  29  * This interface is intended to wrap servlets, but a servlet container can
  30  * create <code>RequestDispatcher</code> objects to wrap any type of resource.
  31  *
  32  * @see ServletContext#getRequestDispatcher(java.lang.String)
  33  * @see ServletContext#getNamedDispatcher(java.lang.String)
  34  * @see ServletRequest#getRequestDispatcher(java.lang.String)
  35  *
  36  */
  37 public interface RequestDispatcher {
  38
  39     /**
  40      * The name of the request attribute that should be set by the container
  41      * when the {@link #forward(ServletRequest, ServletResponse)} method is
  42      * called. It provides the original value of a path-related property of the
  43      * request. See the chapter "Forwarded Request Parameters" in the Servlet
  44      * Specification for details.
  45      *
  46      * @since Servlet 3.0
  47      */
  48     static final String FORWARD_REQUEST_URI = "javax.servlet.forward.request_uri";
  49
  50     /**
  51      * The name of the request attribute that should be set by the container
  52      * when the {@link #forward(ServletRequest, ServletResponse)} method is
  53      * called. It provides the original value of a path-related property of the
  54      * request. See the chapter "Forwarded Request Parameters" in the Servlet
  55      * Specification for details.
  56      *
  57      * @since Servlet 3.0
  58      */
  59     static final String FORWARD_CONTEXT_PATH = "javax.servlet.forward.context_path";
  60
  61     /**
  62      * The name of the request attribute that should be set by the container
  63      * when the {@link #forward(ServletRequest, ServletResponse)} method is
  64      * called. It provides the original value of a path-related property of the
  65      * request. See the chapter "Forwarded Request Parameters" in the Servlet
  66      * Specification for details.
  67      *
  68      * @since Servlet 3.0
  69      */
  70     static final String FORWARD_PATH_INFO = "javax.servlet.forward.path_info";
  71
  72     /**
  73      * The name of the request attribute that should be set by the container
  74      * when the {@link #forward(ServletRequest, ServletResponse)} method is
  75      * called. It provides the original value of a path-related property of the
  76      * request. See the chapter "Forwarded Request Parameters" in the Servlet
  77      * Specification for details.
  78      *
  79      * @since Servlet 3.0
  80      */
  81     static final String FORWARD_SERVLET_PATH = "javax.servlet.forward.servlet_path";
  82
  83     /**
  84      * The name of the request attribute that should be set by the container
  85      * when the {@link #forward(ServletRequest, ServletResponse)} method is
  86      * called. It provides the original value of a path-related property of the
  87      * request. See the chapter "Forwarded Request Parameters" in the Servlet
  88      * Specification for details.
  89      *
  90      * @since Servlet 3.0
  91      */
  92     static final String FORWARD_QUERY_STRING = "javax.servlet.forward.query_string";
  93
  94     /**
  95      * The name of the request attribute that should be set by the container
  96      * when the {@link #include(ServletRequest, ServletResponse)} method is
  97      * called on the {@code RequestDispatcher} obtained by a path and not by a
  98      * name. It provides information on the path that was used to obtain the
  99      * {@code RequestDispatcher} instance for this include call. See the chapter
 100      * "Included Request Parameters" in the Servlet Specification for details.
 101      *
 102      * @since Servlet 3.0
 103      */
 104     static final String INCLUDE_REQUEST_URI = "javax.servlet.include.request_uri";
 105
 106     /**
 107      * The name of the request attribute that should be set by the container
 108      * when the {@link #include(ServletRequest, ServletResponse)} method is
 109      * called on the {@code RequestDispatcher} obtained by a path and not by a
 110      * name. It provides information on the path that was used to obtain the
 111      * {@code RequestDispatcher} instance for this include call. See the chapter
 112      * "Included Request Parameters" in the Servlet Specification for details.
 113      *
 114      * @since Servlet 3.0
 115      */
 116     static final String INCLUDE_CONTEXT_PATH = "javax.servlet.include.context_path";
 117
 118     /**
 119      * The name of the request attribute that should be set by the container
 120      * when the {@link #include(ServletRequest, ServletResponse)} method is
 121      * called on the {@code RequestDispatcher} obtained by a path and not by a
 122      * name. It provides information on the path that was used to obtain the
 123      * {@code RequestDispatcher} instance for this include call. See the chapter
 124      * "Included Request Parameters" in the Servlet Specification for details.
 125      *
 126      * @since Servlet 3.0
 127      */
 128     static final String INCLUDE_PATH_INFO = "javax.servlet.include.path_info";
 129
 130     /**
 131      * The name of the request attribute that should be set by the container
 132      * when the {@link #include(ServletRequest, ServletResponse)} method is
 133      * called on the {@code RequestDispatcher} obtained by a path and not by a
 134      * name. It provides information on the path that was used to obtain the
 135      * {@code RequestDispatcher} instance for this include call. See the chapter
 136      * "Included Request Parameters" in the Servlet Specification for details.
 137      *
 138      * @since Servlet 3.0
 139      */
 140     static final String INCLUDE_SERVLET_PATH = "javax.servlet.include.servlet_path";
 141
 142     /**
 143      * The name of the request attribute that should be set by the container
 144      * when the {@link #include(ServletRequest, ServletResponse)} method is
 145      * called on the {@code RequestDispatcher} obtained by a path and not by a
 146      * name. It provides information on the path that was used to obtain the
 147      * {@code RequestDispatcher} instance for this include call. See the chapter
 148      * "Included Request Parameters" in the Servlet Specification for details.
 149      *
 150      * @since Servlet 3.0
 151      */
 152     static final String INCLUDE_QUERY_STRING = "javax.servlet.include.query_string";
 153
 154     /**
 155      * The name of the request attribute that should be set by the container
 156      * when custom error-handling servlet or JSP page is invoked. The value of
 157      * the attribute is of type {@code java.lang.Throwable}. See the chapter
 158      * "Error Handling" in the Servlet Specification for details.
 159      *
 160      * @since Servlet 3.0
 161      */
 162     public static final String ERROR_EXCEPTION = "javax.servlet.error.exception";
 163
 164     /**
 165      * The name of the request attribute that should be set by the container
 166      * when custom error-handling servlet or JSP page is invoked. The value of
 167      * the attribute is of type {@code java.lang.Class}. See the chapter
 168      * "Error Handling" in the Servlet Specification for details.
 169      *
 170      * @since Servlet 3.0
 171      */
 172     public static final String ERROR_EXCEPTION_TYPE = "javax.servlet.error.exception_type";
 173
 174     /**
 175      * The name of the request attribute that should be set by the container
 176      * when custom error-handling servlet or JSP page is invoked. The value of
 177      * the attribute is of type {@code java.lang.String}. See the chapter
 178      * "Error Handling" in the Servlet Specification for details.
 179      *
 180      * @since Servlet 3.0
 181      */
 182     public static final String ERROR_MESSAGE = "javax.servlet.error.message";
 183
 184     /**
 185      * The name of the request attribute that should be set by the container
 186      * when custom error-handling servlet or JSP page is invoked. The value of
 187      * the attribute is of type {@code java.lang.String}. See the chapter
 188      * "Error Handling" in the Servlet Specification for details.
 189      *
 190      * @since Servlet 3.0
 191      */
 192     public static final String ERROR_REQUEST_URI = "javax.servlet.error.request_uri";
 193
 194     /**
 195      * The name of the request attribute that should be set by the container
 196      * when custom error-handling servlet or JSP page is invoked. The value of
 197      * the attribute is of type {@code java.lang.String}. See the chapter
 198      * "Error Handling" in the Servlet Specification for details.
 199      *
 200      * @since Servlet 3.0
 201      */
 202     public static final String ERROR_SERVLET_NAME = "javax.servlet.error.servlet_name";
 203
 204     /**
 205      * The name of the request attribute that should be set by the container
 206      * when custom error-handling servlet or JSP page is invoked. The value of
 207      * the attribute is of type {@code java.lang.Integer}. See the chapter
 208      * "Error Handling" in the Servlet Specification for details.
 209      *
 210      * @since Servlet 3.0
 211      */
 212     public static final String ERROR_STATUS_CODE = "javax.servlet.error.status_code";
 213
 214     /**
 215      * Forwards a request from a servlet to another resource (servlet, JSP file,
 216      * or HTML file) on the server. This method allows one servlet to do
 217      * preliminary processing of a request and another resource to generate the
 218      * response.
 219      *
 220      * <p>
 221      * For a <code>RequestDispatcher</code> obtained via
 222      * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code>
 223      * object has its path elements and parameters adjusted to match the path of
 224      * the target resource.
 225      *
 226      * <p>
 227      * <code>forward</code> should be called before the response has been
 228      * committed to the client (before response body output has been flushed).
 229      * If the response already has been committed, this method throws an
 230      * <code>IllegalStateException</code>. Uncommitted output in the response
 231      * buffer is automatically cleared before the forward.
 232      *
 233      * <p>
 234      * The request and response parameters must be either the same objects as
 235      * were passed to the calling servlet's service method or be subclasses of
 236      * the {@link ServletRequestWrapper} or {@link ServletResponseWrapper}
 237      * classes that wrap them.
 238      *
 239      *
 240      * @param request
 241      *            a {@link ServletRequest} object that represents the request
 242      *            the client makes of the servlet
 243      *
 244      * @param response
 245      *            a {@link ServletResponse} object that represents the response
 246      *            the servlet returns to the client
 247      *
 248      * @exception ServletException
 249      *                if the target resource throws this exception
 250      *
 251      * @exception IOException
 252      *                if the target resource throws this exception
 253      *
 254      * @exception IllegalStateException
 255      *                if the response was already committed
 256      */
 257     public void forward(ServletRequest request, ServletResponse response)
 258             throws ServletException, IOException;
 259
 260     /**
 261      * Includes the content of a resource (servlet, JSP page, HTML file) in the
 262      * response. In essence, this method enables programmatic server-side
 263      * includes.
 264      *
 265      * <p>
 266      * The {@link ServletResponse} object has its path elements and parameters
 267      * remain unchanged from the caller's. The included servlet cannot change
 268      * the response status code or set headers; any attempt to make a change is
 269      * ignored.
 270      *
 271      * <p>
 272      * The request and response parameters must be either the same objects as
 273      * were passed to the calling servlet's service method or be subclasses of
 274      * the {@link ServletRequestWrapper} or {@link ServletResponseWrapper}
 275      * classes that wrap them.
 276      *
 277      * @param request
 278      *            a {@link ServletRequest} object that contains the client's
 279      *            request
 280      *
 281      * @param response
 282      *            a {@link ServletResponse} object that contains the servlet's
 283      *            response
 284      *
 285      * @exception ServletException
 286      *                if the included resource throws this exception
 287      *
 288      * @exception IOException
 289      *                if the included resource throws this exception
 290      */
 291     public void include(ServletRequest request, ServletResponse response)
 292             throws ServletException, IOException;
 293 }