home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 September / PCWorld_2000-09_cd.bin / Komunik / sambar / _setup.1 / javaeng.jar / javax / servlet / RequestDispatcher.java < prev    next >
Text File  |  2000-04-03  |  4KB  |  99 lines
  1. /*
  2.  * RequestDispatcher.java -- Interface to forward requests or include responses
  3.  *
  4.  * Copyright (c) 1998, 1999 by Free Software Foundation, Inc.
  5.  * Written by Paul Siegmann (pauls@euronet.nl)
  6.  *
  7.  * This program is free software; you can redistribute it and/or modify
  8.  * it under the terms of the GNU Library General Public License as published
  9.  * by the Free Software Foundation, version 2. (see COPYING.LIB)
  10.  *
  11.  * This program is distributed in the hope that it will be useful, but
  12.  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with this program; if not, write to the Free Software Foundation
  18.  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307 USA
  19.  */
  20.  
  21. package javax.servlet;
  22.  
  23. import java.io.IOException;
  24.  
  25. /**
  26.  * This interface implements methods to forward a request or include
  27.  * output from another (active) source such as another servlet.
  28.  * <p>
  29.  * A servlet can get an object that implements this interface from
  30.  * the <code>ServletContext</code> by calling the
  31.  * <code>getRequestDispatcher()</code> method.
  32.  * <p>
  33.  * If the servlet engine can it should provide a (wrapper) object which
  34.  * implements this interface when a servlet calls
  35.  * <code>getRequestDispatcher()</code>.
  36.  *
  37.  * @see javax.servlet.ServletContext#getRequestDispatcher(java.lang.String)
  38.  * 
  39. #ifdef SERVLET_2_0
  40.  * @version Servlet API 2.0 
  41. #endif
  42. #ifdef SERVLET_2_1
  43.  * @version Servlet API 2.1
  44. #endif
  45. #ifdef SERVLET_2_2
  46.  * @version Servlet API 2.2
  47. #endif
  48.  * @since Servlet API 2.1
  49.  * @author Paul Siegmann (pauls@euronet.nl)
  50.  */
  51. public interface RequestDispatcher {
  52.     /**
  53.      * Forwards a <code>ServletRequest</code> to the resource represented by the
  54.      * <code>RequestDispatcher</code>.
  55.      * <p>
  56.      * A servlet can call this method if it has not yet requested an
  57.      * <code>OutputStream</code> or a <code>Writer</code> from the
  58.      * <code>response</code>.
  59.      * <p>
  60.      * Note that the <code>RequestDispatcher</code> can change the
  61.      * <code>request</code> object before handing it to the target resource
  62.      * depending on the string that was given to
  63.      * <code>getRequestDispatcher()</code>.
  64.      *
  65.      * @since Servlet API 2.1
  66.      *
  67.      * @param request the original request
  68.      * @param response the response to which output should be written
  69.      * @exception ServletException can be thrown by the target resource
  70.      * @exception IOException if an I/O-error occurs
  71.      * @exception IllegalStateException if <code>getOutputStream</code> or <code>getWriter</code> has already been called on the <code>response</code>
  72.      */
  73.     void forward(ServletRequest request,
  74.                 ServletResponse response)
  75.                 throws ServletException, IOException;
  76.     /**
  77.      * Includes into the <code>ServletResponse</code> any output written by the
  78.      * resource represented by the <code>RequestDispatcher</code>.
  79.      * <p>
  80.      * Note that the target resource can only use the <code>OutputStream</code>
  81.      * or <code>Writer</code> that the original caller uses. It can not set any
  82.      * headers. Also note that any sessions should be started before calling
  83.      * include.
  84.      * <p>
  85.      * The RequestDispatcher will not alter the original <code>request</code>
  86.      * before handing it to the target resource.
  87.      *
  88.      * @since Servlet API 2.1
  89.      *
  90.      * @param request the original request
  91.      * @param response the original response
  92.      * @exception ServletException can be thrown by the target resource
  93.      * @exception IOException if an I/O-error occurs
  94.      */
  95.     void include(ServletRequest request,
  96.                 ServletResponse response)
  97.                 throws ServletException, IOException;
  98. }
  99.