RequestDispatcher | Java Servlet Programming (Java Series)

Java Servlet Programming, 2nd Edition > A. Servlet API Quick Reference > RequestDispatcher

< BACK

CONTINUE >

RequestDispatcher

Synopsis

Interface Name: javax.servlet.RequestDispatcher

Superinterface: None

Immediate Subinterfaces: None

Implemented By: None

Availability: Servlet API 2.1 and later

Description

The interface for an object that can internally dispatch requests to any resource (such as a servlet, HTML file, or JSP file) on the server. The servlet container creates the RequestDispatcher object that is then used as a wrapper around a server resource located at a particular path or given by a particular name. This interface is intended to wrap servlets and JSP pages, but a servlet container can create RequestDispatcher objects to wrap any type of resource. The dispatching can be used to forward a request to the resource or to include the content of that resource into the current response. This class was introduced in Servlet API 2.1.

Interface Declaration

public interface RequestDispatcher {   // Methods   public abstract void forward(ServletRequest req, ServletResponse res)     throws ServletException, java.io.IOException             // New in 2.1   public abstract void include(ServletRequest req, ServletResponse res)     throws ServletException, java.io.IOException             // New in 2.1 }

Methods

forward()

public abstract void forward(ServletRequest req, ServletResponse res)     throws ServletException, IOException, IllegalStateException

Description: Forwards a request from a servlet to another resource on the server. This method allows one servlet to do preliminary processing of a request and another resource to generate the response. For a RequestDispatcher obtained via getRequestDispatcher( ), the ServletRequest object has its path elements and parameters adjusted to match the path of the target resource. This method should be called before the response has been committed to the client; if the response already has been committed, this method throws an IllegalStateException. Uncommitted output in the response buffer is automatically cleared before the forward. The request and response parameters must be the same objects as were passed to the calling servlet's service method. This method was introduced in Servlet API 2.1.

include()

public abstract void include(ServletRequest req, ServletResponse res)   throws ServletException, IOException

Description: Includes the content of a resource into the current response. The path elements and parameters of the ServletRequest remain unchanged from the caller's; if the included resource requires access to its own path elements and parameters, it may retrieve them using the server-assigned request attributes javax.servlet.include.request_uri, javax.servlet.include.context_path, javax.servlet.include.servlet_path, javax.servlet.include.path_info, and javax.servlet.include.query_string. The included servlet cannot change the response status code or set headers; any attempt to make a change is ignored. The request and response parameters must be the same objects as were passed to the calling servlet's service method. This method was introduced in Servlet API 2.1.

< BACK

CONTINUE >