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-25 06:01:51 +0200 (Mi, 25. Okt 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