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