KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > servlet > RequestDispatcher


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 JavaDoc;
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 JavaDoc request, ServletResponse JavaDoc response)
93     throws ServletException JavaDoc, IOException JavaDoc;
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 JavaDoc request, ServletResponse JavaDoc response)
130     throws ServletException JavaDoc, IOException JavaDoc;
131 }
132
133
134
135
136
137
138
139
140
Popular Tags