URLRewriteFilter

rewrite

The open-source Routing ↑↓ and /url/{rewriting} solution for Servlet, Java Web Frameworks, and Java EE / Jakarta EE

Get Started, Rewrite how you think about Servlets (3 simple steps)

Learn more, jump right into the configuration manual, or follow the quick-start below.
It is recommended but not required to remove other URL-rewriting tools from your application before using Rewrite and/or PrettyFaces. If you choose to leave them in place, weird things may happen to you, be warned.

Come join us on in #ocpsoftour channel on irc.freenode.net. Additionally, you are welcome to attend the dev meeting, every [[Calendar|Monday at 1pm EST]]. Also, please join the discussion on our dev email list.


1. Include Rewrite in your Project

The first step to installing is to add the required Maven dependencies to your pom.xml file. If you are not using Maven, you may also download the Rewrite distribution from the Maven central repository and include rewrite-servlet.jar in your project – a list of all available versions can be found here.

Add Rewrite to your maven pom.xmlOr download a ZIP
<!-- Jakarta EE 10+ -->
<dependency>
   <groupId>org.ocpsoft.rewrite</groupId>
   <artifactId>rewrite-servlet</artifactId>
   <version>10.0.1.Final</version>
</dependency>

<!-- Jakarta EE 9 -->
<dependency>
   <groupId>org.ocpsoft.rewrite</groupId>
   <artifactId>rewrite-servlet</artifactId>
   <version>9.0.1.Final</version>
</dependency>

<!-- Jakarta EE 8 -->
<dependency>
   <groupId>org.ocpsoft.rewrite</groupId>
   <artifactId>rewrite-servlet</artifactId>
   <version>8.0.1.Final</version>
</dependency>

<!-- Java EE <= 7 -->
<dependency>
   <groupId>org.ocpsoft.rewrite</groupId>
   <artifactId>rewrite-servlet</artifactId>
   <version>3.5.2.Final</version>
</dependency>

<!-- To use snapshots, you must also use the Sonatype Snapshots respository -->
<repository>
   <id>sonatype-snapshots</id>
   <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
</repository>

2. Implement a ConfigurationProvider

Add one class, a configuration provider, which implements the primary org.ocpsoft.rewrite.config.ConfigurationProvider interface. In a Servlet environment, you may also extend from the abstract HttpConfigurationProvider class for convenience:
NOTE: The @RewriteConfiguration annotation must be added to your provider class to activate your configuration; otherwise, Rewrite will ignore it!
Implement a ConfigurationProvider
package com.example;

@RewriteConfiguration
public class ExampleConfigurationProvider extends HttpConfigurationProvider
{
   @Override
   public int priority()
   {
     return 10;
   }

   @Override
   public Configuration getConfiguration(final ServletContext context)
   {
     return ConfigurationBuilder.begin()
       .addRule()
         .when(Direction.isInbound().and(Path.matches("/some/{page}/")))
         .perform(Forward.to("/new-{page}/"));
    }
}

3. Add rules to your configuration

Condition objects such as Direction.isInbound() and Path.matches(...) can be found in the common org.ocpsoft.rewrite.config.* and org.ocpsoft.rewrite.servlet.config.* packages. If you can describe what you want to do, you can use fluent rewrite conditions and operations.
Take a look at some example configuration.

4. Use Rewrite extensions for extra power

Just include the corresponding extension in your pom.xml file in order to add functionality to your application (Or download and include the JAR files.):
/pom.xml
<dependency>
    <groupId>org.ocpsoft.rewrite</groupId>
    <artifactId>rewrite-integation-gwt</artifactId>
    <version>${rewrite.version}</version>
</dependency>

Run your “rewritten” application!

You should now be ready to go! Rewrite is installed, and your first configuration provider is enabled. If everything has been done correctly, you should see Rewrite log a message confirming registration of your configuration providers (in priority order.)
RewriteFilter starting up...
Loaded [1] org.ocpsoft.rewrite.config.ConfigurationProvider [com.example.ExampleRewriteConfiguration<0>]
RewriteFilter initialized.

Read the Documentation

Our Rewrite Manual is a work in progress, but continues to grow daily. There is a lot you can do with this framework, and we are taking our time to make sure that our examples behave as advertised.

You may also wish to read the installation guide or configuration manual, including instructions for using Rewrite annotations, or migrating from PrettyFaces 3.x.