
Index
RedirectFilter
Index
Setup & Config
Setup examples
Downloads
License

RedirectFilter

Set up

The RedirectFilter is configured through its filter declaration in the web.xml file. Here is the standard declaration for a servlet:

  <filter> 
     <filter-name>MyFirstRedirectFilter</filter-name> 
     <filter-class>net.pieroxy.tools.j2ee.RedirectFilter</filter-class> 
  </filter>
  
  <filter-mapping> 
     <filter-name>MyFirstRedirectFilter</filter-name>  
     <url-pattern>/</url-pattern>
  </filter-mapping>

Note: The above declaration does nothing. The filter will let pass through every call without doing nothing since no redirection has been configured. The RedirectFilter configuration takes place in the init-params right in the filter declaration. The param-name is a regular expression that should match some URL. The param-value is the string that should replace the regular expression when encountered. For example:

  <filter> 
     <filter-name>redirect1</filter-name> 
     <filter-class>net.pieroxy.tools.j2ee.RedirectFilter</filter-class> 
     <init-param> 
        <param-name>http://mydomain\.com/</param-name> 
        <param-value>http://www.mydomain.com/</param-value> 
     </init-param> 
  </filter>

The above servlet will answer all calls to http://mydomain.com/anything/here by a 301 http redirection to http://www.mydomain.com/anything/here. And that's all it does, redirect. Note that the '\' before the '.'. Since the parameter-name is a regular expression, special characters must be escaped. If not escaped, the RedirectFilter would also redirect http://mydomain_com/ if such a host name is defined.

This example illustrates how to use RedirectFilter to redirect an entire website. This should be used as the ROOT webapp of a host linked to the mydomain.com name.

Note that if the servlet is called on a URL that doesn't match any of the patterns (param-names), it will let the request go through to your web application.

Here is another example that shows how to redirect just some URLs of a website:

  <filter> 
     <filter-name>MyFirstRedirectFilter</filter-name> 
     <filter-class>net.pieroxy.tools.j2ee.RedirectFilter</filter-class> 
     <init-param> 
        <param-name>/my/first/page\.html</param-name> 
        <param-value>/my/target/page.html</param-value> 
     </init-param> 
  </filter> 
  
  <filter-mapping> 
     <filter-name>MyFirstRedirectFilter</filter-name>  
     <url-pattern>/my/first/page.html</url-pattern>
  </filter-mapping>

The above example will redirect all calls to /my/first/page.html with a 301 http status redirecting to /my/target/page.html. Note that the pattern is a substring, so a call to /another/path/my/first/page.html could be redirected to /another/path/my/target/page.html. Hopefully, the RedirectFilter will not be called here because the filter-mapping doesn't match this second path.

Configuration

There are a few parameters that can be tweaked, for example the status code used to redirect (http 301 or 302) and wether or not the query string should be included in the redirection. All param-names starting with RedirectFilterConfig: will be ignored in the redirections list and will be treated as a config parameter. Below is an example of configuration:

  <filter> 
     <filter-name>MyFirstRedirectFilter</filter-name> 
     <filter-class>net.pieroxy.tools.j2ee.RedirectFilter</filter-class> 
     <init-param> 
        <param-name>/my/first/page\.html</param-name> 
        <param-value>/my/target/page.html</param-value> 
     </init-param> 
     <init-param> 
        <param-name>RedirectFilterConfig:status</param-name> 
        <param-value>302</param-value> 
     </init-param> 
     <init-param> 
        <param-name>RedirectFilterConfig:addQueryString</param-name> 
        <param-value>true</param-value> 
     </init-param> 
  </filter> 
  
  <filter-mapping> 
     <filter-name>MyFirstRedirectFilter</filter-name>  
     <url-pattern>/my/first/page.html</url-pattern>
  </filter-mapping>

Note that by default, the http status code used is 301 (permanent redirect) and the query string will not be passed through.

list of configurable options

status

possible values	301, 302, *
default value	301
meaning	301 means a permanent HTTP redirection, 302 means a temporary HTTP redirection.

*: While the primary goal of RedirectFilter is to redirect, it can be used to block some parts of a website. Any HTTP status code can be configured. However, RedirectFilter will never answer a body, just a http header so it makes little sense to configure it to serve a HTTP 200 for example. A http 404 or 403 is perfectly acceptable.

Note on the http status codes: 301 or 302 will have the same effects on the end user: they will be redirected. However, robots (programs) browsing your website may have a different behavior depending on which status code is used. You should use the one that is closest to your needs.

addQueryString

possible values	true, false
default value	false
meaning	false means that the query string is lost in the redirection; true means that the query string is carried in the redirection.

verboseLevel

possible values	0,1,2
default value	0
meaning	0=no output, 1=Outputs every redirection performed, 2=Output every call.

Note that the logs are output through System.out.

patternType

possible values	substring, regexp
default value	regexp
meaning	regexp will consider param-names as regular expressions. substring will consider the param-names as simple sub strings.

Note: The substring matcher may be up to twice as fast. On a regular dual core processor (Centrino Duo, T5600 @ 1.83GHz), the RedirectFilter is able to filter 200 000 queries per second, with 6 regexps configured. Performance should never become an issue on a regular "casual" usage. For more intensive usage, performance testing should be part of the plan.