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