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