1
2
3 /*
4 * The contents of this file are subject to the terms
5 * of the Common Development and Distribution License
6 * (the "License"). You may not use this file except
7 * in compliance with the License.
8 *
9 * You can obtain a copy of the license at
10 * glassfish/bootstrap/legal/CDDLv1.0.txt or
11 * https://glassfish.dev.java.net/public/CDDLv1.0.html.
12 * See the License for the specific language governing
13 * permissions and limitations under the License.
14 *
15 * When distributing Covered Code, include this CDDL
16 * HEADER in each file and include the License file at
17 * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
18 * add the following below this CDDL HEADER, with the
19 * fields enclosed by brackets "[]" replaced with your
20 * own identifying information: Portions Copyright [yyyy]
21 * [name of copyright owner]
22 *
23 * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
24 *
25 * Portions Copyright Apache Software Foundation.
26 */
27
28
29 package javax.servlet;
30
31 import java.io.IOException;
32
33
34 /**
35 * Defines an object that receives requests from the client
36 * and sends them to any resource (such as a servlet,
37 * HTML file, or JSP file) on the server. The servlet
38 * container creates the <code>RequestDispatcher</code> object,
39 * which is used as a wrapper around a server resource located
40 * at a particular path or given by a particular name.
41 *
42 * <p>This interface is intended to wrap servlets,
43 * but a servlet container can create <code>RequestDispatcher</code>
44 * objects to wrap any type of resource.
45 *
46 * @author Various
47 *
48 * @see ServletContext#getRequestDispatcher(java.lang.String)
49 * @see ServletContext#getNamedDispatcher(java.lang.String)
50 * @see ServletRequest#getRequestDispatcher(java.lang.String)
51 *
52 */
53
54 public interface RequestDispatcher {
55
56
57
58
59
60 /**
61 * Forwards a request from
62 * a servlet to another resource (servlet, JSP file, or
63 * HTML file) on the server. This method allows
64 * one servlet to do preliminary processing of
65 * a request and another resource to generate
66 * the response.
67 *
68 * <p>For a <code>RequestDispatcher</code> obtained via
69 * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code>
70 * object has its path elements and parameters adjusted to match
71 * the path of the target resource.
72 *
73 * <p><code>forward</code> should be called before the response has been
74 * committed to the client (before response body output has been flushed).
75 * If the response already has been committed, this method throws
76 * an <code>IllegalStateException</code>.
77 * Uncommitted output in the response buffer is automatically cleared
78 * before the forward.
79 *
80 * <p>The request and response parameters must be either the same
81 * objects as were passed to the calling servlet's service method or be
82 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
83 * that wrap them.
84 *
85 *
86 * @param request a {@link ServletRequest} object
87 * that represents the request the client
88 * makes of the servlet
89 *
90 * @param response a {@link ServletResponse} object
91 * that represents the response the servlet
92 * returns to the client
93 *
94 * @exception ServletException if the target resource throws this exception
95 *
96 * @exception IOException if the target resource throws this exception
97 *
98 * @exception IllegalStateException if the response was already committed
99 *
100 */
101
102 public void forward(ServletRequest request, ServletResponse response)
103 throws ServletException, IOException;
104
105
106
107
108 /**
109 *
110 * Includes the content of a resource (servlet, JSP page,
111 * HTML file) in the response. In essence, this method enables
112 * programmatic server-side includes.
113 *
114 * <p>The {@link ServletResponse} object has its path elements
115 * and parameters remain unchanged from the caller's. The included
116 * servlet cannot change the response status code or set headers;
117 * any attempt to make a change is ignored.
118 *
119 * <p>The request and response parameters must be either the same
120 * objects as were passed to the calling servlet's service method or be
121 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
122 * that wrap them.
123 *
124 *
125 *
126 * @param request a {@link ServletRequest} object
127 * that contains the client's request
128 *
129 * @param response a {@link ServletResponse} object
130 * that contains the servlet's response
131 *
132 * @exception ServletException if the included resource throws this exception
133 *
134 * @exception IOException if the included resource throws this exception
135 *
136 *
137 */
138
139 public void include(ServletRequest request, ServletResponse response)
140 throws ServletException, IOException;
141 }
142
143
144
145
146
147
148
149