01: /*
02: * Copyright 1998-2000 Caucho Technology -- all rights reserved
03: *
04: * Caucho Technology forbids redistribution of any part of this software
05: * in any form, including derived works and generated binaries.
06: *
07: * This Software is provided "AS IS," without a warranty of any kind.
08: * ALL EXPRESS OR IMPLIED REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
09: * IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
10: * OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED.
11:
12: * CAUCHO TECHNOLOGY AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES
13: * SUFFERED BY LICENSEE OR ANY THIRD PARTY AS A RESULT OF USING OR
14: * DISTRIBUTING SOFTWARE. IN NO EVENT WILL CAUCHO OR ITS LICENSORS BE LIABLE
15: * FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
16: * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
17: * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
18: * INABILITY TO USE SOFTWARE, EVEN IF HE HAS BEEN ADVISED OF THE POSSIBILITY
19: * OF SUCH DAMAGES.
20: *
21: * $Id: RequestDispatcher.java,v 1.1.1.1 2004/09/11 05:06:12 cvs Exp $
22: */
23:
24: package javax.servlet;
25:
26: import java.io.IOException;
27:
28: /**
29: * The RequestDispatcher gives servlets the capabilities of SSI includes.
30: * The forwarded or included page is handled as a normal page request.
31: *
32: * <pre><code>
33: * RequestDispatcher disp;
34: * disp = request.getRequestDispatcher("inc.jsp?a=b");
35: * disp.include(request, response);
36: * </code></pre>
37: *
38: * <p>Servlets typically use <code>ServletRequest.setAttribute()</code>
39: * to communicate between included pages.
40: *
41: * <p>A popular architecture uses servlets to process the initial request
42: * and JSP files to format the results. That template architecture uses
43: * request attributes to communicate data from the servlet to the JSP page.
44: * <code>disp.forward()</code> transfers the request to the JSP file.
45: */
46: public interface RequestDispatcher {
47: /**
48: * Forwards the request to another page. Forward may not be called
49: * if data has been sent to the client. Specifically,
50: * forward calls the <code>response.reset()</code> method to clear
51: * the output buffer.
52: *
53: * <p>Query parameters are added to the original query parameters.
54: *
55: * <p>The new URI values are based on the RequestDispatcher URI.
56: * So getRequestURI(), getServletPath(), and getPathInfo() will reflect
57: * the request dispatcher URI.
58: *
59: * @param request the original request
60: * @param response the original response
61: */
62: public void forward(ServletRequest request, ServletResponse response)
63: throws ServletException, IOException;
64:
65: /**
66: * Includes the result of another page.
67: *
68: * <p>Query parameters are added to the original query parameters.
69: *
70: * <p>The included request's URI methods reflect the <em>original</em>
71: * URI data. So getRequestURI() will return the URI sent by
72: * the browser.
73: *
74: * <p>Included pages should use request.getAttribute() to get the
75: * new URI values:
76: * <table>
77: * <tr><td>getRequestURI<td>javax.servlet.include.request_uri
78: * <tr><td>getContextPath<td>javax.servlet.include.context_path
79: * <tr><td>getServletPath<td>javax.servlet.include.servlet_path
80: * <tr><td>getPathInfo<td>javax.servlet.include.path_info
81: * <tr><td>getQueryString<td>javax.servlet.include.query_string
82: * </table>
83: *
84: * @param request the original request
85: * @param response the original response
86: */
87: public void include(ServletRequest request, ServletResponse response)
88: throws ServletException, IOException;
89: }
|