Version: 9.4.5.v20170502 |

Rewrite Handler
Previous | Chapter 18. Provided Servlets, Filters, and Handlers Home | Next

##### Contact the core Jetty developers at www.webtide.com

private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development

## Rewrite Handler

The `RewriteHandler` matches a request against a set of rules, and modifies the request accordingly for any rules that match. The most common use is to rewrite request URIs, but it is capable of much more: rules can also be configured to redirect the response, set a cookie or response code on the response, modify the header, etc.

### Info

- Classname: org.eclipse.jetty.rewrite.handler.RewriteHandler
- Maven artifact: org.eclipse.jetty:jetty-rewrite
- Javadoc: http://www.eclipse.org/jetty/javadoc/9.4.5.v20170502/org/eclipse/jetty/rewrite/handler/RewriteHandler.html
- Xref: http://download.eclipse.org/jetty/stable-9/xref/org/eclipse/jetty/rewrite/handler/RewriteHandler.html

The standard Jetty distribution bundle contains the `jetty-rewrite` module, so all you need to do is to enable it using one of the module commands, eg:

    $ java -jar start.jar --add-to-start=rewrite

> ### Note

> If you are running the standard Jetty distribution with the sample test webapp, there will be a demo of the rewrite module at http://localhost:8080/test/rewrite/

### Usage

The rewrite module enables the following Jetty xml config file on the execution path:

    <?xml version="1.0"?>
    <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

    <Configure id="Server" class="org.eclipse.jetty.server.Server">

      <!-- =========================================================== -->
      <!-- configure rewrite handler                                   -->
      <!-- =========================================================== -->
      <Call name="insertHandler">
        <Arg>
          <New class="org.eclipse.jetty.rewrite.handler.RewriteHandler">
    	<Set name="rewriteRequestURI"><Property name="jetty.rewrite.rewriteRequestURI" deprecated="rewrite.rewriteRequestURI" default="true"/></Set>
    	<Set name="rewritePathInfo"><Property name="jetty.rewrite.rewritePathInfo" deprecated="rewrite.rewritePathInfo" default="false"/></Set>
    	<Set name="originalPathAttribute"><Property name="jetty.rewrite.originalPathAttribute" deprecated="rewrite.originalPathAttribute" default="requestedPath"/></Set>

    	<!-- Set DispatcherTypes  -->
    	<Set name="dispatcherTypes">
    	  <Array type="javax.servlet.DispatcherType">
    	    <Item><Call class="javax.servlet.DispatcherType" name="valueOf"><Arg>REQUEST</Arg></Call></Item>
    	    <Item><Call class="javax.servlet.DispatcherType" name="valueOf"><Arg>ASYNC</Arg></Call></Item>
    	  </Array>
    	</Set>

            <Get id="Rewrite" name="ruleContainer"/>

    	<!-- see rewrite-compactpath.xml for example how to add a rule -->

          </New>
        </Arg>
      </Call>
    </Configure>

As the commented out code shows, you configure the `RewriteHandler` by adding various rules.

There is an example of rules configuration in the standard distribution in the `demo-base/etc/demo-rewrite-rules.xml` file:

    <?xml version="1.0"?>
    <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

    <!-- =============================================================== -->
    <!-- Configure the demos                                             -->
    <!-- =============================================================== -->
    <Configure id="Server" class="org.eclipse.jetty.server.Server">

      <!-- ============================================================= -->
      <!-- Add rewrite rules                                             -->
      <!-- ============================================================= -->
      <Ref refid="Rewrite">
          <!-- Add rule to protect against IE ssl bug -->
          <Call name="addRule">
            <Arg>
              <New class="org.eclipse.jetty.rewrite.handler.MsieSslRule"/>
            </Arg>
          </Call>

          <!-- protect favicon handling -->
          <Call name="addRule">
            <Arg>
              <New class="org.eclipse.jetty.rewrite.handler.HeaderPatternRule">
                <Set name="pattern">/favicon.ico</Set>
                <Set name="name">Cache-Control</Set>
                <Set name="value">Max-Age=3600,public</Set>
                <Set name="terminating">true</Set>
              </New>
            </Arg>
          </Call>

          <!-- redirect from the welcome page to a specific page -->
          <Call name="addRule">
            <Arg>
              <New class="org.eclipse.jetty.rewrite.handler.RewritePatternRule">
                <Set name="pattern">/test/rewrite/</Set>
                <Set name="replacement">/test/rewrite/info.html</Set>
              </New>
            </Arg>
          </Call>

          <!-- replace the entire request URI -->
          <Call name="addRule">
            <Arg>
              <New class="org.eclipse.jetty.rewrite.handler.RewritePatternRule">
                <Set name="pattern">/test/some/old/context</Set>
                <Set name="replacement">/test/rewritten/newcontext</Set>
              </New>
            </Arg>
          </Call>

          <!-- replace the beginning of the request URI -->
          <Call name="addRule">
            <Arg>
              <New class="org.eclipse.jetty.rewrite.handler.RewritePatternRule">
                <Set name="pattern">/test/rewrite/for/*</Set>
                <Set name="replacement">/test/rewritten/</Set>
              </New>
            </Arg>
          </Call>

          <!-- reverse the order of the path sections -->
          <Call name="addRule">
            <Arg>
              <New class="org.eclipse.jetty.rewrite.handler.RewriteRegexRule">
                <Set name="regex">(.*?)/reverse/([^/]*)/(.*)</Set>
                <Set name="replacement">$1/reverse/$3/$2</Set>
              </New>
            </Arg>
          </Call>

          <!-- add a cookie to each path visited -->
          <Call name="addRule">
            <Arg>
              <New class="org.eclipse.jetty.rewrite.handler.CookiePatternRule">
                <Set name="pattern">/*</Set>
                <Set name="name">visited</Set>
                <Set name="value">yes</Set>
              </New>
            </Arg>
          </Call>

          <!--  actual redirect, instead of internal rewrite -->
          <Call name="addRule">
            <Arg>
              <New class="org.eclipse.jetty.rewrite.handler.RedirectPatternRule">
                <Set name="pattern">/test/redirect/*</Set>
                <Set name="location">/test/redirected</Set>
              </New>
            </Arg>
          </Call>

          <!-- add a response rule -->
          <Call name="addRule">
            <Arg>
               <New class="org.eclipse.jetty.rewrite.handler.ResponsePatternRule">
                 <Set name="pattern">/400Error</Set>
                 <Set name="code">400</Set>
                 <Set name="reason">ResponsePatternRule Demo</Set>
              </New>
            </Arg>
          </Call>
      </Ref>
    </Configure>

#### Embedded Example

This is an example for embedded Jetty, which does something similar to the configuration file example above:

      Server server = new Server();

      RewriteHandler rewrite = new RewriteHandler();
      rewrite.setRewriteRequestURI(true);
      rewrite.setRewritePathInfo(false);
      rewrite.originalPathAttribute("requestedPath");

      RedirectPatternRule redirect = new RedirectPatternRule();
      redirect.setPattern("/redirect/*");
      redirect.setReplacement("/redirected");
      rewrite.addRule(redirect);

      RewritePatternRule oldToNew = new RewritePatternRule();
      oldToNew.setPattern("/some/old/context");
      oldToNew.setReplacement("/some/new/context");
      rewrite.addRule(oldToNew);

      RewriteRegexRule reverse = new RewriteRegexRule();
      reverse.setRegex("/reverse/([^/]*)/(.*)");
      reverse.setReplacement("/reverse/$2/$1");
      rewrite.addRule(reverse);

      server.setHandler(rewrite);

### Rules

There are several types of rules that are written extending useful base rule classes.

#### PatternRule

Matches against the request URI using the servlet pattern syntax.

CookiePatternRule
  Adds a cookie to the response.
HeaderPatternRule
  Adds/modifies a header in the response.
RedirectPatternRule
  Redirects the response.
ResponsePatternRule
  Sends the response code (status or error).
RewritePatternRule
  Rewrite the URI by replacing the matched request path with a fixed string.

#### RegexRule

Matches against the request URI using regular expressions.

RedirectRegexRule
  Redirect the response.
RewriteRegexRule
  Rewrite the URI by matching with a regular expression. (The replacement string may use `Template:$n` to replace the nth capture group.)

#### HeaderRule

Match against request headers. Match either on a header name and specific value, or on the presence of a header (with any value).

ForwardedSchemaHeaderRule
  Set the scheme on the request (defaulting to HTTPS).

#### Others

Extra rules that defy standard classification.

MsieSslRule
  Disables the keep alive for SSL from IE5 or IE6.
LegacyRule
  Implements the legacy API of RewriteHandler

#### RuleContainer

Groups rules together. The contained rules will only be processed if the conditions for the `RuleContainer` evaluate to true.

VirtualHostRuleContainer
  Groups rules that apply only to a specific virtual host or a set of virtual hosts

Previous | Top | Next
Error Handler | Home | Chapter 19. Jetty Runner

See an error or something missing? Contribute to this documentation at Github!(Generated: 2017-05-02)