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 //
021 // This source code implements specifications defined by the Java
022 // Community Process. In order to remain compliant with the specification
023 // DO NOT add / change / or delete method signatures!
024 //
025
026 package javax.servlet;
027
028 import java.io.IOException;
029
030 /**
031 * Defines an object that receives requests from the client
032 * and sends them to any resource (such as a servlet,
033 * HTML file, or JSP file) on the server. The servlet
034 * container creates the <code>RequestDispatcher</code> object,
035 * which is used as a wrapper around a server resource located
036 * at a particular path or given by a particular name.
037 *
038 * <p>This interface is intended to wrap servlets,
039 * but a servlet container can create <code>RequestDispatcher</code>
040 * objects to wrap any type of resource.
041 *
042 * @see ServletContext#getRequestDispatcher(java.lang.String)
043 * @see ServletContext#getNamedDispatcher(java.lang.String)
044 * @see ServletRequest#getRequestDispatcher(java.lang.String)
045 *
046 * @version $Rev: 467553 $ $Date: 2006-10-24 21:01:51 -0700 (Tue, 24 Oct 2006) $
047 */
048 public interface RequestDispatcher {
049 /**
050 * Forwards a request from
051 * a servlet to another resource (servlet, JSP file, or
052 * HTML file) on the server. This method allows
053 * one servlet to do preliminary processing of
054 * a request and another resource to generate
055 * the response.
056 *
057 * <p>For a <code>RequestDispatcher</code> obtained via
058 * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code>
059 * object has its path elements and parameters adjusted to match
060 * the path of the target resource.
061 *
062 * <p><code>forward</code> should be called before the response has been
063 * committed to the client (before response body output has been flushed).
064 * If the response already has been committed, this method throws
065 * an <code>IllegalStateException</code>.
066 * Uncommitted output in the response buffer is automatically cleared
067 * before the forward.
068 *
069 * <p>The request and response parameters must be either the same
070 * objects as were passed to the calling servlet's service method or be
071 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes
072 * that wrap them.
073 *
074 *
075 * @param request a {@link ServletRequest} object
076 * that represents the request the client makes of the servlet
077 *
078 * @param response a {@link ServletResponse} object
079 * that represents the response the servlet returns to the client
080 *
081 * @exception ServletException if the target resource throws this exception
082 *
083 * @exception IOException if the target resource throws this exception
084 *
085 * @exception IllegalStateException if the response was already committed
086 */
087 public void forward(ServletRequest request, ServletResponse response)
088 throws ServletException, IOException;
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 * @param request a {@link ServletRequest} object
106 * that contains the client's request
107 *
108 * @param response a {@link ServletResponse} object
109 * that contains the servlet's response
110 *
111 * @exception ServletException if the included resource throws this exception
112 *
113 * @exception IOException if the included resource throws this exception
114 */
115 public void include(ServletRequest request, ServletResponse response)
116 throws ServletException, IOException;
117 }
118
119
120
121
122
123
124
125