Download FAQ History |  | API Search Feedback

> ## Filtering Requests and Responses

> A filter is an object that can transform the header and content (or both) of a request or response. Filters differ from Web components in that they usually do not themselves create a response. Instead, a filter provides functionality that can be "attached" to any kind of Web resource. As a consequence, a filter should not have any dependencies on a Web resource for which it is acting as a filter, so that it can be composable with more than one type of Web resource. The main tasks that a filter can perform are as follows:

> - Query the request and act accordingly.
> - Block the request and response pair from passing any further.
> - Modify the request headers and data. You do this by providing a customized version of the request.
> - Modify the response headers and data. You do this by providing a customized version of the response.
> - Interact with external resources.

> Applications of filters include authentication, logging, image conversion, data compression, encryption, tokenizing streams, and XML transformations, and so on.

> You can configure a Web resource to be filtered by a chain of zero, one, or more filters in a specific order. This chain is specified when the Web application containing the component is deployed and is instantiated when a Web container loads the component.

> In summary, the tasks involved in using filters include

> - Programming the filter
> - Programming customized requests and responses
> - Specifying the filter chain for each Web resource

> ### Programming Filters

> The filtering API is defined by the `Filter`, `FilterChain`, and `FilterConfig` interfaces in the `javax.servlet` package. You define a filter by implementing the `Filter` interface. The most important method in this interface is the `doFilter` method, which is passed request, response, and filter chain objects. This method can perform the following actions:

> - Examine the request headers.
> - Customize the request object if it wishes to modify request headers or data.
> - Customize the response object if it wishes to modify response headers or data.
> - Invoke the next entity in the filter chain. If the current filter is the last filter in the chain that ends with the target Web component or static resource, the next entity is the resource at the end of the chain; otherwise, it is the next filter that was configured in the WAR. It invokes the next entity by calling the `doFilter` method on the chain object (passing in the request and response it was called with, or the wrapped versions it may have created). Alternatively, it can choose to block the request by not making the call to invoke the next entity. In the latter case, the filter is responsible for filling out the response.
> - Examine response headers after it has invoked the next filter in the chain
> - Throw an exception to indicate an error in processing

> In addition to `doFilter`, you must implement the `init` and `destroy` methods. The `init` method is called by the container when the filter is instantiated. If you wish to pass initialization parameters to the filter, you retrieve them from the `FilterConfig` object passed to `init`.

> The Duke's Bookstore application uses the filters `HitCounterFilter` and `OrderFilter` to increment and log the value of a counter when the entry and receipt servlets are accessed.

> In the `doFilter` method, both filters retrieve the servlet context from the filter configuration object so that they can access the counters stored as context attributes. After the filters have completed application-specific processing, they invoke `doFilter` on the filter chain object passed into the original `doFilter` method. The elided code is discussed in the next section.

>     public final class HitCounterFilter implements Filter {
>       private FilterConfig filterConfig = null;

>       public void init(FilterConfig filterConfig)
>         throws ServletException {
>         this.filterConfig = filterConfig;
>       }
>       public void destroy() {
>         this.filterConfig = null;
>       }
>       public void doFilter(ServletRequest request,
>         ServletResponse response, FilterChain chain)
>         throws IOException, ServletException {
>         if (filterConfig == null)
>           return;
>         StringWriter sw = new StringWriter();
>         PrintWriter writer = new PrintWriter(sw);
>         Counter counter = (Counter)filterConfig.
>           getServletContext().
>           getAttribute("hitCounter");
>         writer.println();
>         writer.println("===============");
>         writer.println("The number of hits is: " +
>           counter.incCounter());
>         writer.println("===============");
>         // Log the resulting string
>         writer.flush();
>         System.out.println(sw.getBuffer().toString());
>         ...
>         chain.doFilter(request, wrapper);
>         ...
>       }
>     }

> ### Programming Customized Requests and Responses

> There are many ways for a filter to modify a request or response. For example, a filter could add an attribute to the request or insert data in the response. In the Duke's Bookstore example, `HitCounterFilter` inserts the value of the counter into the response.

> A filter that modifies a response must usually capture the response before it is returned to the client. The way to do this is to pass a stand-in stream to the servlet that generates the response. The stand-in stream prevents the servlet from closing the original response stream when it completes and allows the filter to modify the servlet's response.

> To pass this stand-in stream to the servlet, the filter creates a response wrapper that overrides the `getWriter` or `getOutputStream` method to return this stand-in stream. The wrapper is passed to the `doFilter` method of the filter chain. Wrapper methods default to calling through to the wrapped request or response object. This approach follows the well-known Wrapper or Decorator pattern described in Design Patterns, Elements of Reusable Object-Oriented Software (Addison-Wesley, 1995). The following sections describe how the hit counter filter described earlier and other types of filters use wrappers.

> To override request methods, you wrap the request in an object that extends `ServletRequestWrapper` or `HttpServletRequestWrapper`. To override response methods, you wrap the response in an object that extends `ServletResponseWrapper` or `HttpServletResponseWrapper`.

> `HitCounterFilter` wraps the response in a `CharResponseWrapper`. The wrapped response is passed to the next object in the filter chain, which is `BookStoreServlet`. `BookStoreServlet` writes its response into the stream created by `CharResponseWrapper`. When `chain.doFilter` returns, `HitCounterFilter` retrieves the servlet's response from `PrintWriter` and writes it to a buffer. The filter inserts the value of the counter into the buffer, resets the content length header of the response, and finally writes the contents of the buffer to the response stream.

>     PrintWriter out = response.getWriter();
>     CharResponseWrapper wrapper = new CharResponseWrapper(
>       (HttpServletResponse)response);
>     chain.doFilter(request, wrapper);
>     CharArrayWriter caw = new CharArrayWriter();
>     caw.write(wrapper.toString().substring(0,
>       wrapper.toString().indexOf("</body>")-1));
>     caw.write("<p>\n<center>" +
>       messages.getString("Visitor") + "<font color='red'>" +
>       counter.getCounter() + "</font></center>");
>     caw.write("\n</body></html>");
>     response.setContentLength(caw.toString().getBytes().length);
>     out.write(caw.toString());
>     out.close();

>     public class CharResponseWrapper extends
>       HttpServletResponseWrapper {
>       private CharArrayWriter output;
>       public String toString() {
>         return output.toString();
>       }
>       public CharResponseWrapper(HttpServletResponse response){
>         super(response);
>         output = new CharArrayWriter();
>       }
>       public PrintWriter getWriter(){
>         return new PrintWriter(output);
>       }
>     }

> Figure 15-3 shows the entry page for Duke's Bookstore with the hit counter.

> Figure 15-3 Duke's Bookstore

> ### Specifying Filter Mappings

> A Web container uses filter mappings to decide how to apply filters to Web resources. A filter mapping matches a filter to a Web component by name or to Web resources by URL pattern. The filters are invoked in the order in which filter mappings appear in the filter mapping list of a WAR. You specify a filter mapping list for a WAR by coding them directly in the Web application deployment descriptor as follows

> - Declare the filter. This element creates a name for the filter and declares the filter's implementation class and initialization parameters.
> - Map the filter to a Web resource by name or by URL pattern.
> - Constrain how the filter will be applied to requests by choosing one of the enumerated dispatcher options:
> - `REQUEST`-Only when the request come directly from the client.
> - `FORWARD`-Only when the request has been forwarded to a component (see Transferring Control to Another Web Component).
> - `INCLUDE`-Only when the request is being processed by a component that has been included (see Including Other Resources in the Response).
> - `ERROR`-Only when the request is being processed with the error page mechanism (see Handling Errors).

> You can direct the filter to be applied in any combination of the preceding situations by including multiple `dispatcher` elements. If no elements are specified, the default option is `REQUEST`.

> The following elements show how to specify the Duke's Bookstore hit counter and order filters:

>     <filter>
>       <filter-name>OrderFilter</filter-name>
>       <filter-class>filters.OrderFilter</filter-class>
>     </filter>
>     <filter>
>       <filter-name>HitCounterFilter</filter-name>
>       <filter-class>filters.HitCounterFilter</filter-class>
>     </filter>

> The `filter-mapping` element maps the order filter to the `/receipt` URL. The mapping could also have specified the servlet `ReceiptServlet`. Note that the `filter`, `filter-mapping`, `servlet`, and `servlet-mapping` elements must appear in the Web application deployment descriptor in that order.

>     <filter-mapping>
>         <filter-name>OrderFilter</filter-name>
>         <url-pattern>/receipt</url-pattern>
>     </filter-mapping>
>     <filter-mapping>
>         <filter-name>HitCounterFilter</filter-name>
>         <url-pattern>/enter</url-pattern>
>     </filter-mapping>

> If you want to log every request to a Web application, you would map the hit counter filter to the URL pattern `/*`. Table 15-6 summarizes the filter definition and mapping list for the Duke's Bookstore application. The filters are matched by servlet name and each filter chain contains only one filter.

> Table 15-6 Duke's Bookstore Filter Definition and Mapping List
> Filter | Class | Servlet
> --- | --- | ---
> `HitCounterFilter` | `filters.HitCounterFilter` | `BookStoreServlet`
> `OrderFilter` | `filters.OrderFilter` | `ReceiptServlet`

> You can map a filter to one or more Web resources and you can map more than one filter to a Web resource. This is illustrated in Figure 15-4, where filter F1 is mapped to servlets S1, S2, and S3, filter F2 is mapped to servlet S2, and filter F3 is mapped to servlets S1 and S2.

> Figure 15-4 Filter to Servlet Mapping

> Recall that a filter chain is one of the objects passed to the `doFilter` method of a filter. This chain is formed indirectly via filter mappings. The order of the filters in the chain is the same as the order in which filter mappings appear in the Web application deployment descriptor.

> When a filter is mapped to servlet S1, the Web container invokes the `doFilter` method of F1. The `doFilter` method of each filter in S1's filter chain is invoked by the preceding filter in the chain via the `chain.doFilter` method. Since S1's filter chain contains filters F1 and F3, F1's call to `chain.doFilter` invokes the `doFilter` method of filter F3. When F3's `doFilter` method completes, control returns to F1's `doFilter` method.

Download FAQ History |  | API Search Feedback

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.