javax.servlet
Interface RequestDispatcher

public abstract interface RequestDispatcher

Defines an object that receives requests from the client and sends them to any resource (such as a servlet, HTML file, or JSP file) on the server. The servlet engine creates the RequestDispatcher object, which is used as a wrapper around a server resource located at a particular path.

This interface is intended to wrap servlets, but a servlet engine can create RequestDispatcher objects to wrap any type of resource.

Version:

$Version$

Author:

Various

See Also:

ServletContext.getRequestDispatcher(java.lang.String)

Method Summary

void	forward(ServletRequest request, ServletResponse response) Forwards a ServletRequest object from this servlet to a resource (servlet, JSP file, or HTML file) on the server.
void	include(ServletRequest request, ServletResponse response) Includes the content a resource (servlet, JSP page, HTML file) on the Web server generates in the response this servlet sends to another servlet.

Method Detail

forward

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

Forwards a ServletRequest object from this servlet to a resource (servlet, JSP file, or HTML file) on the server. You can use this method when one servlet does preliminary processing of a request and lets another resource generate the response.

The ServletRequest object has its path and other parameters adjusted to be relative to the path of the target resource.

You cannot use forward if the target resource has already returned a ServletOutputStream or PrintWriter object to the servlet. In that situation, forward throws an IllegalStateException.

Parameters:

request - a ServletRequest object that represents the request the client makes of the servlet

response - a ServletResponse object that represents the response the servlet returns to the client

Throws:

ServletException - if the target resource is a servlet and throws an exception

java.io.IOException - if an input or output exception occurs

java.lang.IllegalStateException - if the target resource returned a ServletOutputStream or PrintWriter object before this method was called

include

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

Includes the content a resource (servlet, JSP page, HTML file) on the Web server generates in the response this servlet sends to another servlet. In essence, this method enables programmatic server-side includes.

The ServletResponse object passed to this servlet has the caller's request path. The response object only has access to this servlet's ServletOutputStream and PrintWriter objects.

A servlet that calls include cannot set response headers. If the servlet that calls include also calls methods that set headers, include is not guaranteed to work.

Parameters:

request - a ServletRequest object that contains the client's request

response - a ServletResponse object that contains the servlet's response

Throws:

ServletException - if the target servlet throws a servlet exception

java.io.IOException - if the servlet has already obtained a ServletOutputStream or print writer object from the ServletResponse object