1 2 3 /* 4 * The contents of this file are subject to the terms 5 * of the Common Development and Distribution License 6 * (the "License"). You may not use this file except 7 * in compliance with the License. 8 * 9 * You can obtain a copy of the license at 10 * glassfish/bootstrap/legal/CDDLv1.0.txt or 11 * https://glassfish.dev.java.net/public/CDDLv1.0.html. 12 * See the License for the specific language governing 13 * permissions and limitations under the License. 14 * 15 * When distributing Covered Code, include this CDDL 16 * HEADER in each file and include the License file at 17 * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable, 18 * add the following below this CDDL HEADER, with the 19 * fields enclosed by brackets "[]" replaced with your 20 * own identifying information: Portions Copyright [yyyy] 21 * [name of copyright owner] 22 * 23 * Copyright 2005 Sun Microsystems, Inc. All rights reserved. 24 * 25 * Portions Copyright Apache Software Foundation. 26 */ 27 28 29 package javax.servlet; 30 31 import java.io.IOException; 32 33 34 /** 35 * Defines an object that receives requests from the client 36 * and sends them to any resource (such as a servlet, 37 * HTML file, or JSP file) on the server. The servlet 38 * container creates the <code>RequestDispatcher</code> object, 39 * which is used as a wrapper around a server resource located 40 * at a particular path or given by a particular name. 41 * 42 * <p>This interface is intended to wrap servlets, 43 * but a servlet container can create <code>RequestDispatcher</code> 44 * objects to wrap any type of resource. 45 * 46 * @author Various 47 * 48 * @see ServletContext#getRequestDispatcher(java.lang.String) 49 * @see ServletContext#getNamedDispatcher(java.lang.String) 50 * @see ServletRequest#getRequestDispatcher(java.lang.String) 51 * 52 */ 53 54 public interface RequestDispatcher { 55 56 57 58 59 60 /** 61 * Forwards a request from 62 * a servlet to another resource (servlet, JSP file, or 63 * HTML file) on the server. This method allows 64 * one servlet to do preliminary processing of 65 * a request and another resource to generate 66 * the response. 67 * 68 * <p>For a <code>RequestDispatcher</code> obtained via 69 * <code>getRequestDispatcher()</code>, the <code>ServletRequest</code> 70 * object has its path elements and parameters adjusted to match 71 * the path of the target resource. 72 * 73 * <p><code>forward</code> should be called before the response has been 74 * committed to the client (before response body output has been flushed). 75 * If the response already has been committed, this method throws 76 * an <code>IllegalStateException</code>. 77 * Uncommitted output in the response buffer is automatically cleared 78 * before the forward. 79 * 80 * <p>The request and response parameters must be either the same 81 * objects as were passed to the calling servlet's service method or be 82 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes 83 * that wrap them. 84 * 85 * 86 * @param request a {@link ServletRequest} object 87 * that represents the request the client 88 * makes of the servlet 89 * 90 * @param response a {@link ServletResponse} object 91 * that represents the response the servlet 92 * returns to the client 93 * 94 * @exception ServletException if the target resource throws this exception 95 * 96 * @exception IOException if the target resource throws this exception 97 * 98 * @exception IllegalStateException if the response was already committed 99 * 100 */ 101 102 public void forward(ServletRequest request, ServletResponse response) 103 throws ServletException, IOException; 104 105 106 107 108 /** 109 * 110 * Includes the content of a resource (servlet, JSP page, 111 * HTML file) in the response. In essence, this method enables 112 * programmatic server-side includes. 113 * 114 * <p>The {@link ServletResponse} object has its path elements 115 * and parameters remain unchanged from the caller's. The included 116 * servlet cannot change the response status code or set headers; 117 * any attempt to make a change is ignored. 118 * 119 * <p>The request and response parameters must be either the same 120 * objects as were passed to the calling servlet's service method or be 121 * subclasses of the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} classes 122 * that wrap them. 123 * 124 * 125 * 126 * @param request a {@link ServletRequest} object 127 * that contains the client's request 128 * 129 * @param response a {@link ServletResponse} object 130 * that contains the servlet's response 131 * 132 * @exception ServletException if the included resource throws this exception 133 * 134 * @exception IOException if the included resource throws this exception 135 * 136 * 137 */ 138 139 public void include(ServletRequest request, ServletResponse response) 140 throws ServletException, IOException; 141 } 142 143 144 145 146 147 148 149