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