rewrite

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

Rewrite is an OpenSource, Filter-based Servlets extension for Java – enabling creation of bookmark-able, pretty URLs. Rewrite solves the “RESTful URL” problem elegantly, including features such as: page-load actions, managed parameter parsing, seamless integration with CDI, Spring, and configuration-free compatibility with other web frameworks. Get involved in the project »

Get Started, Rewrite how you think about Servlets (5 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 #ocpsoft – our channel on irc.freenode.net. Additionally, you are welcome to attend the dev meeting, every Monday at 1pm EST. Also, please join the discussion on our dev email list.

1. Include Rewrite in your Project

Add Rewrite to your maven pom.xmlOr download the ZIP

<dependency>
   <groupId>org.ocpsoft.rewrite</groupId>
   <artifactId>rewrite-servlet</artifactId>
   <version>2.0.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:

Implement a ConfigurationProvider

package com.example;
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. Register your configuration provider

Register your configuration provider by creating a file in the Java resources directory named: /META-INF/services/org.ocpsoft.rewrite.config.ConfigurationProvider. This file must contain the fully qualified name of your ConfigurationProvider implementation.

The registration file must be created in src/main/resources/META-INF/services, along-side your Java resources. It must NOT be placed in the src/main/webapp/META-INF directory.

/META-INF/services/org.ocpsoft.rewrite.config.ConfigurationProvider

com.example.ExampleConfigurationProvider

4. 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.

5. 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.)

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.

RewriteFilter starting up...
Loaded [1] org.ocpsoft.rewrite.config.ConfigurationProvider [com.example.ExampleRewriteConfiguration<0>]
RewriteFilter initialized.