javax.servlet

Interface RequestDispatcher

public interface RequestDispatcher

This interface implements methods to forward a request or include output from another (active) source such as another servlet.

A servlet can get an object that implements this interface from the ServletContext by calling the getRequestDispatcher() method.

If the servlet engine can it should provide a (wrapper) object which implements this interface when a servlet calls getRequestDispatcher().

Since:

2.1

See Also:

ServletContext.getRequestDispatcher(java.lang.String)

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ERROR_EXCEPTION Name of the attribute for the exception object.
static java.lang.String	ERROR_EXCEPTION_TYPE Name of the attribute for the type of the exception object.
static java.lang.String	ERROR_MESSAGE Name of the attribute for the exception message.
static java.lang.String	ERROR_REQUEST_URI Name of the attribute for the request-URI that caused the exception.
static java.lang.String	ERROR_SERVLET_NAME Name of the attribute for the servlet name that caused the exception.
static java.lang.String	ERROR_STATUS_CODE Name of the attribute for the response status during an error.
static java.lang.String	FORWARD_CONTEXT_PATH Name of the attribute for the context path during a forward.
static java.lang.String	FORWARD_PATH_INFO Name of the attribute for the path info during a forward.
static java.lang.String	FORWARD_QUERY_STRING Name of the attribute for the query-string during a forward.
static java.lang.String	FORWARD_REQUEST_URI Name of the attribute for the request-URI during a forward.
static java.lang.String	FORWARD_SERVLET_PATH Name of the attribute for the servlet path during a forward.
static java.lang.String	INCLUDE_CONTEXT_PATH Name of the attribute for the context path during an include.
static java.lang.String	INCLUDE_PATH_INFO Name of the attribute for the path info during an include.
static java.lang.String	INCLUDE_QUERY_STRING Name of the attribute for the query-string during an include.
static java.lang.String	INCLUDE_REQUEST_URI Name of the attribute for the request-URI during an include.
static java.lang.String	INCLUDE_SERVLET_PATH Name of the attribute for the servlet path during an include.

Method Summary

Methods

Modifier and Type	Method and Description
void	forward(ServletRequest request, ServletResponse response) Forwards a ServletRequest to the resource represented by the RequestDispatcher.
void	include(ServletRequest request, ServletResponse response) Includes into the ServletResponse any output written by the resource represented by the RequestDispatcher.

Field Detail

ERROR_EXCEPTION

static final java.lang.String ERROR_EXCEPTION

Name of the attribute for the exception object.

Since:

3.0

See Also:

Constant Field Values

ERROR_EXCEPTION_TYPE

static final java.lang.String ERROR_EXCEPTION_TYPE

Name of the attribute for the type of the exception object.

Since:

3.0

See Also:

Constant Field Values

ERROR_MESSAGE

static final java.lang.String ERROR_MESSAGE

Name of the attribute for the exception message.

Since:

3.0

See Also:

Constant Field Values

ERROR_REQUEST_URI

static final java.lang.String ERROR_REQUEST_URI

Name of the attribute for the request-URI that caused the exception.

Since:

3.0

See Also:

Constant Field Values

ERROR_SERVLET_NAME

static final java.lang.String ERROR_SERVLET_NAME

Name of the attribute for the servlet name that caused the exception.

Since:

3.0

See Also:

Constant Field Values

ERROR_STATUS_CODE

static final java.lang.String ERROR_STATUS_CODE

Name of the attribute for the response status during an error.

Since:

3.0

See Also:

Constant Field Values

FORWARD_REQUEST_URI

static final java.lang.String FORWARD_REQUEST_URI

Name of the attribute for the request-URI during a forward.

Since:

3.0

See Also:

Constant Field Values

FORWARD_CONTEXT_PATH

static final java.lang.String FORWARD_CONTEXT_PATH

Name of the attribute for the context path during a forward.

Since:

3.0

See Also:

Constant Field Values

FORWARD_PATH_INFO

static final java.lang.String FORWARD_PATH_INFO

Name of the attribute for the path info during a forward.

Since:

3.0

See Also:

Constant Field Values

FORWARD_SERVLET_PATH

static final java.lang.String FORWARD_SERVLET_PATH

Name of the attribute for the servlet path during a forward.

Since:

3.0

See Also:

Constant Field Values

FORWARD_QUERY_STRING

static final java.lang.String FORWARD_QUERY_STRING

Name of the attribute for the query-string during a forward.

Since:

3.0

See Also:

Constant Field Values

INCLUDE_REQUEST_URI

static final java.lang.String INCLUDE_REQUEST_URI

Name of the attribute for the request-URI during an include.

Since:

3.0

See Also:

Constant Field Values

INCLUDE_CONTEXT_PATH

static final java.lang.String INCLUDE_CONTEXT_PATH

Name of the attribute for the context path during an include.

Since:

3.0

See Also:

Constant Field Values

INCLUDE_PATH_INFO

static final java.lang.String INCLUDE_PATH_INFO

Name of the attribute for the path info during an include.

Since:

3.0

See Also:

Constant Field Values

INCLUDE_SERVLET_PATH

static final java.lang.String INCLUDE_SERVLET_PATH

Name of the attribute for the servlet path during an include.

Since:

3.0

See Also:

Constant Field Values

INCLUDE_QUERY_STRING

static final java.lang.String INCLUDE_QUERY_STRING

Name of the attribute for the query-string during an include.

Since:

3.0

See Also:

Constant Field Values

Method Detail

forward

void forward(ServletRequest request,
           ServletResponse response)
             throws ServletException,
                    java.io.IOException

Forwards a ServletRequest to the resource represented by the RequestDispatcher.

A servlet can call this method if it has not yet requested an OutputStream or a Writer from the response.

Note that the RequestDispatcher can change the request object before handing it to the target resource depending on the string that was given to getRequestDispatcher().

Parameters:

request - the original request

response - the response to which output should be written

Throws:

ServletException - can be thrown by the target resource

java.io.IOException - if an I/O-error occurs

java.lang.IllegalStateException - if getOutputStream or getWriter has already been called on the response

Since:

2.1

include

void include(ServletRequest request,
           ServletResponse response)
             throws ServletException,
                    java.io.IOException

Includes into the ServletResponse any output written by the resource represented by the RequestDispatcher.

Note that the target resource can only use the OutputStream or Writer that the original caller uses. It can not set any headers. Also note that any sessions should be started before calling include.

The RequestDispatcher will not alter the original request before handing it to the target resource.

Parameters:

request - the original request

response - the original response

Throws:

ServletException - can be thrown by the target resource

java.io.IOException - if an I/O-error occurs

Since:

2.1