Sadly, apart from being difficult to navigate, some of the information on the official ‘UrlRewriteFilter‘ website pertaining to setup and usage of the filter is also incorrect/out of date. This is really quite a shame, because ‘UrlRewriteFilter‘ is an excellent little utility and I’m quite tired of seeing people needlessly running multi-server configurations (typically Apache httpd for static content, and something like Tomcat, Resin, Jetty, etc. for dynamic content) out of a desire to use this-or-that particular module that only works with httpd or (even worse) out of the outdated and no-longer-relevant notion that servlet containers cannot efficiently serve static content. So in an effort to save ‘UrlRewriteFilter‘ from obscurity and an undeserved death at the hands of poor documentation and a shoddy distribution site, here is a complete set of instructions for getting the filter to work in your webapp.

First, you will need to ensure that the ‘UrlRewriteFilter‘ JAR file is on your web-application’s classpath. How you do this will depend upon your build process/how you are constructing your webapp(s), but long story short placing the JAR file in your webapp under ‘/WEB-INF/lib’ will do the trick, and if you’ve spent any time at all working with webapps you probably already have a preferred way of doing this. Alternately, you may want to install the JAR file in your servlet container’s ‘/lib’ folder, particularly if you are deploying multiple webapps on your server and you want to have ‘UrlRewriteFilter‘ available to any/all of them automatically.

In any case, once you have the ‘UrlRewriteFilter‘ JAR on your webapp’s classpath, the real setup can begin. Open your application’s ‘web.xml‘ file, and add the following filter configuration to your webapp:

<!-- URL rewriting -->
<filter>
    	<filter-name>UrlRewriteFilter</filter-name>
      	<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
      	<init-param>
        	<param-name>logLevel</param-name>
        	<param-value>WARN</param-value>
        </init-param>
</filter>
<filter-mapping>
    	<filter-name>UrlRewriteFilter</filter-name>
    	<url-pattern>/*</url-pattern>
</filter-mapping>

This instructs the servlet container to route every request that the server receives through the ‘UrlRewriteFilter‘. Note that although it is not discussed on the official site, that ‘logLevel‘ parameter is absolutely essential. If you omit it, the filter will fail to initialize properly and yield some very bizarre behavior.

Anyways, once your ‘web.xml‘ has been updated, the final step is to add a ‘urlrewrite.xml‘ file in the same directory as your ‘web.xml‘ file, and configure it to your liking. Here is an example ‘urlrewrite.xml‘ file with a couple basic rewrite rules:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 3.2//EN"
        "http://tuckey.org/res/dtds/urlrewrite3.2.dtd">
<urlrewrite>
    <!-- user-account activation link -->
    <rule>
    	<from>/activate/([a-f0-9]+)?(.*)</from>
     	<to>/userController?action=activateUser&amp;token=$1&amp;$2</to>
    </rule>

    <!-- default rules included with urlrewrite -->
    <rule>
        <note>
            The rule means that requests to /test/status/ will be redirected to /rewrite-status
            the url will be rewritten.
        </note>
        <from>/test/status/</from>
        <to type="redirect">%{context-path}/rewrite-status</to>
    </rule>
    <outbound-rule>
        <note>
            The outbound-rule specifies that when response.encodeURL is called (if you are using JSTL c:url)
            the url /rewrite-status will be rewritten to /test/status/.

            The above rule and this outbound-rule means that end users should never see the
            url /rewrite-status only /test/status/ both in thier location bar and in hyperlinks
            in your pages.
        </note>
        <from>/rewrite-status</from>
        <to>/test/status/</to>
    </outbound-rule> 
</urlrewrite>

This defines two rules. The first simply rewrites URL’s of the form ‘/activate/######?[params]‘ to something like ‘/userController?action=activateUser&token=######&[params]‘, and the second is the default example rule that comes with ‘UrlRewriteFilter‘ and allows you to see a basic diagnostic page by pointing your browser at ‘[your server]/test/status‘.

And there you have it. Quite simple, really, and now there’s one less reason to continue running two distinct server instances where one would do just as well.