javax.servlet
Interface RequestDispatcher

public abstract interface RequestDispatcher

Defines a request dispatcher object that receives request from the client and sends them to any resource (such as a servlet, CGI script, HTML file, or JSP file) available on the server. The request dispatcher object is created by the servlet engine and serves as a wrapper around a server resource defined by a particular URL path.

The RequestDispatcher interface is defined primary to wrap servlets, but a servlet engine can create request dispatcher objects to wrap any type of resource.

Request dispatcher objects are created by the servlet engine, not by the servlet developer.

See Also:

ServletContext.getRequestDispatcher(java.lang.String)

Method Summary

void	forward(ServletRequest request, ServletResponse response) Used for forwarding a request from this servlet to another resource on the server.
void	include(ServletRequest request, ServletResponse response) Used for including the content generated by another server resource in the body of a response.

Method Detail

forward

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

Used for forwarding a request from this servlet to another resource on the server. This method is useful when one servlet does preliminary processing of a request and wants to let another object generate the response.

The request object passed to the target object will have its request URL path and other path parameters adjusted to reflect the target URL path of the target ojbect.

You cannot use this method if a ServletOutputStream object or PrintWriter object has been obtained from the response. In that case, the method throws an IllegalStateException

Parameters:

request - the client's request on the servlet

response - the client's response from the servlet

Throws:

ServletException - if a servlet exception is thrown by the target servlet

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

IllegalStateException - if the ServletOutputStream or a writer had allready been obtained from the response object

include

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

Used for including the content generated by another server resource in the body of a response. In essence, this method enables programmatic server side includes.

The request object passed to the target object will reflect the request URL path and path info of the calling request. The response object only has access to the calling servlet's ServletOutputStream object or PrintWriter object.

An included servlet cannot set headers. If the included servlet calls a method that may need to set headers (such as sessions might need to), the method is not guaranteed to work. As a servlet developer, you must ensure that any methods that might need direct access to headers are properly resolved. To ensure that a session works correctly, start the session outside of the included servlet, even if you use session tracking.

Parameters:

request - the client's request on the servlet

response - the client's response from the servlet

Throws:

ServletException - if a servlet exception is thrown by the target servlet

java.io.IOException - if the ServletOutputStream or a writer had already been obtained from the response object