The following post was contributed by Adam Roth, a Senior Software Architect here at iApps:
Here’s a nice little utility that can be found on a once difficult to navigate but now very much improved website. In case it’s not immediately apparent what I’m referring to, I’m talking about the ‘UrlRewriteFilter‘ featured near the top of the page. This handy Filter implementation allows you to configure mod_rewrite style URL rewriting rules for your J2EE webapp. You can also use this direct link to download ‘UrlRewriteFilter‘ version 3.2.
Sadly some of the information on the official ‘UrlRewriteFilter‘ website pertaining to setup and usage of the filter is incorrect/out of date. This is 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 notion that servlet containers cannot efficiently serve static content. So in an effort to save ‘UrlRewriteFilter‘ from obscurity, 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:
[xml]<!– URL rewriting –>
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 essential. If you omit it, the filter will fail to initialize properly and will 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]<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 3.2//EN"
<!– user-account activation link –>
<!– default rule included with urlrewrite –>
The rule means that requests to /test/status/ will be redirected to /rewrite-status
the url will be rewritten.
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‘.
That’s about it, and now maybe there’s one less reason to continue running two distinct server instances where one would do just as well.