UrlRewriteFilter 2.6 - Manual

Examples - Manual
Install - Filter Parameters - Configuration - Testing - Performance - Ant Task

For commercial support contact sales@tuckey.co.nz. Community support is avaliable at UrlRewrite on StackOverflow.

Read examples of usage and a sample of the ant task report. If you have feedback, or conf you want to share with the world email me.

Install

1. Download the zip (or tar.gz) and extract it into your context's directory ie, so that urlrewrite.xml goes into the WEB-INF directory.
2. Add the following to your WEB-INF/web.xml (add it near the top above your servlet mappings (if you have any)): (see filter parameters for more options)

   
               <filter>
               <filter-name>UrlRewriteFilter</filter-name>
               <filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
               </filter>
               <filter-mapping>
               <filter-name>UrlRewriteFilter</filter-name>
               <url-pattern>/*</url-pattern>
               </filter-mapping>
           

3. Add your own configuration to the WEB-INF/urlrewrite.xml that was created.
4. Restart the context.

You can visit http://127.0.0.1:8080/rewrite-status (or whatever the address of your local webapp and context) to see output (note: this page is only viewable from localhost).

Filter Parameters

There are a few advanced filter parameters for enabling conf file reloading etc. There are self-explanatory.

    <filter>
    <filter-name>UrlRewriteFilter</filter-name>
    <filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>

    <!-- set the amount of seconds the conf file will be checked for reload
    can be a valid integer (0 denotes check every time,
          empty/not set denotes no reload check) -->
    <init-param>
    <param-name>confReloadCheckInterval</param-name>
    <param-value>60</param-value>
    </init-param>

    <!-- sets up log level (will be logged to context log)
    can be: TRACE, DEBUG, INFO (default), WARN, ERROR, FATAL, log4j, commons, sysout:{level} (ie, sysout:DEBUG)
          if you are having trouble using normal levels use sysout:DEBUG -->
    <init-param>
    <param-name>logLevel</param-name>
    <param-value>DEBUG</param-value>
    </init-param>

    <!-- you can disable status page if desired
    can be: true, false (default true) -->
    <init-param>
    <param-name>statusEnabled</param-name>
    <param-value>true</param-value>
    </init-param>

        <!-- you can change status path so that it does not
          conflict with your installed apps (note, defaults
          to /rewrite-status) note, must start with / -->
    <init-param>
            <param-name>statusPath</param-name>
            <param-value>/status</param-value>
    </init-param>

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

Note, setting logLevel to log4j or commons will cause the built in loging to call either log4j or commons-logging as if they were the logging framework, obviously you will need to have the jar for log4j or commons-logging in your classpath.

Configuration File WEB-INF/urlrewrite.xml

Configuration is done via a simple XML file that lives in your WEB-INF folder. It should be named urlrewrite.xml. It may be helpful to read the UrlRewriteFilter DTD (Document Type Definition). Please also make sure you look at the examples. A simple configuration file looks like:

    <?xml version="1.0" encoding="utf-8"?>

    <!DOCTYPE urlrewrite
    PUBLIC "-//tuckey.org//DTD UrlRewrite 2.6//EN"
    "http://www.tuckey.org/res/dtds/urlrewrite2.6.dtd">

    <urlrewrite>

    <rule>
    <from>^/some/olddir/(.*)$</from>
    <to type="redirect">/very/newdir/$1</to>
    </rule>

    </urlrewrite>

The urlrewrite.xml file must have a root element called "urlrewrite" and must contain at least one "rule" element.

A "rule" must contain a "from" and a "to", and can have zero or more "condition" elements and zero or more and/or "set" elements.

When a "rule" is processed against an incoming request, all the "condition" elements must be met, then the "from" will be applied to the request URL and the final URL generated by applying the "to" to the "from" pattern. So long as the rule has matched then the "set" will be run.

Traps for young players:

• when you want to put an "&" in a rule you must enter it as the XML entity "&"
• for simplicity you might want to start all from's with a ^ and end them with a $.
  In regular expressions ^ specifies the start of the string and $ specifies the end.
  ie, a request for /my/url/path will NOT match <from>^/url/$</from> but it will match <from>/url/</from>
• If using <outbound-rule> remember all urls in your code must be encoded e.g. <a href="<%= response.encodeURL("/some/olddir/b.jsp") %>">my link</a>
• Regular expressions are complex and a bit trick at times. read Regular expression syntax for Java.

When executing a rule the filter will (very simplified) do something like this psuedo code:

    Pattern.compile(<from> element);
    pattern.matcher(each request url);
    matcher.replaceAll(<to> element);
    if ( <condition> elements match && pattern matched ) {
    execute <run> elements (if any)
    perform <to> element (if any)
    }

<rule> element

Zero or more. The basis of a rule.

In the following example requests for /world/usa/nyc will be transparently forwarded to /world.jsp?country=usa&city=nyc

    <rule enabled="true">
       <from>^/world/([a-z]+)/([a-z]+)$</from>
       <to>/world.jsp?country=$1&amp;city=$2</to>
    </rule>

<outbound-rule> element

Zero or more. This is very similar to a normal rule but it is used for rewriting urls that go through response.encodeURL().

May contain "run", "from", "to" and "set" element(s) also. Example:

    <outbound-rule>
    <from>^/world.jsp?country=([a-z]+)&amp;city=([a-z]+)$</from>
    <to>/world/$1/$2</to>
    </outbound-rule>

Using the example above JSP's with the code
<a href="<%= response.encodeURL("/world.jsp?country=usa&amp;city=nyc") %>">nyc</a>
will output
<a href="/world/usa/nyc">nyc</a>

Note, If you are using JSTL (ie, <c:url) this will work also.

<name> element

An optional element used for documenting the name of the rule. This can be used with rule and outbound-rule. See ant task.

    <rule>
    <name>World Rule</name>
    <from>^/world/([a-z]+)/([a-z]+)$</from>
    <to>/world.jsp?country=$1&amp;city=$2</to>
    </rule>

<note> element

A simple optional element used for documentation of the rule. This can be used with rule and outbound-rule. See ant task.

    <rule>
    <name>World Rule</name>
    <note>
        Cleanly redirect world requests to JSP,
        a country and city must be specified.
        </note>
    <from>^/world/([a-z]+)/([a-z]+)$</from>
    <to>/world.jsp?country=$1&amp;city=$2</to>
    </rule>

<condition> element

An element that lets you choose conditions for the rule. Note, all conditions must be met for the rule to be run (unless "next" is set to "or" obvoiusly).

Value can be any Regular Expression (Perl5 style).

Examples:

    <condition name="user-agent" operator="notequal">Mozilla/[1-4]</condition>

    <condition type="user-in-role" operator="notequal">bigboss</condition>

    <condition name="host" operator="notequal">www.example.com</condition>

    <condition type="method" next="or">PROPFIND</condition>
    <condition type="method">PUT</condition>

<from> element

You must always have exactly one from for each rule or outbound-rule. Value can be a regular expression in the Perl5 style. Note, from url's are relative to the context.

Example:

    <from>^/world/([a-z]+)$</from>

<to> element

Value can be a regular replacement expression in the Perl5 style.

Note, "to" can be null ie, <to>null</to>, this will mean that the request will go no further if the rule is matched (ie, this filter will not call chain.doFilter).

    <to>/world.jsp?country=$1</to>

To elements can contain backreferences and variables.

Backreferences

    %N

Provides access to the grouped parts (parentheses!) of the pattern from the last matched Condition in the current rule. N must be less than 10 and greater than 0.

Variables

    %{VARIABLE-NAME}

Any valid condition type can be used as a variable name. ie, '%{port}' will be translated to '80', '%{year}' to '2005', '%{cookie:myCookie}' would be translated to 'myCookieValue' (assuming the user had a cookie named myCookie with the value myCookieValue).

Valid types are and condition type, see condition for a full description.

<set> element

Allows you to set varous things if the rule is matched.

In the following example a request attribute "client" will be set to "AvantGo" or "Samsung SCH-6100", this can be fetched in a servlet or JSP using request.getAttribute("client").

    <rule>
    <condition name="user-agent">Mozilla/3\.0 (compatible; AvantGo .*)</from>
    <from>.*</from>
    <set name="client">AvantGo</set>
    </rule>
    <rule>
    <condition name="user-agent">UP\.Browser/3.*SC03 .* </from>
    <from>.*</from>
    <set name="client">Samsung SCH-6100</set>
    </rule>

<run> element

Allows you to run a method on an object when a rule and it's conditions are matched.

When the rule in the following example is matched, WorldServlet.goGet(HttpServletRequest, HttpServletResponse) will be invoked, the request will then be forwarded to /world-presentation.jsp.

    <rule>
    <from>^/world/[a-z]+/[a-z]+$</from>
    <run class="com.blah.web.WorldServlet" method="doGet" />
    <to>/world-presentation.jsp</to>
    </rule>

Note, you can specify init-param's the same way you would for a servlet.

    <run class="com.blah.web.MyServlet" method="doGet">
    <init-param>
    <param-name>someParamName</param-name>
    <param-value>10</param-value>
    </init-param>
    </run>

If the method being called throws an Exception the original exception will be re-thrown as if it were the original if it extends RuntimeException (eg, NullPointer), other exceptions are wrapped in a ServletException and thrown so your container can handle them.

Testing

Test cases have been written for most of the code. You can find them in the source distribution. UrlRewriteFilter has been tested using Cactus on the following web application servers:

• Jakarta Tomcat 4 & 5
• Caucho Resin 3
• Orion 2
• Jboss 3

If you have run the test cases on another application server please let me know.

Performance

UrlRewriteFilter has been written 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 UrlRewriterTest.testLoadsOfRules() for more information.

Ant Task

An Ant task has been written to allow validate the conf file and generation of documentation. You can view a sample.

Paste the following into your build.xml file, then change the dest and conf to point to the correct places. Note, the urlrewrite jar file will need to be in your classpath.

    <target name="urlrewrite-doc" depends="compile"
    description="UrlRewriteFilter validation and documenting">

    <taskdef
    name="urlrewritedoc"
    classname="org.tuckey.web.filters.urlrewrite.UrlRewriteDocTask" />
    <urlrewritedoc
    conf="${build.home}/WEB-INF/urlrewrite.xml"
    dest="urlrewrite-conf-overview.html" />
    </target>

Copyright 2007 Paul Tuckey