Java Enterprise in a Nutshell, Second Edition

Name

RequestDispatcher

Synopsis

A RequestDispatcher allows a servlet to forward a request to another resource, or to include another resource in its output. The web server is responsible for creating RequestDispatcher objects as well as properly retrieving content for them. The forward() method can be used before a servlet has returned content to the client and will cause the target of the dispatcher to serve the entire request. This is similar issuing a redirect to the client, but since the redirection occurs on the server side, the browser believes it is still at the original URL, which may have consequences for relative paths and related behavior. The include() method enables a server-side include, merging the output of the included resource with the servlet’s output stream. If the included resources is a servlet, it cannot change any response codes or headers.

public interface RequestDispatcher {
// Public Instance Methods
   public abstract void forward(ServletRequest request, 
        ServletResponse response) throws ServletExceptionIOException;  
   public abstract void include(ServletRequest request, 
        ServletResponse response) throws ServletExceptionIOException;  
}

Returned By

ServletContext.{getNamedDispatcher(), getRequestDispatcher()}, ServletRequest.getRequestDispatcher(), ServletRequestWrapper.getRequestDispatcher()