001 /**
002 *
003 * Copyright 2003-2004 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 //
019 // This source code implements specifications defined by the Java
020 // Community Process. In order to remain compliant with the specification
021 // DO NOT add / change / or delete method signatures!
022 //
023
024 package javax.servlet;
025
026 import java.io.IOException;
027
028 /**
029 * Defines an object that receives requests from the client
030 * and sends them to any resource (such as a servlet,
031 * HTML file, or JSP file) on the server. The servlet
032 * container creates the <code>RequestDispatcher</code> object,
033 * which is used as a wrapper around a server resource located
034 * at a particular path or given by a particular name.
035 *
036 * <p>This interface is intended to wrap servlets,
037 * but a servlet container can create <code>RequestDispatcher</code>
038 * objects to wrap any type of resource.
039 *
040 * @see ServletContext#getRequestDispatcher(java.lang.String)
041 * @see ServletContext#getNamedDispatcher(java.lang.String)
042 * @see ServletRequest#getRequestDispatcher(java.lang.String)
043 *
044 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
045 */
046 public interface RequestDispatcher {
047 /**
048 * Forwards a request from
049 * a servlet to another resource (servlet, JSP file, or
050 * HTML file) on the server. This method allows
051 * one servlet to do preliminary processing of
052 * a request and another resource to generate
053 * the response.
054 *
055 * <p>For a <code>RequestDispatcher</code> obtained via
056 * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code>
057 * object has its path elements and parameters adjusted to match
058 * the path of the target resource.
059 *
060 * <p><code>forward</code> should be called before the response has been
061 * committed to the client (before response body output has been flushed).
062 * If the response already has been committed, this method throws
063 * an <code>IllegalStateException</code>.
064 * Uncommitted output in the response buffer is automatically cleared
065 * before the forward.
066 *
067 * <p>The request and response parameters must be either the same
068 * objects as were passed to the calling servlet's service method or be
069 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
070 * that wrap them.
071 *
072 *
073 * @param request a {@link ServletRequest} object
074 * that represents the request the client makes of the servlet
075 *
076 * @param response a {@link ServletResponse} object
077 * that represents the response the servlet returns to the client
078 *
079 * @exception ServletException if the target resource throws this exception
080 *
081 * @exception IOException if the target resource throws this exception
082 *
083 * @exception IllegalStateException if the response was already committed
084 */
085 public void forward(ServletRequest request, ServletResponse response)
086 throws ServletException, IOException;
087
088 /**
089 * Includes the content of a resource (servlet, JSP page,
090 * HTML file) in the response. In essence, this method enables
091 * programmatic server-side includes.
092 *
093 * <p>The {@link ServletResponse} object has its path elements
094 * and parameters remain unchanged from the caller's. The included
095 * servlet cannot change the response status code or set headers;
096 * any attempt to make a change is ignored.
097 *
098 * <p>The request and response parameters must be either the same
099 * 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