001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020 package javax.servlet;
021
022 import java.io.IOException;
023
024 /**
025 * Defines an object that receives requests from the client
026 * and sends them to any resource (such as a servlet,
027 * HTML file, or JSP file) on the server. The servlet
028 * container creates the <code>RequestDispatcher</code> object,
029 * which is used as a wrapper around a server resource located
030 * at a particular path or given by a particular name.
031 * <p/>
032 * <p>This interface is intended to wrap servlets,
033 * but a servlet container can create <code>RequestDispatcher</code>
034 * objects to wrap any type of resource.
035 *
036 * @version $Rev: 788194 $ $Date: 2009-06-24 18:05:48 -0400 (Wed, 24 Jun 2009) $
037 *
038 * @see ServletContext#getRequestDispatcher(java.lang.String)
039 * @see ServletContext#getNamedDispatcher(java.lang.String)
040 * @see ServletRequest#getRequestDispatcher(java.lang.String)
041 */
042
043 public interface RequestDispatcher {
044
045 //constants since 3.0
046
047 String ERROR_EXCEPTION = "javax.servlet.error.exception";
048 String ERROR_EXCEPTION_TYPE = "javax.servlet.error.exception_type";
049 String ERROR_MESSAGE = "javax.servlet.error.message";
050 String ERROR_REQUEST_URI = "javax.servlet.error.request_uri";
051 String ERROR_SERVLET_NAME = "javax.servlet.error.servlet_name";
052 String ERROR_STATUS_CODE = "javax.servlet.error.status_code";
053 String FORWARD_CONTEXT_PATH = "javax.servlet.forward.context_path";
054 String FORWARD_PATH_INFO = "javax.servlet.forward.path_info";
055 String FORWARD_QUERY_STRING = "javax.servlet.forward.query_string";
056 String FORWARD_REQUEST_URI = "javax.servlet.forward.request_uri";
057 String FORWARD_SERVLET_PATH = "javax.servlet.forward.servlet_path";
058 String INCLUDE_CONTEXT_PATH = "javax.servlet.include.context_path";
059 String INCLUDE_PATH_INFO = "javax.servlet.include.path_info";
060 String INCLUDE_QUERY_STRING = "javax.servlet.include.query_string";
061 String INCLUDE_REQUEST_URI = "javax.servlet.include.request_uri";
062 String INCLUDE_SERVLET_PATH = "javax.servlet.include.servlet_path";
063
064 /**
065 * Forwards a request from
066 * a servlet to another resource (servlet, JSP file, or
067 * HTML file) on the server. This method allows
068 * one servlet to do preliminary processing of
069 * a request and another resource to generate
070 * the response.
071 * <p/>
072 * <p>For a <code>RequestDispatcher</code> obtained via
073 * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code>
074 * object has its path elements and parameters adjusted to match
075 * the path of the target resource.
076 * <p/>
077 * <p><code>forward</code> should be called before the response has been
078 * committed to the client (before response body output has been flushed).
079 * If the response already has been committed, this method throws
080 * an <code>IllegalStateException</code>.
081 * Uncommitted output in the response buffer is automatically cleared
082 * before the forward.
083 * <p/>
084 * <p>The request and response parameters must be either the same
085 * objects as were passed to the calling servlet's service method or be
086 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
087 * that wrap them.
088 *
089 * @param request a {@link ServletRequest} object
090 * that represents the request the client
091 * makes of the servlet
092 * @param response a {@link ServletResponse} object
093 * that represents the response the servlet
094 * returns to the client
095 * @throws ServletException if the target resource throws this exception
096 * @throws IOException if the target resource throws this exception
097 * @throws IllegalStateException if the response was already committed
098 */
099 public void forward(ServletRequest request, ServletResponse response) throws ServletException, IOException;
100
101 /**
102 * Includes the content of a resource (servlet, JSP page,
103 * HTML file) in the response. In essence, this method enables
104 * programmatic server-side includes.
105 * <p/>
106 * <p>The {@link ServletResponse} object has its path elements
107 * and parameters remain unchanged from the caller's. The included
108 * servlet cannot change the response status code or set headers;
109 * any attempt to make a change is ignored.
110 * <p/>
111 * <p>The request and response parameters must be either the same
112 * objects as were passed to the calling servlet's service method or be
113 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
114 * that wrap them.
115 *
116 * @param request a {@link ServletRequest} object
117 * that contains the client's request
118 * @param response a {@link ServletResponse} object
119 * that contains the servlet's response
120 * @throws ServletException if the included resource throws this exception
121 * @throws IOException if the included resource throws this exception
122 */
123 public void include(ServletRequest request, ServletResponse response) throws ServletException, IOException;
124
125 }
126
127
128
129
130
131
132
133