View Javadoc

1   /**
2    *
3    * Copyright 2003-2004 The Apache Software Foundation
4    *
5    *  Licensed under the Apache License, Version 2.0 (the "License");
6    *  you may not use this file except in compliance with the License.
7    *  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  //
19  // This source code implements specifications defined by the Java
20  // Community Process. In order to remain compliant with the specification
21  // DO NOT add / change / or delete method signatures!
22  //
23  
24  package javax.servlet;
25  
26  import java.io.IOException;
27  
28  /**
29   * Defines an object that receives requests from the client
30   * and sends them to any resource (such as a servlet,
31   * HTML file, or JSP file) on the server. The servlet
32   * container creates the <code>RequestDispatcher</code> object,
33   * which is used as a wrapper around a server resource located
34   * at a particular path or given by a particular name.
35   *
36   * <p>This interface is intended to wrap servlets,
37   * but a servlet container can create <code>RequestDispatcher</code>
38   * objects to wrap any type of resource.
39   *
40   * @see ServletContext#getRequestDispatcher(java.lang.String)
41   * @see ServletContext#getNamedDispatcher(java.lang.String)
42   * @see ServletRequest#getRequestDispatcher(java.lang.String)
43   *
44   * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
45   */
46  public interface RequestDispatcher {
47      /**
48       * Forwards a request from
49       * a servlet to another resource (servlet, JSP file, or
50       * HTML file) on the server. This method allows
51       * one servlet to do preliminary processing of
52       * a request and another resource to generate
53       * the response.
54       *
55       * <p>For a <code>RequestDispatcher</code> obtained via
56       * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code>
57       * object has its path elements and parameters adjusted to match
58       * the path of the target resource.
59       *
60       * <p><code>forward</code> should be called before the response has been
61       * committed to the client (before response body output has been flushed).
62       * If the response already has been committed, this method throws
63       * an <code>IllegalStateException</code>.
64       * Uncommitted output in the response buffer is automatically cleared
65       * before the forward.
66       *
67       * <p>The request and response parameters must be either the same
68       * objects as were passed to the calling servlet's service method or be
69       * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
70       * that wrap them.
71       *
72       *
73       * @param request a {@link ServletRequest} object
74       * that represents the request the client makes of the servlet
75       *
76       * @param response a {@link ServletResponse} object
77       * that represents the response the servlet returns to the client
78       *
79       * @exception ServletException if the target resource throws this exception
80       *
81       * @exception IOException if the target resource throws this exception
82       *
83       * @exception IllegalStateException if the response was already committed
84       */
85      public void forward(ServletRequest request, ServletResponse response)
86              throws ServletException, IOException;
87  
88      /**
89       * Includes the content of a resource (servlet, JSP page,
90       * HTML file) in the response. In essence, this method enables
91       * programmatic server-side includes.
92       *
93       * <p>The {@link ServletResponse} object has its path elements
94       * and parameters remain unchanged from the caller's. The included
95       * servlet cannot change the response status code or set headers;
96       * any attempt to make a change is ignored.
97       *
98       * <p>The request and response parameters must be either the same
99       * objects as were passed to the calling servlet's service method or be
100      * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
101      * that wrap them.
102      *
103      * @param request a {@link ServletRequest} object
104      * that contains the client's request
105      *
106      * @param response a {@link ServletResponse} object
107      * that contains the servlet's response
108      *
109      * @exception ServletException if the included resource throws this exception
110      *
111      * @exception IOException if the included resource throws this exception
112      */
113     public void include(ServletRequest request, ServletResponse response)
114             throws ServletException, IOException;
115 }
116 
117 
118 
119 
120 
121 
122 
123