javax.servlet
Interface RequestDispatcher

All Known Implementing Classes:
RequestDispatcherImpl

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.


Field Summary
static java.lang.String ERROR_EXCEPTION
           
static java.lang.String ERROR_EXCEPTION_TYPE
           
static java.lang.String ERROR_MESSAGE
           
static java.lang.String ERROR_REQUEST_URI
           
static java.lang.String ERROR_SERVLET_NAME
           
static java.lang.String ERROR_STATUS_CODE
           
static java.lang.String FORWARD_CONTEXT_PATH
           
static java.lang.String FORWARD_PATH_INFO
           
static java.lang.String FORWARD_QUERY_STRING
           
static java.lang.String FORWARD_REQUEST_URI
           
static java.lang.String FORWARD_SERVLET_PATH
           
static java.lang.String INCLUDE_CONTEXT_PATH
           
static java.lang.String INCLUDE_PATH_INFO
           
static java.lang.String INCLUDE_QUERY_STRING
           
static java.lang.String INCLUDE_REQUEST_URI
           
static java.lang.String INCLUDE_SERVLET_PATH
           
 
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.
 

Field Detail

ERROR_MESSAGE

static final java.lang.String ERROR_MESSAGE
See Also:
Constant Field Values

ERROR_EXCEPTION

static final java.lang.String ERROR_EXCEPTION
See Also:
Constant Field Values

ERROR_EXCEPTION_TYPE

static final java.lang.String ERROR_EXCEPTION_TYPE
See Also:
Constant Field Values

ERROR_REQUEST_URI

static final java.lang.String ERROR_REQUEST_URI
See Also:
Constant Field Values

ERROR_SERVLET_NAME

static final java.lang.String ERROR_SERVLET_NAME
See Also:
Constant Field Values

ERROR_STATUS_CODE

static final java.lang.String ERROR_STATUS_CODE
See Also:
Constant Field Values

FORWARD_CONTEXT_PATH

static final java.lang.String FORWARD_CONTEXT_PATH
See Also:
Constant Field Values

FORWARD_PATH_INFO

static final java.lang.String FORWARD_PATH_INFO
See Also:
Constant Field Values

FORWARD_QUERY_STRING

static final java.lang.String FORWARD_QUERY_STRING
See Also:
Constant Field Values

FORWARD_REQUEST_URI

static final java.lang.String FORWARD_REQUEST_URI
See Also:
Constant Field Values

FORWARD_SERVLET_PATH

static final java.lang.String FORWARD_SERVLET_PATH
See Also:
Constant Field Values

INCLUDE_CONTEXT_PATH

static final java.lang.String INCLUDE_CONTEXT_PATH
See Also:
Constant Field Values

INCLUDE_PATH_INFO

static final java.lang.String INCLUDE_PATH_INFO
See Also:
Constant Field Values

INCLUDE_QUERY_STRING

static final java.lang.String INCLUDE_QUERY_STRING
See Also:
Constant Field Values

INCLUDE_REQUEST_URI

static final java.lang.String INCLUDE_REQUEST_URI
See Also:
Constant Field Values

INCLUDE_SERVLET_PATH

static final java.lang.String INCLUDE_SERVLET_PATH
See Also:
Constant Field Values
Method Detail

forward

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
Throws:
ServletException
java.io.IOException

include

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
Throws:
ServletException
java.io.IOException