UrlRewriteFilter 4.0.3


A clean URL scheme is very important detail for any quality Web Application. UrlRewriteFilter provides a toolkit to let you set URL patterns however you want.

See Cool URIs don't change, by World Wide Web creator Tim Berners-Lee, for excellent arguments on why URLs should be clean and usable.

With the Apache webserver there is mod_rewrite for URL manipulation.

In J2EE land the Servlet specification (by Sun) standardises the approach for dealing with Java web server programming. We have come a long way from basic Servlets, JSP's, MVC frameworks etc but Java Web Application Servers such as Tomcat are seldom used as front-line web servers, they almost always have Apache infront of them.

If you want to use an app server as a front line web server UrlRewriteFilter will enable you to manage incoming URL's in a much more flexible way than the app server usually lets you.

You can find test cases in the source distribution. UrlRewriteFilter should work on any J2EE web application server and has been tested using Cargo on the following web application servers:

The filter has been designed for maximum performance. Testing has indicated that it should only slow down a request by 0.0005 of a second under normal circumstances (depending on hardware and configuration etc.). Take a look at the source in the class org.tuckey.web.filters.urlrewrite.PerformanceTest.testLoadsOfRules() for more information.


UrlRewriteFilter is distributed under the BSD License. For more information on see opensource.org/licenses.

If you want to purchase ad-hoc support, a support contract or custom development please email sales@tuckey.co.nz.


  • 4.0.5
    • Bug fix for appending query strings breaking URL (issue 116)
  • 4.0.4
    • Changes to build process (not formally released)
  • 4.0.3
    • Minor fix for identifying versions
  • 4.0.2
    • Bug Fix for gzip filtering
  • 4.0.1 Beta
    • Rewrite of the way Encoding/Decoding is handled (issue 27)
    • Support for file existence tests via new condition type request-filename and operators isdir, isfile, isfilewithsize, notdir, notfile, notfilewithsize (issue 49)
    • Support for qsappend (issue 31)
    • New condition types requested-session-id-from-cookie, requested-session-id-from-url, requested-session-id-valid
    • Ability to conditionally GZip responses using the gzip conf element
    • Fixed bug: ":" char in url results in java.io.UnsupportedEncodingException (issue 30)
    • Fixed bug: Wildcard matcher and $ in URL causes exception (issue 71)
    • Dropped support for log4j and commons-logging. Just use slf4j instead. This removes 2 x dependencies.
  • 3.2.0
    • Added "no substitution" ability with to element eg, <to>-</to>
    • In urlrewrite.xml allow rule, class-rule and outbound-rule elements in any order
    • Fixed bug with handling of references in functions (ie, to allow this: ${replace:$1:-:+} )
    • Added slf4j logging support for logLevel (filter parameter)
    • Added function for calculating string length (eg, ${length:asdf} would return 4)
    • Added "proxy" to type, to enable requests to be proxied to another server
    • Added "context" attribute to <to> type, to enable requests to sent to other contexts (assuming app server configured to do this)
    • JDK 6+ Annotation processor
    • JDK 5 & 6+ Annotation processors included in main jar file
    • Fixed bug with decoding urls and added ability to specify 'header' type decoding
    • Added allowConfSwapViaHttp filter parameter to allow configuration swap out at runtime.
  • 3.1.0
    • Rules are now allowed to have only condition and set elements
    • Basic functions in "set", and "to" elements eg, ${trim:%1}
    • Experimental mod_rewrite style configuration
    • Bug fix: xml entites containing jndi protocol now correctly loaded
  • 3.0.4 Beta
    • Bug fix - cookie value not being set with variable replacement
  • 3.0.3 Beta
    • Bug fix - annotation processor rule sorting
    • Bug Fix - evaluation boolean result was incorrect on failed condition instance matches
  • 3.0.2 Beta
    • Rule chaining bug fixes
  • 3.0.1 Beta
    • Added "class-rule" element to enable 100% dynamic "Java Rules"
    • Added experimental UrlrewriteTestCase to help with testing (see the source)
    • Added experimental "catch" element to handle exceptions generated from "run"'s
    • Added experimental annotation (@HttpUrl, @HttpParam) processor
    • Minor Bug fixes
  • 3.0 Beta
    • Support for wildcard matching.
    • Added "match-type" attribute to rule and outbound-rule.
    • Added ability to specify charset decoding ("decodeusing" attribute to "urlrewrite" element)
    • Swapped "to" variable replacement and run processing, run processing now comes before "to" variable replacement is done. dtd it has been swapped make sure you change the reference in your conf file. Make sure element order is from, set, run, to.
    • Context addition to the url is now optional
    • Query string matching on rule is now optional (defaults to false)
      before 3.0 you would specify
      3.0 and up (unless use-query-string on urlrewrite element is set to true)
      <condition name="a">b</condition>
  • 2.6
    • fixed bug with encode on to element defaulting to incorrect boolean (change to dtd)
  • 2.5.3
    • cleaner exception handling when invoking "run" items, original exception thrown as if it were the original if it extends RuntimeException (eg, NullPointer), other exceptions wrapped in a ServletException and thrown
  • 2.5.2
    • fixed bug with encodefirst attr not being set
    • ability to specify wildcards on statusEnabledOnHosts
    • added backreferences and variables for to element value
    • logLevel init param can now include sysout:{level} ie, sysout:DEBUG for people who have trouble with context.log
  • 2.5.1
    • bug fixes, Log initialisation and null auth type condition values
  • 2.5
    • matcher changed to accept first match (not the whole string) please make sure you retest your rules (ie, previously /res/js/l.js?aaa would not match /res/js/l.js, with this release it will)
    • support for logging to log4j or commons-logging (see filter params in manual)
    • fixed bug for when request.getCookies() returns null on some containers
    • added encodefirst outbound-rule, outbound-rule now respects encode on "to".
  • 2.4
    • removed all external library dependencies to make much more deploy friendly
    • no longer uses Jakarta ORO, this should't mean any change in regular expression handling but you should test your existing rules just in case.
    • fixed problem with rediredting to "null" this will now not proceed with the request if the rule is matched (ie, chain.doFilter will not be called)
    • fixed problem with ant dependency on status page
  • 2.3 (4/2005)
    • Added new outbound-rule for rewriting hyperlinks in JSP's, improved status page, added ability to run methods when a rule is matched
  • 2.0.1 (2/2005)
    • Fixed bug with rule processing when to element doesn't exist.
  • 2.0 (1/2005)
    • Minor bug fixes, last attribute on rule now defaults to false (thanks to Vineet Kumar for his assistance).
  • 2.0-beta (12/2004)
    • Minor bug fixes, documentation improvements, ALL matches now done case insensitively by default, case sensitivity can be set (see from and condition elements).
  • 2.0-alpha (11/2004)
    • First 2.0 release, added many new condition types, many new set types.
  • 1.2 (6/2004)
    • Added set element (ability to set random attributes on request, thanks for the idea Russell), from now matches RELATIVE to context NOT root (if you are upgrading this may mean a change for you).
  • 1.1 (4/2004)
    • Ability to disable rules, Refactored to enable rewriter to be embedded, changed logging to enable log level to be set, added name and note elements to rule for documentation, ability to disable status page, ability to change status prefix, javadoc style ant task for an HTML configuration report.
  • 1.0 (3/2004)
    • General tidy up of logging, tidy up of all code, dist now includes manual, log4j and junit removed from bin release.
  • 0.9 (2/2004)
    • Fixed conf loading problem in Resin, resolved concurrency issue with Perl5Compiler and Perl5Matcher (thanks Scott Askew!)
  • 0.8 (2/2004)
    • Removed dependency on "Commons Lang", Changed DTD path (bug fix), added ability to put time fields in "condition" element, added ability to put "operators" in the "condition" element, fixed multiple rules issue (bug fix)
  • 0.7 (11/2003)
    • Improved test cases, documentation
  • 0.6 (8/2003)
    • Improved error handling, status page and condition matching
  • 0.5 (6/2003)
    • Improved configuration error handling