javax.servlet
Interface RequestDispatcher

All Known Subinterfaces:
CauchoRequestDispatcher

public interface RequestDispatcher

The RequestDispatcher gives servlets the capabilities of SSI includes. The forwarded or included page is handled as a normal page request.


 RequestDispatcher disp;
 disp = request.getRequestDispatcher("inc.jsp?a=b");
 disp.include(request, response);
 

Servlets typically use ServletRequest.setAttribute() to communicate between included pages.

A popular architecture uses servlets to process the initial request and JSP files to format the results. That template architecture uses request attributes to communicate data from the servlet to the JSP page. disp.forward() transfers the request to the JSP file.


Method Summary
 void forward(ServletRequest request, ServletResponse response)
          Forwards the request to another page.
 void include(ServletRequest request, ServletResponse response)
          Includes the result of another page.
 

Method Detail

forward

public void forward(ServletRequest request,
                    ServletResponse response)
             throws ServletException,
                    java.io.IOException
Forwards the request to another page. Forward may not be called if data has been sent to the client. Specifically, forward calls the response.reset() method to clear the output buffer.

Query parameters are added to the original query parameters.

The new URI values are based on the RequestDispatcher URI. So getRequestURI(), getServletPath(), and getPathInfo() will reflect the request dispatcher URI.

Parameters:
request - the original request
response - the original response

include

public void include(ServletRequest request,
                    ServletResponse response)
             throws ServletException,
                    java.io.IOException
Includes the result of another page.

Query parameters are added to the original query parameters.

The included request's URI methods reflect the original URI data. So getRequestURI() will return the URI sent by the browser.

Included pages should use request.getAttribute() to get the new URI values:
getRequestURIjavax.servlet.include.request_uri
getContextPathjavax.servlet.include.context_path
getServletPathjavax.servlet.include.servlet_path
getPathInfojavax.servlet.include.path_info
getQueryStringjavax.servlet.include.query_string

Parameters:
request - the original request
response - the original response