View Javadoc

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