SRV.8.1 Obtaining a RequestDispatcher

SRV.8.1 Obtaining a RequestDispatcher

An object implementing the RequestDispather interface may be obtained from the ServletContext via the following methods :

• getRequestDispatcher

• getNamedDispatcher

The getRequestDispatcher method takes a String argument describing a path within the scope of the ServletContext . This path must be relative to the root of the ServletContext . This path is used to look up a servlet, wrap it with a RequestDis patcher object, and return it. If no servlet can be resolved based on the given path, a RequestDispatcher is provided that simply returns the content for that path.

The getNamedDispatcher method takes a String argument indicating the name of a servlet known to the ServletContext . If a servlet is known to the ServletCon text by the given name, it is wrapped with a RequestDispatcher object and returned. If no servlet is associated with the given name, the method must return null .

To allow RequestDispatcher objects to be obtained using relative paths, paths which are not relative to the root of the ServletContext but instead are relative to the path of the current request, the following method is provided in the ServletRe quest interface:

• getRequestDispatcher

The behavior of this method is similar to the behavior of the method of the same name in the ServletContext ; however, it does not require a complete path within the context to be given as part of the argument to operate . The servlet container can use the information in the request object to transform the given relative path to a complete path. For example, in a context rooted at '/' , a request to /garden/tools.html , a request dispatcher obtained via ServletRequest.getRequestDispatcher("header.html") will behave exactly like a call to ServletContext.getRequestDispatcher("/garden/header.html") .

SRV.8.1.1 Query Strings in Request Dispatcher Paths

In the ServletContext and ServletRequest methods which allow the creation of a RequestDispatcher using path information, optional query string information may be attached to the path. For example, a developer may obtain a RequestDispatcher by using the following code:

 String path = "/raisons.jsp?orderno=5";  RequestDispatcher rd = context.getRequestDispatcher(path);  rd.include(request, response); 

The contents of the query string are added to the parameter set that the included servlet has access to. The parameters are ordered so that any parameters specified in the query string used to create the RequestDispatcher take precedence. The parameters associated with a RequestDispatcher are scoped only for the duration of the include or forward call.