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
20
21
22
23
24 package javax.servlet;
25
26 import java.io.IOException;
27
28 /**
29 * Defines an object that receives requests from the client
30 * and sends them to any resource (such as a servlet,
31 * HTML file, or JSP file) on the server. The servlet
32 * container creates the <code>RequestDispatcher</code> object,
33 * which is used as a wrapper around a server resource located
34 * at a particular path or given by a particular name.
35 *
36 * <p>This interface is intended to wrap servlets,
37 * but a servlet container can create <code>RequestDispatcher</code>
38 * objects to wrap any type of resource.
39 *
40 * @see ServletContext#getRequestDispatcher(java.lang.String)
41 * @see ServletContext#getNamedDispatcher(java.lang.String)
42 * @see ServletRequest#getRequestDispatcher(java.lang.String)
43 *
44 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
45 */
46 public interface RequestDispatcher {
47 /**
48 * Forwards a request from
49 * a servlet to another resource (servlet, JSP file, or
50 * HTML file) on the server. This method allows
51 * one servlet to do preliminary processing of
52 * a request and another resource to generate
53 * the response.
54 *
55 * <p>For a <code>RequestDispatcher</code> obtained via
56 * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code>
57 * object has its path elements and parameters adjusted to match
58 * the path of the target resource.
59 *
60 * <p><code>forward</code> should be called before the response has been
61 * committed to the client (before response body output has been flushed).
62 * If the response already has been committed, this method throws
63 * an <code>IllegalStateException</code>.
64 * Uncommitted output in the response buffer is automatically cleared
65 * before the forward.
66 *
67 * <p>The request and response parameters must be either the same
68 * objects as were passed to the calling servlet's service method or be
69 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
70 * that wrap them.
71 *
72 *
73 * @param request a {@link ServletRequest} object
74 * that represents the request the client makes of the servlet
75 *
76 * @param response a {@link ServletResponse} object
77 * that represents the response the servlet returns to the client
78 *
79 * @exception ServletException if the target resource throws this exception
80 *
81 * @exception IOException if the target resource throws this exception
82 *
83 * @exception IllegalStateException if the response was already committed
84 */
85 public void forward(ServletRequest request, ServletResponse response)
86 throws ServletException, IOException;
87
88 /**
89 * Includes the content of a resource (servlet, JSP page,
90 * HTML file) in the response. In essence, this method enables
91 * programmatic server-side includes.
92 *
93 * <p>The {@link ServletResponse} object has its path elements
94 * and parameters remain unchanged from the caller's. The included
95 * servlet cannot change the response status code or set headers;
96 * any attempt to make a change is ignored.
97 *
98 * <p>The request and response parameters must be either the same
99 * objects as were passed to the calling servlet's service method or be
100 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
101 * that wrap them.
102 *
103 * @param request a {@link ServletRequest} object
104 * that contains the client's request
105 *
106 * @param response a {@link ServletResponse} object
107 * that contains the servlet's response
108 *
109 * @exception ServletException if the included resource throws this exception
110 *
111 * @exception IOException if the included resource throws this exception
112 */
113 public void include(ServletRequest request, ServletResponse response)
114 throws ServletException, IOException;
115 }
116
117
118
119
120
121
122
123