View Javadoc

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