(Originally published in JavaWorld, June 2001)

Summary
Jason Hunter looks in-depth at the new servlet filter model with an examination of several freely available filters. You'll learn how these filters work and what you can do with them. For a grand finale, Jason describes his own multipart request filter that simplifies the handling of file uploads. (3,200 words)

By Jason Hunter

In "Servlet 2.3: New Features Exposed," I introduced the changes coming in the Servlet API 2.3 and gave a short tutorial on the new servlet filter model. In this follow-on article, I'll dig deeper into servlet filters and look at several filters you can download for free on the Web. For each filter, I'll examine what it does, how it works, and where you can get it.

You can use this article in two ways: to learn about some filters that are useful out of the box, or as an aid in writing your own filters. I'll start off with some simple examples and then move on to more advanced ones. At the end, I'll show you a file upload filter that I wrote to support multipart requests.

Servlet filters
In case you aren't yet familiar, a filter is an object that can transform a request or modify a response. Filters are not servlets; they don't actually create a response. They are preprocessors of the request before it reaches a servlet, and/or postprocessors of the response leaving a servlet. As you'll see later in the examples, a filter can:

• Intercept a servlet's invocation before the servlet is called
• Examine a request before a servlet is called
• Modify the request headers and request data by providing a customized version of the request object that wraps the real request
• Modify the response headers and response data by providing a customized version of the response object that wraps the real response
• Intercept a servlet's invocation after the servlet is called

1. void init(FilterConfig config) throws ServletException: Called before the filter goes into service, and sets the filter's configuration object
2. void destroy(): Called after the filter has been taken out of service
3. void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException: Performs the actual filtering work

In its doFilter() method, each filter receives the current request and response, as well as a FilterChain containing the filters that still must be processed. In the doFilter() method, a filter may do what it wants with the request and response. (It could gather data by calling their methods, or wrap the objects to give them new behavior, as I'll discuss later.) The filter then calls chain.doFilter() to transfer control to the next filter. When that call returns, a filter can, at the end of its own doFilter() method, perform additional work on the response; for instance, it can log information about the response. If the filter wants to halt the request processing and gain full control of the response, it can intentionally not call the next filter.

Spot the slowdown
To really understand filters, you have to see them in action. The first filter we'll look at is simple but powerful; it records the duration of all requests. It's modeled loosely after the non-descriptively named ExampleFilter from the Tomcat 4.0 distribution. Here is the code:

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class TimerFilter implements Filter {

  private FilterConfig config = null;

  public void init(FilterConfig config) throws ServletException {
    this.config = config;
  }

  public void destroy() {
    config = null;
  }

  public void doFilter(ServletRequest request, ServletResponse response,
                     FilterChain chain) throws IOException, ServletException {
    long before = System.currentTimeMillis();
    chain.doFilter(request, response);
    long after = System.currentTimeMillis();

    String name = "";
    if (request instanceof HttpServletRequest) {
      name = ((HttpServletRequest)request).getRequestURI();
    }
    config.getServletContext().log(name + ": " + (after - before) + "ms");
  }
}

To use this filter, you must declare it in the web.xml deployment descriptor using the <filter> tag, as shown below:

<filter>
    <filter-name>timerFilter</filter-name>
    <filter-class>TimerFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>timerFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

2001-05-25 00:14:11 /timer/index.html: 10ms

Who's on your site, and what are they doing?
Our next filter is a clickstream filter written by the folks at OpenSymphony. This filter tracks user requests (a.k.a. clicks) and request sequences (a.k.a. clickstreams) to show a site administrator who's visiting her site and what pages each visitor has accessed so far. It's an open source library, under the LGPL license.

Inside the clickstream library you'll find a ClickstreamFilter class that captures request information, a Clickstream class that operates like a struct to hold data, and a ClickstreamLogger class that captures session and context events to glue everything together. There's also a BotChecker class that determines if a client is a robot (using simple logic, like "Did they request robots.txt?"). To view the data, the library provides a clickstreams.jsp visitor summary page and a supporting viewstream.jsp visitor detail page.

We'll look first at the ClickstreamFilter class. All these examples are slightly modified from the original, for formatting and to fix portability issues, which I'll discuss later.

import java.io.IOException;
import javax.servlet.*;
import javax.servlet.http.*;

public class ClickstreamFilter implements Filter {
  protected FilterConfig filterConfig;
  private final static String FILTER_APPLIED = "_clickstream_filter_applied";

  public void init(FilterConfig config) throws ServletException {
    this.filterConfig = filterConfig;
  }

  public void doFilter(ServletRequest request, ServletResponse response,
                   FilterChain chain) throws IOException, ServletException {
    // Ensure that filter is only applied once per request.
    if (request.getAttribute(FILTER_APPLIED) == null) {
      request.setAttribute(FILTER_APPLIED, Boolean.TRUE);
      HttpSession session = ((HttpServletRequest)request).getSession();
      Clickstream stream = (Clickstream)session.getAttribute("clickstream");
      stream.addRequest(((HttpServletRequest)request));
    }

    // pass the request on
    chain.doFilter(request, response);
  }

  public void destroy() { }
}

import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class ClickstreamLogger implements ServletContextListener,
                                          HttpSessionListener {
  Map clickstreams = new HashMap();

  public ClickstreamLogger() { }

  public void contextInitialized(ServletContextEvent sce) {
    sce.getServletContext().setAttribute("clickstreams", clickstreams);
  }

  public void contextDestroyed(ServletContextEvent sce) {
    sce.getServletContext().setAttribute("clickstreams", null);
  }

  public void sessionCreated(HttpSessionEvent hse) {
    HttpSession session = hse.getSession();
    Clickstream clickstream = new Clickstream();
    session.setAttribute("clickstream", clickstream);
    clickstreams.put(session.getId(), clickstream);
  }

  public void sessionDestroyed(HttpSessionEvent hse) {
    HttpSession session = hse.getSession();
    Clickstream stream = (Clickstream)session.getAttribute("clickstream");
    clickstreams.remove(session.getId());
  }
}

The following web.xml deployment descriptor snippet wires everything together:

    <filter>
         <filter-name>clickstreamFilter</filter-name>
         <filter-class>ClickstreamFilter</filter-class>
    </filter>

    <filter-mapping>
         <filter-name>clickstreamFilter</filter-name>
         <url-pattern>*.jsp</url-pattern>
    </filter-mapping>

    <filter-mapping>
         <filter-name>clickstreamFilter</filter-name>
         <url-pattern>*.html</url-pattern>
    </filter-mapping>

    <listener>
         <listener-class>ClickstreamLogger</listener-class>
    </listener>

The two JSP pages pull the clickstream data from the session and context objects and use an HTML interface to display the current status. The following clickstreams.jsp file shows the overall summary:

<%@ page import="java.util.*" %>
<%@ page import="Clickstream" %>
<%
Map clickstreams = (Map)application.getAttribute("clickstreams");
String showbots = "false";

if (request.getParameter("showbots") != null) {
  if (request.getParameter("showbots").equals("true"))
    showbots = "true";
  else if (request.getParameter("showbots").equals("both"))
    showbots = "both";
}
%>

<font face="Verdana" size="-1">
<h1>All Clickstreams</h1>

<a href="clickstreams.jsp?showbots=false">No Bots</a> |
<a href="clickstreams.jsp?showbots=true">All Bots</a> |
<a href="clickstreams.jsp?showbots=both">Both</a> <p>

<% if (clickstreams.keySet().size() == 0) { %>
        No clickstreams in progress
<% } %>

<%
Iterator it = clickstreams.keySet().iterator();
int count = 0;
while (it.hasNext()) {
  String key = (String)it.next();
  Clickstream stream = (Clickstream)clickstreams.get(key);

  if (showbots.equals("false") && stream.isBot()) {
    continue;
  }
  else if (showbots.equals("true") && !stream.isBot()) {
    continue;
  }
  count++;
  try {
%>

<%= count %>.
<a href="viewstream.jsp?sid=<%= key %>"><b>
<%= (stream.getHostname() != null && !stream.getHostname().equals("") ?
     stream.getHostname() : "Stream") %>
</b></a> <font size="-1">[<%= stream.getStream().size() %> reqs]</font><br>

<%
  }
  catch (Exception e) {
%>
  An error occurred - <%= e %><br>
<%
  }
}
%>

For the filter to work on Tomcat 4.0 beta5, I found I had to make some slight portability modifications. The changes I made show some common pitfalls in servlet and filter portability, so I'll list them here:

• I had to add an extra import line to the JSP files: <%@ page import="Clickstream" %>. In Java you don't have to import classes within your own package, so on servers where JSPs compile into the default package, you don't need an import line like this. But on servers like Tomcat where JSPs compile into a custom package, you have to explicitly import classes in the default package.
• I had to move the <listener> element in the web.xml file after the <filter> and <filter-mapping> elements, as required by the deployment descriptor DTD. Not all servers require elements to be in the proper order, but Tomcat does.
• I had to change the web.xml mapping from /*.html and /*.jsp to the more correct *.html and *.jsp. Some servers are forgiving of the leading slash, but Tomcat rigidly enforces the rule that prohibits that slash.
• Finally, I brought the ClickstreamFilter class up to the latest lifecycle API, changing setFilterConfig() to the newer init() and destroy() methods.

Squeeze the response
The third filter on our menu today automatically compresses the response output stream, improving bandwidth utilization and providing a great demonstration of response object wrapping. This filter is based on one written by Amy Roh from Sun who contributed it to the Tomcat 4.0 "examples" Web application. You'll find the original code under webapps/examples/WEB-INF/classes/compressionFilters. That filter is available under the standard Apache license. The example code shown here and in the WAR has been edited for clarity and simplicity.

The strategy of the CompressionFilter class is to examine the request headers to determine if the client supports compression, and if so, wrap the response object with a custom response whose getOutputStream() and getWriter() methods have been customized to utilize a compressed output stream. Using filters allows such a simple yet powerful solution.

Looking at the code, we'll start with the filter's init() method:

  public void init(FilterConfig filterConfig) {
    config = filterConfig;
    compressionThreshold = 0;
    if (filterConfig != null) {
      String str = filterConfig.getInitParameter("compressionThreshold");
      if (str != null) {
        compressionThreshold = Integer.parseInt(str);
      }
      else {
        compressionThreshold = 0;
      }
    }
  }

The doFilter() method, called when the request comes in, retrieves the Accept-Encoding header, and if the header value includes gzip, wraps the response and sets the threshold on the wrapper:

  public void doFilter(ServletRequest request, ServletResponse response,
                    FilterChain chain ) throws IOException, ServletException {
    boolean supportCompression = false;
    if (request instanceof HttpServletRequest) {
      Enumeration e = ((HttpServletRequest)request)
                           .getHeaders("Accept-Encoding");
      while (e.hasMoreElements()) {
        String name = (String)e.nextElement();
        if (name.indexOf("gzip") != -1) {
          supportCompression = true;
        }
      }
    }
    if (!supportCompression) {
      chain.doFilter(request, response);
    }
    else {
      if (response instanceof HttpServletResponse) {
        CompressionResponseWrapper wrappedResponse =
          new CompressionResponseWrapper((HttpServletResponse)response);
        wrappedResponse.setCompressionThreshold(compressionThreshold);
        chain.doFilter(request, wrappedResponse);
      }
    }
  }

public class CompressionResponseWrapper extends HttpServletResponseWrapper {

  protected ServletOutputStream stream = null;
  protected PrintWriter writer = null;
  protected int threshold = 0;
  protected HttpServletResponse origResponse = null;

  public CompressionResponseWrapper(HttpServletResponse response) {
    super(response);
    origResponse = response;
  }

  public void setCompressionThreshold(int threshold) {
    this.threshold = threshold;
  }

  public ServletOutputStream createOutputStream() throws IOException {
    return (new CompressionResponseStream(origResponse));
  }

  public ServletOutputStream getOutputStream() throws IOException {
    if (writer != null) {
      throw new IllegalStateException("getWriter() has already been " +
                                      "called for this response");
    }

    if (stream == null) {
      stream = createOutputStream();
    }
    ((CompressionResponseStream) stream).setCommit(true);
    ((CompressionResponseStream) stream).setBuffer(threshold);
    return stream;
  }

  public PrintWriter getWriter() throws IOException {
    if (writer != null) {
      return writer;
    }

    if (stream != null) {
      throw new IllegalStateException("getOutputStream() has already " +
                                      "been called for this response");
    }

    stream = createOutputStream();
    ((CompressionResponseStream) stream).setCommit(true);
    ((CompressionResponseStream) stream).setBuffer(threshold);
    writer = new PrintWriter(stream);
    return writer;
  }
}

The Tomcat "examples" Web application comes preconfigured with the compression filter enabled with an example servlet set up. The example servlet responds to the /CompressionTest URL (make sure to prepend the /examples context path). With the WAR file I've made available, you can access the test servlet at /servlet/compressionTest (again, remember to prepend the appropriate context path). You can use the following web.xml snippet to configure the test.

<filter>
    <filter-name>compressionFilter</filter-name>
    <filter-class>CompressionFilter</filter-class>
    <init-param>
      <param-name>compressionThreshold</param-name>
      <param-value>10</param-value>
    </init-param>
</filter>

<filter-mapping>
    <filter-name>compressionFilter</filter-name>
    <servlet-name>compressionTest</servlet-name>
</filter-mapping>

<servlet>
  <servlet-name>
    compressionTest
  </servlet-name>
  <servlet-class>
    CompressionTestServlet
  </servlet-class>
</servlet>

File upload filter
The final filter we'll look at handles multipart/form-data POST requests, the type of request that can contain file uploads. Each multipart/form-data POST request contains any number of parameters and files, using a special format not natively understood by servlets. Servlet developers have historically used third-party classes to handle the uploads, such as the MultipartRequest and MultipartParser classes found in my own com.oreilly.servlet package. Here we see a new approach using a MultipartFilter to make the handling of such requests easier. The filter builds on the parsers in the com.oreilly.servlet package and has been integrated into the package. (See Resources.)

The MultipartFilter works by watching incoming requests and when it detects a file upload request (with the content type multipart/form-data), the filter wraps the request object with a special request wrapper that knows how to parse the special content type format. A servlet receiving the special request wrapper has seamless access to the multipart parameters through the standard getParameter() methods, because the wrapper has redefined the behavior of those methods. The servlet can also handle uploaded files by casting the request to the wrapper type and using the additional getFile() methods on the wrapper.

Here is the code for the filter:

package com.oreilly.servlet;

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class MultipartFilter implements Filter {

  private FilterConfig config = null;
  private String dir = null;

  public void init(FilterConfig config) throws ServletException {
    this.config = config;

    // Determine the upload directory.  First look for an uploadDir filter
    // init parameter.  Then look for the context tempdir.
    dir = config.getInitParameter("uploadDir");
    if (dir == null) {
      File tempdir = (File) config.getServletContext()
                  .getAttribute("javax.servlet.context.tempdir");
      if (tempdir != null) {
        dir = tempdir.toString();
      }
      else {
        throw new ServletException(
          "MultipartFilter: No upload directory found: set an uploadDir " +
          "init parameter or ensure the javax.servlet.context.tempdir " +
          "directory is valid");
      }
    }
  }

  public void destroy() {
    config = null;
  }

  public void doFilter(ServletRequest request, ServletResponse response,
                     FilterChain chain) throws IOException, ServletException {
    HttpServletRequest req = (HttpServletRequest) request;
    String type = req.getHeader("Content-Type");

    // If this is not a multipart/form-data request continue
    if (type == null || !type.startsWith("multipart/form-data")) {
      chain.doFilter(request, response);
    }
    else {
      MultipartWrapper multi = new MultipartWrapper(req, dir);
      chain.doFilter(multi, response);
    }
  }
}

The doFilter() method examines the request content type, and should it be a multipart/form-data request, wraps the request with a MultipartWrapper. The wrapper code looks like this:

package com.oreilly.servlet;

import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class MultipartWrapper extends HttpServletRequestWrapper {

  MultipartRequest mreq = null;

  public MultipartWrapper(HttpServletRequest req, String dir)
                                     throws IOException {
    super(req);
    mreq = new MultipartRequest(req, dir);
  }

  // Methods to replace HSR methods
  public Enumeration getParameterNames() {
    return mreq.getParameterNames();
  }
  public String getParameter(String name) {
    return mreq.getParameter(name);
  }
  public String[] getParameterValues(String name) {
    return mreq.getParameterValues(name);
  }
  public Map getParameterMap() {
    Map map = new HashMap();
    Enumeration enum = getParameterNames();
    while (enum.hasMoreElements()) {
      String name = (String) enum.nextElement();
      map.put(name, mreq.getParameterValues(name));
    }
    return map;
  }

  // Methods only in MultipartRequest
  public Enumeration getFileNames() {
    return mreq.getFileNames();
  }
  public String getFilesystemName(String name) {
    return mreq.getFilesystemName(name);
  }
  public String getContentType(String name) {
    return mreq.getContentType(name);
  }
  public File getFile(String name) {
    return mreq.getFile(name);
  }
}

The web.xml deployment descriptor adds the filter like this:

<filter>
    <filter-name>multipartFilter</filter-name>
    <filter-class>com.oreilly.servlet.MultipartFilter</filter-class>
    <!--
    <init-param>
      <param-name>uploadDir</param-name>
      <param-value>/tmp</param-value>
    </init-param>
    -->
</filter>

<filter-mapping>
    <filter-name>multipartFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<servlet>
    <servlet-name>
        uploadTest
    </servlet-name>
    <servlet-class>
        UploadTest
    </servlet-class>
</servlet>

<servlet-mapping>
    <servlet-name>
        uploadTest
    </servlet-name>
    <url-pattern>
        /uploadTest
    </url-pattern>
</servlet-mapping>

import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;

import com.oreilly.servlet.*;

public class UploadTest extends HttpServlet {

  public void doPost(HttpServletRequest req, HttpServletResponse res)
                                throws ServletException, IOException {
    res.setContentType("text/html");
    PrintWriter out = res.getWriter();

    out.println("<HTML>");
    out.println("<HEAD><TITLE>UploadTest</TITLE></HEAD>");
    out.println("<BODY>");
    out.println("<H1>UploadTest</H1>");

    // Parameters can now be read the same way for both
    // application/x-www-form-urlencoded and multipart/form-data requests!

    out.println("<H3>Request Parameters:</H3><PRE>");
    Enumeration enum = req.getParameterNames();
    while (enum.hasMoreElements()) {
      String name = (String) enum.nextElement();
      String values[] = req.getParameterValues(name);
      if (values != null) {
        for (int i = 0; i < values.length; i++) {
          out.println(name + " (" + i + "): " + values[i]);
        }
      }
    }
    out.println("</PRE>");

    // Files can be read if the request class is MultipartWrapper
    // Init params to MultipartWrapper control the upload handling

    if (req instanceof MultipartWrapper) {
      try {
        // Cast the request to a MultipartWrapper
        MultipartWrapper multi = (MultipartWrapper) req;

        // Show which files we received
        out.println("<H3>Files:</H3>");
        out.println("<PRE>");
        Enumeration files = multi.getFileNames();
        while (files.hasMoreElements()) {
          String name = (String)files.nextElement();
          String filename = multi.getFilesystemName(name);
          String type = multi.getContentType(name);
          File f = multi.getFile(name);
          out.println("name: " + name);
          out.println("filename: " + filename);
          out.println("type: " + type);
          if (f != null) {
            out.println("length: " + f.length());
          }
          out.println();
        }
        out.println("</PRE>");
      }
      catch (Exception e) {
        out.println("<PRE>");
        e.printStackTrace(out);
        out.println("</PRE>");
      }
    }

    out.println("</BODY></HTML>");
  }
}

An example HTML form to drive this servlet is shown here:

<FORM ACTION="uploadTest" ENCTYPE="multipart/form-data" METHOD=POST>
What is your name? <INPUT TYPE=TEXT NAME=submitter> <BR>
What is your age? <INPUT TYPE=TEXT NAME=age> <BR>
Which file do you want to upload? <INPUT TYPE=FILE NAME=file1>
<BR>
Any other file to upload? <INPUT TYPE=FILE NAME=file2> <BR>
<INPUT TYPE=SUBMIT>
</FORM>

UploadTest
Request Parameters:
submitter (0): Jason
age (0): 28

Files:
name: file1
filename: 4008b21.tif
type: application/octet-stream
length: 39396

name: file2
filename: null
type: null

Filter power
Servlet filters provide a powerful ability to control request processing and response generation, providing new functionality to servlets without large amounts of servlet coding. I hope these filters have shown you some of what is possible to do with filters, and taught you some tricks about how to make the most effective use of the new filter mechanism.

My thanks to the authors of these filters and to the people who suggested useful filters to write about: Amy Roh, Criag McClanahan, Serge Knystautas, and the folks at OpenSymphony.

About the author
Jason Hunter is a senior technologist with CollabNet, a company that provides tools and services for collaborative software development based on open source concepts. He is author of Java Servlet Programming, 2nd Edition (O'Reilly, April 2001), publisher of Servlets.com, and contributor to Apache Tomcat (starting on the project when it was still Sun internal). He is also a member of the expert groups responsible for Servlet/JSP and JAXP API development, and holds a seat on the JCP Executive Committee overseeing the Java platform, as a representative of the Apache Software Foundation. Most recently he co-created the open source JDOM library to enable optimized Java and XML integration.

Resources
Download the WAR files from:
• http://www.servlets.com/soapbox/filters/timer.war
• http://www.servlets.com/soapbox/filters/clickstream.war
• http://www.servlets.com/soapbox/filters/compress.war
• http://www.servlets.com/soapbox/filters/multipart.war
• Apache Tomcat, the open source servlet reference implementation:
  http://jakarta.apache.org
  
• OpenSymphony's Website:
  http://www.opensymphony.com/
  
• Information on Jason's new book Java Servlet Programming, 2nd Edition (O'Reilly, April 2001; ISBN: 0596000405):
  http://www.servlets.com/book
  
• The com.oreilly.servlet package with file upload abilities:
  http://www.servlets.com/cos
  
• Official home page for servlets:
  http://java.sun.com/products/servlet
  
• More Servlet API articles by Jason Hunter:
  http://www.servlets.com/soapbox/
  
• Jason's new pet project:
  http://www.jdom.org