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