Object Computing, Inc.
Java News Brief
May 2001 Issue
Sun Authorized Java Center

Headlines:
Java Technical Insight of the Month
     Filters in the Servlet 2.3 API
Visit The Java News Brief Archive for past issues of the JNB.
OCI Educational Services


Java Technical Insight of the Month
Filters in the Servlet 2.3 API
by Dan Troesser, Senior Software Engineer, Object Computing, Inc. (OCI)

Java Servlets have been around for several years now and have proven themselves in delivering robust and portable web applications.  Since their introduction, the Java web development front hasn't slowed down.  Along came JSPs introducing an easier way to generate HTML.  XML and XSLT entered the picture making it easier to separate presentation from data, among many other benefits.  The Servlet API hasn't stood still either.  The Servlet 2.3 API, now a proposed final draft, will be released soon and will bring with it another powerful feature called filters.

Filters allow declarative pre-processing and post-processing of requests and responses handled by web resources.  Web resources in this case are considered servlets, JSPs, static content (HTML files), and even other filters in the web application.  Declarative means the Filter can be applied in the deployment descriptor of the web application rather than programmatically in a Servlet or JSP.

Filters are very similar to the concept of Servlet chaining introduced and implemented by some Servlet containers years ago.  They could also be applied declaratively usually in a web administration tool.  However, declarative Servlet chaining was not in the specification and thus was not implemented widely or in any standard way by the containers.  In the interest of portability, their use somewhat disappeared.

Many Possibilities

The capabilities of filters are many.  They are capable of intercepting requests to one or more web resources, performing some action, modifying the request, and passing it on to the next Filter in the chain or to the requested resource.  They can also block the request.  Once the request has been served by the requested resource, the same or other filters can intercept the response, perform some action, modify the response, and pass it on.  They can also block the response.

Some of the potential uses of filters include:

Classes Involved

Several classes and interfaces have been added to the Servlet API to help with filtering. They include:

Image Removal Filter Example

This example demonstrates a Filter that removes images from HTML content.  It replaces the images with hyperlinks to the images.  This might be useful for users who have low bandwidth (e.g. a 56K modem).  It demonstrates interception of the response, forwarding to the next resource in the chain, and interception and selective transformation of the responses content.

Let's suppose we have a web application that is used to create and display a photo album.  Below is a screen shot of the unfiltered photo album.

Unfiltered Photo Album

We want to filter the photo album for our low-bandwidth users so the following is produced:

Filtered Photo Album

We start by creating a class that implements the Filter interface. 
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.xml.transform.*;
import javax.xml.transform.stream.*;

public class ImageRemovalFilter implements Filter {

    // Could also use an initialization parameter for this.
    private static final String STYLESHEET = "removeImages.xslt";
    private FilterConfig filterConfig;

    public void doFilter(ServletRequest req, ServletResponse res,
           FilterChain chain) throws IOException, ServletException {
        boolean doRemove = req.getParameter("removeImages") != null;
        HttpServletResponse httpRes;
        if (res instanceof HttpServletResponse) {
            httpRes = (HttpServletResponse) res;
        } else {
            throw new ServletException("ImageRemovalFilter only accepts"
                + " HTTP requests");
        }
        OutputCaptureResponseWrapper resWrapper
            = new OutputCaptureResponseWrapper(httpRes);
        chain.doFilter(req, resWrapper);
        resWrapper.flushBuffer();
        String contentType = resWrapper.getContentType();
        if (doRemove && contentType != null 
            && contentType.indexOf("html") != -1) {
            String initialXHTML = resWrapper.getOutputAsString();
            String finalXHTML = removeImages(initialXHTML);
            res.setContentLength(finalXHTML.length());
            res.getWriter().print(finalXHTML);
        } else {
            // Let all other content types pass through.
            res.getOutputStream().write(resWrapper.getOutputAsByteArray());
        }
    }

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

    // Required by Filter interface.  Just providing empty implementation.
    public void destroy() { }

    /**
     * Performs an XSLT transformation using JAXP 1.1 to replace img elements
     * in the input XHTML document with links (<a href="...).
     */
    private String removeImages(String initialXHTML)
            throws ServletException {
        StringWriter finalXHTMLWriter = new StringWriter();
        TransformerFactory factory = TransformerFactory.newInstance();
        ServletContext context = filterConfig.getServletContext();
        try {
            InputStream xsltStream = context.getResourceAsStream(STYLESHEET);
            StreamSource xsltSource = new StreamSource(xsltStream);
            StringReader xmlSourceReader
                = new StringReader(initialXHTML);
            StreamSource xmlSource = new StreamSource(xmlSourceReader);
            StreamResult xmlResult = new StreamResult(finalXHTMLWriter);
            Transformer transformer = factory.newTransformer(xsltSource);
            transformer.transform(xmlSource, xmlResult);
        } catch (Exception ex) {
            throw new ServletException("Error performing transformation to remove"
                + " images", ex);
        }
        return finalXHTMLWriter.toString();
    }
}
When the Filter is loaded, the init() method is called.  We use the opportunity to save a reference to the FilterConfig object. We will need this later to retrieve an instance of the ServletContext object so we can gain access to the XSLT stylesheet, which will perform the content transformation. Click here to view or download the stylesheet.  The stylesheet filename is defined as a static final String.  It could also have been specified as a Filter initialization parameter in the web application's deployment descriptor (web.xml).  If that were the case, the init() method would have been a good place to retrieve the value using getInitParameter() on the FilterConfig object.  Once loaded and the init() method is called, the Filter can handle requests. Each request that should be filtered calls the doFilter() method.

The doFilter() method first checks the request object for a removeImages parameter.  If it exists, we know we should attempt to remove the images from the response.  Perhaps a better alternative than requiring a request parameter would be to compare the user against a list of the users or remote hosts who have low bandwidth.  A list of known low bandwidth remote hosts could be specified as initialization parameters for the Filter.  The getRemoteHost() or getRemoteAddr() method on the request can be used to return the client's hostname or IP address and then compared against the list.  Rather than maintaining a list of remote hosts, one could develop a user preferences Servlet or Filter.  The user could choose a "remove images" option in their preferences.  When the photo album is viewed, the Filter could identify the user, perhaps by calling getRemoteUser() on the request, and check the user's preferences to determine whether to replace the images with links.  These options would provide a more declarative solution. This example uses a request parameter for simplicity.

We only want to handle HTTP requests, so the next step checks whether the request coming in is an HTTP request by checking the type of the response object passed.  The existence of an HttpFilter interface would be nice in this situation.  It seems messy to have to check this.  Within this check we must also explicitly cast the response to an HttpServletResponse type. This is necessary because our custom built response wrapper, OutputCaptureResponseWrapper, extends HttpServletResponseWrapper, which wraps an HttpServletResponse. We then create an instance of OutputCaptureResponseWrapper so that it can be passed along in place of the regular response object.  Calling doFilter() on the FilterChain object passed to us in our doFilter() method continues the chain so that the next Filter or target resource will be called.  The target resource in this case is a Servlet called ViewerServlet that emulates producing dynamic content.  Click here to view or download ViewerServlet.java.  For simplicity, it just forwards the request to a static HTML file (photos.html) containing our photo album.  Click here to view the HTML for photos.html.  Note that for the XSL transformation to take place, it must take well-formed XHTML as input.  If you look at the HTML file you will notice the elements are properly nested, properly terminated, and the attributes are quoted. This shouldn't be a problem though.  We all should be producing well-formed XHTML now, right?

The OutputCaptureResponseWrapper class uses a custom ServletOutputStream called ByteArrayServletOutputStream.  These two classes allow the capture and retrieval of the response output.  This is another area where the Servlet API/Specification needs to mature.  It seems unnecessary we should have to build our own classes just to capture the output.  On the plus side, the classes are not too complex and once created, can be reused.  Click the links below to view or download the code for these two classes.
Now that we've called the doFilter() method and have captured the content produced by the resources farther down the chain with our custom response object, we can retrieve that content and modify it.  The buffer is flushed to make sure we get all the output when we retrieve it as a String or byte array.  We only want to remove images from HTML content, so we make sure the content type is "text/html".  Otherwise, we just let the content pass through.  To pass the content along, modified or unmodified, just use the Writer or OutputStream of the original response object.  If it is not known whether the content is text, make sure to use the OutputStream and pass the data as bytes, not as a String.

It isn't always necessary to use wrapper request or response objects in filters.  The Filter developer may want to simply retrieve request or response values, block further execution, or return completely different content, such as a login or error page.  In these cases, using wrapper classes isn't necessary.  Wrapper classes are used when the Filter must modify what the request or response returns.  For example, in our OutputCaptureResponseWrapper, we needed to override the methods related to the OutputStream and Writer used for outputting content.  Notably, the getOutputStream() and getWriter() methods returned our custom versions (which captured output), rather than the standard.  The target resource will then be using our custom OutputSream and Writer.

Deployment

The Filter is useless until we apply it to something.  That's where the deployment descriptor comes in.  The deployment descriptor (web.xml) for the image filter example is below. 
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">
<web-app>

    <filter>
        <filter-name>Image Removal Filter</filter-name>
        <filter-class>ImageRemovalFilter</filter-class>
    </filter>

    <!-- Will cause the Filter to be applied to Viewer Servlet because it
            has a matching url-pattern.  One could have instead specified the 
            Servlet directly using a servlet-name element.-->
    <filter-mapping>
        <filter-name>Image Removal Filter</filter-name>
        <url-pattern>/view/*</url-pattern>
    </filter-mapping>

    <!-- Will cause the Filter to be applied to all resources in the web
            application, including static content and JSPs.  This makes the 
            previous filter-mapping a bit redundant.-->
    <filter-mapping>
        <filter-name>Image Removal Filter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    <servlet>
        <servlet-name>Viewer Servlet</servlet-name>
        <servlet-class>ViewerServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Viewer Servlet</servlet-name>
        <url-pattern>/view/*</url-pattern>
    </servlet-mapping>

</web-app>
The <filter> element declares a Filter in the web application.  It expects <filter-name> and <filter-class> child elements that define the logical name and class of the Filter, respectively, similar to the definitions for servlets shown farther down in the file. Initialization parameters can be defined in the same way for filters as far servlets using <init-params> elements.  We also have <filter-mapping> elements that look similar to <servlet-mapping> elements.  They can contain <url-pattern> elements that define when a Filter should be called.  Filters have critical differences, however, when it comes to mapping.  For one, the <filter-mapping> element can take a <servlet-name> element instead of a <url-pattern> element.  This allows the Filter to be mapped to an individual Servlet using its logical name defined elsewhere in the deployment descriptor.  Another critical difference in mapping is realized when filters are chained together.  When chaining multiple filters, the order the mappings appear in the deployment descriptor is significant. First, the filters will be called in the order the <filter-mapping> elements appear for <url-pattern> elements that match.  Then filters will be called in the order the <filter-mapping> elements appear for matching <servlet-name> elements.

Great Potential

Improvements could be made to the API to make it more Filter developer friendly.  The addition of an HttpFilter would be nice.  It would also be nice to see more wrapper classes or a modification of the existing to make it easier to capture the output of the response for possible modification.  Until then, developers will have to develop their own classes similar to those in the example.

Despite some possible tweaking in the specification, filters have the potential to change the way web applications are designed and implemented.  Developers now have an alternative to programmatically forcing some or all requests through a single Servlet or custom JSP tag.  Once filters are created, they can be applied in the deployment descriptor to any single resource or group of resources in a web application.  Filters can also be chained together.  In this way, filters and their accompanying pre- and post-processing can be easily applied and reused among resources in a web application.  Things like logging, modification of headers, transforming of content, and validation no longer need to be coded into servlets or JSPs. This will allow web applications to become even more modular and easier to develop.

References

Java Servlet Specification 2.3 - Proposed Final Draft 2
Jakarta Tomcat Project
JAXP 1.1 Reference Implementation
XML Apache Organization

Note: The example used Jakarta Tomcat 4.0-b4-dev, JAXP 1.1, Xerces 1.3.1, and Xalan 2.0.1.

OCI Educational Services                

OCI has one of the most comprehensive OO training curricula in the country.  Clients contract group training that is either taught at the client site or at the OCI Education Center in St. Louis, MO.
 (click on course titles for online descriptions)


Java
Curriculum 		CORBA/C++
Curriculum 		Enterprise Web
Development Curriculum 		Linux
Courses

XML
Courses

Course
Catalog

Open
Enrollment
Schedule

Instructor
Bios

 
Java Curriculum
Enterprise Web Development Curriculum

Object Computing, Inc. is a Sun Authorized Java Center in St. Louis and a Member of the Object Management Group, OMG.  OCI specializes in distributed computing using object-oriented and web-enabled technologies and provides Consulting, Education, and Product Development services to clients nation-wide.  For more information contact us at 314-579-0066 (St. Louis), 480-752-0042 (Tempe) or email info@ociweb.com.

Click here for OCI CAREER OPPORTUNITIES.

The Java News Brief is a monthly newsletter.  The purpose and intent of this publication is to advance Java, provide technical value, and to announce available OCI Java services.  If you would prefer to not receive this newsletter or would like to subscribe please click here. 

Copyright © 2001.  Object Computing, Inc. All rights reserved.
Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc.  in the United States and other countries.
Object Computing, Inc. is independent of Sun Microsystems, Inc.