RewriteHandler (Jetty :: Aggregate :: All core Jetty 7.6.8.v20121106 API)
Date: 2012-11-06

org.eclipse.jetty.rewrite.handler

## Class RewriteHandler

- java.lang.Object
- - org.eclipse.jetty.util.component.AbstractLifeCycle
  - - org.eclipse.jetty.util.component.AggregateLifeCycle
    - - org.eclipse.jetty.server.handler.AbstractHandler
      - - org.eclipse.jetty.server.handler.AbstractHandlerContainer
        - - org.eclipse.jetty.server.handler.HandlerWrapper
          - - org.eclipse.jetty.rewrite.handler.RewriteHandler

- All Implemented Interfaces:
    Handler, HandlerContainer, Destroyable, Dumpable, LifeCycle

      public class RewriteHandler
      extends HandlerWrapper

  Rewrite handler is responsible for managing the rules. Its capabilities is not only limited for URL rewrites such as RewritePatternRule or RewriteRegexRule. There is also handling for cookies, headers, redirection, setting status or error codes whenever the rule finds a match.

  The rules can be matched by the either: pattern matching of PathMap (eg `PatternRule`), regular expressions (eg `RegexRule`) or certain conditions set (eg `MsieSslRule` - the requests must be in SSL mode).

  The rules can be grouped into rule containers (class `RuleContainer`), and will only be applied if the request matches the conditions for their container (e.g., by virtual host name)

  The list of predefined rules is:

  - `CookiePatternRule` - adds a new cookie in response.
  - `HeaderPatternRule` - adds/modifies the HTTP headers in response.
  - `RedirectPatternRule` - sets the redirect location.
  - `ResponsePatternRule` - sets the status/error codes.
  - `RewritePatternRule` - rewrites the requested URI.
  - `RewriteRegexRule` - rewrites the requested URI using regular expression for pattern matching.
  - `ProxyRule` - proxies the requested URI to the host defined in proxyTo.
  - `MsieSslRule` - disables the keep alive on SSL for IE5 and IE6.
  - `LegacyRule` - the old version of rewrite.
  - `ForwardedSchemeHeaderRule` - set the scheme according to the headers present.
  - `VirtualHostRuleContainer` - checks whether the request matches one of a set of virtual host names.
  Here is a typical jetty.xml configuration would be:

           <New id="RewriteHandler" class="org.eclipse.jetty.rewrite.handler.RewriteHandler">
             <Set name="rules">
               <Array type="org.eclipse.jetty.rewrite.handler.Rule">

                 <Item>
                   <New id="rewrite" class="org.eclipse.jetty.rewrite.handler.RewritePatternRule">
                     <Set name="pattern">/*</Set>
                     <Set name="replacement">/test</Set>
                   </New>
                 </Item>

                 <Item>
                   <New id="rewrite" class="org.eclipse.jetty.rewrite.handler.ProxyRule">
                     <Set name="pattern">/*</Set>
                     <Set name="proxyTo">http://webtide.com:8080</Set>
                   </New>
                 </Item>

                 <Item>
                   <New id="response" class="org.eclipse.jetty.rewrite.handler.ResponsePatternRule">
                     <Set name="pattern">/session/</Set>
                     <Set name="code">400</Set>
                     <Set name="reason">Setting error code 400</Set>
                   </New>
                 </Item>

                 <Item>
                   <New id="header" class="org.eclipse.jetty.rewrite.handler.HeaderPatternRule">
                     <Set name="pattern">*.jsp</Set>
                     <Set name="name">server</Set>
                     <Set name="value">dexter webserver</Set>
                   </New>
                 </Item>

                 <Item>
                   <New id="header" class="org.eclipse.jetty.rewrite.handler.HeaderPatternRule">
                     <Set name="pattern">*.jsp</Set>
                     <Set name="name">title</Set>
                     <Set name="value">driven header purpose</Set>
                   </New>
                 </Item>

                 <Item>
                   <New id="redirect" class="org.eclipse.jetty.rewrite.handler.RedirectPatternRule">
                     <Set name="pattern">/test/dispatch</Set>
                     <Set name="location">http://jetty.eclipse.org</Set>
                   </New>
                 </Item>

                 <Item>
                   <New id="regexRewrite" class="org.eclipse.jetty.rewrite.handler.RewriteRegexRule">
                     <Set name="regex">/test-jaas/$</Set>
                     <Set name="replacement">/demo</Set>
                   </New>
                 </Item>

                 <Item>
                   <New id="forwardedHttps" class="org.eclipse.jetty.rewrite.handler.ForwardedSchemeHeaderRule">
                     <Set name="header">X-Forwarded-Scheme</Set>
                     <Set name="headerValue">https</Set>
                     <Set name="scheme">https</Set>
                   </New>
                 </Item>

                 <Item>
                   <New id="virtualHost" class="org.eclipse.jetty.rewrite.handler.VirtualHostRuleContainer">

                     <Set name="virtualHosts">
                       <Array type="java.lang.String">
                         <Item>eclipse.com</Item>
                         <Item>www.eclipse.com</Item>
                         <Item>eclipse.org</Item>
                         <Item>www.eclipse.org</Item>
                       </Array>
                     </Set>

                     <Call name="addRule">
                       <Arg>
                         <New class="org.eclipse.jetty.rewrite.handler.CookiePatternRule">
                           <Set name="pattern">/*</Set>
                           <Set name="name">CookiePatternRule</Set>
                           <Set name="value">1</Set>
                         </New>
                       </Arg>
                     </Call>

                   </New>
                 </Item>

               </Array>
             </Set>
           </New>

           <Set name="handler">
             <New id="Handlers" class="org.eclipse.jetty.server.handler.HandlerCollection">
               <Set name="handlers">
                 <Array type="org.eclipse.jetty.server.Handler">
                   <Item>
                     <Ref id="RewriteHandler"/>
                   </Item>
                   <Item>
                     <New id="Contexts" class="org.eclipse.jetty.server.handler.ContextHandlerCollection"/>
                   </Item>
                   <Item>
                     <New id="DefaultHandler" class="org.eclipse.jetty.server.handler.DefaultHandler"/>
                   </Item>
                   <Item>
                     <New id="RequestLog" class="org.eclipse.jetty.server.handler.RequestLogHandler"/>
                   </Item>
                 </Array>
               </Set>
             </New>
           </Set>

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

      `AbstractLifeCycle.AbstractLifeCycleListener`

    - ### Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

      `LifeCycle.Listener`

  - ### Field Summary

    - ### Fields inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

      `_handler`

    - ### Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

      `_listeners, FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RewriteHandler()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRule(Rule rule)` Add a Rule
    `String` | `getOriginalPathAttribute()`
    `Rule[]` | `getRules()` Returns the list of rules.
    `void` | `handle(String target, Request baseRequest, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Handle a request.
    `boolean` | `isRewritePathInfo()`
    `boolean` | `isRewriteRequestURI()`
    `void` | `setLegacyRule(LegacyRule legacyRule)` Deprecated.
    `void` | `setOriginalPathAttribute(String originalPathAttribute)`
    `void` | `setRewritePathInfo(boolean rewritePathInfo)`
    `void` | `setRewriteRequestURI(boolean rewriteRequestURI)`
    `void` | `setRules(Rule[] rules)` Assigns the rules to process.
    `void` | `setRules(RuleContainer rules)` Assigns the rules to process.

    - ### Methods inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

      `destroy, doStart, doStop, expandChildren, getHandler, getHandlers, getNestedHandlerByClass, setHandler, setServer`

    - ### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandlerContainer

      `dump, expandHandler, findContainerOf, getChildHandlerByClass, getChildHandlers, getChildHandlersByClass`

    - ### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandler

      `dumpThis, getServer`

    - ### Methods inherited from class org.eclipse.jetty.util.component.AggregateLifeCycle

      `addBean, addBean, contains, dump, dump, dump, dump, dumpObject, dumpStdErr, getBean, getBeans, getBeans, isManaged, manage, removeBean, removeBeans, unmanage`

    - ### Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

      `addLifeCycleListener, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

      `addLifeCycleListener, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

- - ### Constructor Detail

    - #### RewriteHandler

          public RewriteHandler()

  - ### Method Detail

    - #### setLegacyRule

          @Deprecated
          public void setLegacyRule(LegacyRule legacyRule)

      Deprecated.
      To enable configuration from jetty.xml on rewriteRequestURI, rewritePathInfo and originalPathAttribute
      Parameters:
        `legacyRule` - old style rewrite rule

    - #### getRules

          public Rule[] getRules()

      Returns the list of rules.
      Returns:
        an array of `Rule`.

    - #### setRules

          public void setRules(Rule[] rules)

      Assigns the rules to process.
      Parameters:
        `rules` - an array of `Rule`.

    - #### setRules

          public void setRules(RuleContainer rules)

      Assigns the rules to process.
      Parameters:
        `rules` - a `RuleContainer` containing other rules to process

    - #### addRule

          public void addRule(Rule rule)

      Add a Rule
      Parameters:
        `rule` - The rule to add to the end of the rules array

    - #### isRewriteRequestURI

          public boolean isRewriteRequestURI()

      Returns:
        the rewriteRequestURI If true, this handler will rewrite the value returned by `HttpServletRequest.getRequestURI()`.

    - #### setRewriteRequestURI

          public void setRewriteRequestURI(boolean rewriteRequestURI)

      Parameters:
        `rewriteRequestURI` - true if this handler will rewrite the value returned by `HttpServletRequest.getRequestURI()`.

    - #### isRewritePathInfo

          public boolean isRewritePathInfo()

      Returns:
        true if this handler will rewrite the value returned by `HttpServletRequest.getPathInfo()`.

    - #### setRewritePathInfo

          public void setRewritePathInfo(boolean rewritePathInfo)

      Parameters:
        `rewritePathInfo` - true if this handler will rewrite the value returned by `HttpServletRequest.getPathInfo()`.

    - #### getOriginalPathAttribute

          public String getOriginalPathAttribute()

      Returns:
        the originalPathAttribte. If non null, this string will be used as the attribute name to store the original request path.

    - #### setOriginalPathAttribute

          public void setOriginalPathAttribute(String originalPathAttribute)

      Parameters:
        `originalPathAttribute` - If non null, this string will be used as the attribute name to store the original request path.

    - #### handle

          public void handle(String target,
                    Request baseRequest,
                    javax.servlet.http.HttpServletRequest request,
                    javax.servlet.http.HttpServletResponse response)
                      throws IOException,
                             javax.servlet.ServletException

      Description copied from interface: `Handler`
      Handle a request.
      Specified by:
        `handle` in interface `Handler`
      Overrides:
        `handle` in class `HandlerWrapper`
      Parameters:
        `target` - The target of the request - either a URI or a name.
        `baseRequest` - The original unwrapped request object.
        `request` - The request either as the `Request` object or a wrapper of that request. The `AbstractHttpConnection.getCurrentConnection()` method can be used access the Request object if required.
        `response` - The response as the `Response` object or a wrapper of that request. The `AbstractHttpConnection.getCurrentConnection()` method can be used access the Response object if required.
      Throws:
        `IOException`
        `javax.servlet.ServletException`

Copyright © 1995-2012 Mort Bay Consulting. All Rights Reserved.