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