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 /requestheaders, 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.