1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19
20 package javax.servlet;
21
22 import java.io.IOException;
23
24
25 /**
26 * Defines an object that receives requests from the client
27 * and sends them to any resource (such as a servlet,
28 * HTML file, or JSP file) on the server. The servlet
29 * container creates the <code>RequestDispatcher</code> object,
30 * which is used as a wrapper around a server resource located
31 * at a particular path or given by a particular name.
32 *
33 * <p>This interface is intended to wrap servlets,
34 * but a servlet container can create <code>RequestDispatcher</code>
35 * objects to wrap any type of resource.
36 *
37 * @author Various
38 * @version $Version$
39 *
40 * @see ServletContext#getRequestDispatcher(java.lang.String)
41 * @see ServletContext#getNamedDispatcher(java.lang.String)
42 * @see ServletRequest#getRequestDispatcher(java.lang.String)
43 *
44 */
45
46 public interface RequestDispatcher {
47
48
49
50
51
52 /**
53 * Forwards a request from
54 * a servlet to another resource (servlet, JSP file, or
55 * HTML file) on the server. This method allows
56 * one servlet to do preliminary processing of
57 * a request and another resource to generate
58 * the response.
59 *
60 * <p>For a <code>RequestDispatcher</code> obtained via
61 * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code>
62 * object has its path elements and parameters adjusted to match
63 * the path of the target resource.
64 *
65 * <p><code>forward</code> should be called before the response has been
66 * committed to the client (before response body output has been flushed).
67 * If the response already has been committed, this method throws
68 * an <code>IllegalStateException</code>.
69 * Uncommitted output in the response buffer is automatically cleared
70 * before the forward.
71 *
72 * <p>The request and response parameters must be either the same
73 * objects as were passed to the calling servlet's service method or be
74 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
75 * that wrap them.
76 *
77 *
78 * @param request a {@link ServletRequest} object
79 * that represents the request the client
80 * makes of the servlet
81 *
82 * @param response a {@link ServletResponse} object
83 * that represents the response the servlet
84 * returns to the client
85 *
86 * @exception ServletException if the target resource throws this exception
87 *
88 * @exception IOException if the target resource throws this exception
89 *
90 * @exception IllegalStateException if the response was already committed
91 *
92 */
93
94 public void forward(ServletRequest request, ServletResponse response)
95 throws ServletException, IOException;
96
97
98
99
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 *
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 *
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 *
117 *
118 * @param request a {@link ServletRequest} object
119 * that contains the client's request
120 *
121 * @param response a {@link ServletResponse} object
122 * that contains the servlet's response
123 *
124 * @exception ServletException if the included resource throws this exception
125 *
126 * @exception IOException if the included resource throws this exception
127 *
128 *
129 */
130
131 public void include(ServletRequest request, ServletResponse response)
132 throws ServletException, IOException;
133 }
134
135
136
137
138
139
140
141