Recipe 19.8 Using Filters with RequestDispatcher Objects

Problem

You want to apply a filter to a servlet whose output is included in another servlet.

Solution

Use the javax.servlet.RequestDispatcher object to include the servlet's output. Configure the filter in web.xml with a dispatcher element containing the content "INCLUDE" (servlet API v2.4 and above only!).

Discussion

The servlet API v2.4 introduced a new twist for working with RequestDispatchers . Using the filter-mapping element in the deployment descriptor, you can specify that the filter applies to a servlet that is part of a RequestDispatcher include or forward action.

Example 19-11 shows a web.xml configuration for a filter.

Example 19-11. Applying a filter to a servlet using a RequestDispatcher

 <?xml version="1.0" encoding="ISO-8859-1"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee"   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=     "http://java.sun.com/xml/ns/j2ee        http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">  <filter>     <filter-name>LogFilter</filter-name>     <filter-class>com.jspservletcookbook.LogFilter</filter-class> </filter> <filter-mapping>     <filter-name>LogFilter</filter-name>     <url-pattern>/requestheaders</url-pattern>     <dispatcher>REQUEST</dispatcher>     <dispatcher>INCLUDE</dispatcher> </filter-mapping>

The dispatcher elements in the example configuration specify that the LogFilter applies to requests for the servlet path /requestheader s, as well as to any RequestDispatchers that include the output of the servlet path /requestheaders .

Similarly, if you want to initiate a filter when you are using a RequestDispatcher to forward a request to another component, use the FORWARD value with the dispatcher element, as in:

 <filter-mapping>     <filter-name>LogFilter</filter-name>     <url-pattern>/requestheaders</url-pattern>     <dispatcher>REQUEST</dispatcher>     <dispatcher>FORWARD</dispatcher> </filter-mapping>

Example 19-12 shows a servlet's doGet method that creates a RequestDispatcher specifying the path /requestheaders . This code includes the servlet output represented by that path. Because of Example 19-11s configuration in web.xml , however, the web container applies the LogFilter before the servlet mapped to the /requestheaders path is executed.

Example 19-12. A servlet includes another servlet's output, triggering a filter

 public void doGet(HttpServletRequest request, HttpServletResponse response)     throws ServletException, java.io.IOException {          /* The output of the servlet at path "/requestheaders" will        be included in this servlet's output, but first the request        will pass through the LogFilter before it is sent to the        "/requestheaders" servlet */  RequestDispatcher dispatch = request.getRequestDispatcher(         "/requestheaders");     dispatch.include(request,response);  }

Figure 19-2 illustrates the process of filters and RequestDispatchers .

Figure 19-2. A log filter intervenes between a servlet, including another servlet's output

In Figure 19-2, a web client requests the servlet at path /home/servlet1 , with /home representing the context path. The servlet1 component uses a RequestDispatcher to include the output of servlet2. Based on a filter-mapping element in web.xml , any requests for servlet2 involving a RequestDispatcher include action must first pass through the log filter. This filter is configured with a filter element in web.xml with the name "LogFilter" (Figure 19-2 does not show this configuration; see Example 19-11).

This type of RequestDispatcher set-up is only supported by Servlet API v2.4 and above.