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  ;
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   request, ServletResponse   response)
93      throws ServletException  , IOException  ;
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   request, ServletResponse   response)
130     throws ServletException  , IOException  ;
131 }
132 
133 
134 
135 
136 
137 
138 
139 
140
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags