Resin Documentation

url rewrite tags

Resin's <rewrite-dispatch> tag allows configuration for URL aliasing, rewriting, dispatching, and redirection.

<rewrite-real-path> configures an alias for files located on the filesystem, allowing for the mapping of a virtual directory.

Contains one or more conditions and evaluates to true if all of the contained conditions evaluate to true, false if any of the contained conditions does not evaluate to true.

Evaluates to true if the authorization mechanism used in the request is the given value. The comparison is always case insensitive.

If the auth-type is not "none", or if the auth-type of the request is not "none", a Cache-Control header containing "private" is added to the response.

Evaluates to true if the value of a cookie with a given name matches a regular expression regexp, false if it does not or if the cookie does not exist.

The Vary header of the response is updated to include "Cookie", which indicates to the browser and any intervening proxy cache that the response varies based on the submitted value of cookies.

Cron syntax for specifying a time or times that that the rule should be disabled. In conjunction, enable-at and disable-at provide a means for scheduling the enablement of a rule.

If <dispatch> matches the current URL, the rest of the items in the enclosing rewrite-dispatch are not considered and the request passes immediately to normal servlet evaluation. <dispatch> is often used to specify URLs which should be handled normally before a more general pattern which modifies the URL.

For example, the following pattern uses <dispatch> to handle images and *.php files normally, but forward's all other requests to /index.php.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <dispatch regexp="\.(php|gif|css|jpg|png)"/>
   <forward regexp="^" target="/index.php"/>
 </rewrite-dispatch>

</web-app>

Cron syntax for specifying a time or times that that the rule should be enabled, see <disable-at/>.

Set's the initial state of the rule, default is true. In conjunction with name, an initial enabled value of "false" is valuable for rules which are to be turned on and turned off at runtime.

<forbidden> sents a 403 forbidden message to the browser for a matching URL.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <forbidden regexp="^/protected"/>
 </rewrite-dispatch>

</web-app>

<forward> rewrites the current URL, forwarding it to the target using the servlet forward() call. Because <forward> is internal, it will have better performance than a <redirect> when the target URL is on the same server, the browser will not know that the underlying resource has moved.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <forward regexp="^/old" target="/new"/>
 </rewrite-dispatch>

</web-app>

Evaluates to true if the value of a header with a given name matches a regular expression regexp, false if it does not or if the header does not exist.

The Vary header of the response is updated to include the header name which indicates to the browser and any intervening proxy cache that the response varies based on the submitted value of the header.

<gone> sents a 410 gone response to the browser for a matching URL.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <gone regexp="^/protected"/>
 </rewrite-dispatch>

</web-app>

<import> loads rules from an external xml file.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">

  <rewrite-dispatch>
    <import path='/WEB-INF/rewrite-maintenance.xml' enabled="false"/>
    <import path='/WEB-INF/rewrite-rules.xml'/>
  </rewrite-dispatch>

</web-app>

<rewrite-dispatch xmlns="http://caucho.com/ns/resin"
                  xmlns:resin="http://caucho.com/ns/resin/core">

   <dispatch regexp="\.(css|gif|jpg|pdf|png)"/>

   <forward regexp=".*" target="/maintenance.html"/>

</rewrite-dispatch>

Changes to the external file are checked for at a frequency determined by dependency-check-interval or when the update() operation of the mbean is invoked. If an error occurs when loading the modified file, the contents of the old file are used until the errors are corrected or the server is restarted. The log file will contain details for the error, and the RedeployError property of the mbean wil contain a description of the error.

Each <import> registers an mbean of type RewriteImport, with a full a name like "resin:Host=default,WebApp=/,name=Foo,type=RewriteRule" and an interface of . It provides the update(), start() and stop() operations. The update() operations forces an immediate check for modifications to the external file.

<load-balance> forwards requests from a web-tier server to a cluster of app-tier servers for load-balancing. Load balancing provides scalability by splitting load among many application servers and increases reliability by avoiding servers which are upgrading or restarting.

In the following example, the web-tier load-balances all traffic to a cluster of backend application servers. Because the web-tier has a proxy cache, static pages and cached pages will be served directory from the web-tier.

<load-balance> requires Resin Professional.

<resin xmlns="http://caucho.com/ns/resin">

  <cluster id="app-tier">
    <server id="app-a" address="192.168.3.1">
    <server id="app-b" address="192.168.3.2">
    ...
  </cluster>

  <cluster id="web-tier">
    <server id="web-a" address="192.168.2.1">
      <http port="80"/>
    </server>

    <cache/>

    <host id="">
      <web-app id="/">

        <rewrite-dispatch>
          <load-balance regexp="" cluster="app-tier"/>
        </rewrite-dispatch>

      </web-app>
    </host>

</resin>

Evaluates to true if the value of the Locale matches a regular expression, false if it does not. The comparison is always case insensitive.

The Locale is a normalization of the value of the Accept-Language header. For example "fr" remains "fr" and "FR-CA" becomes "fr_CA". If the request does not include the Accept-Language header then the Locale is the default Locale for the server.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">

  <rewrite-dispatch>
    <forward regexp='^/' target='/fr/'>
      <when locale="^fr"/>
    </forward>

    <forward regexp='^/' target='/en/'/>
  </rewrite-dispatch>
</web-app>

Evaluates to true if the value of the request's local port is the specified value, false if it does not. The local port is the port that Resin has bound to and has used to receive the request.

Evaluates to true if the http method used in the request is the given value. The comparison is always case insensitive. Common methods include HEAD, GET, POST, DELETE, OPTIONS, PUT, and TRACE, although a method by any name may be used by a client.

<match> provides a way to group more specific rules based on the url. The contents of the <match> are any rule, and they are considered only if the regexp of the <match> is satsified and the match is enabled.

Judicious use of <match> will provide better performance in situations where there are many rules and some of them contain when or if conditions.

<match> also provides a convenient way to group a set of rules that can be enabled or disabled using an mbean. If the name attribute is specified for the <match> then an mbean with a name like resin:Host=default,WebApp=/,name=name,type=RewriteRule is registered and the start() and stop() operations are available.

The documentation for <rewrite-dispatch> provides a table of all rules. In addition to the rules that can be contained within <match>, the following configuration tags are available.

<moved-permanently> sends a HTTP 301 moved permanently response to the browser, indicating that the resource has moved.

The following example causes all requests to the "old.com" host to be immediately redirected to "new.com". The urls will be maintained, so for example a request to http://old.com/hello/world.html?foo=bar will get redirected to http://new.com/hello/world.html?foo=bar.

  <host id="old.com">
    <web-app id="/">
      <rewrite-dispatch>
        <moved-permanently regexp="^/(.*)$"
                           target="http://new.com/$1"/>
      </rewrite-dispatch>
    </web-app>
  </host>

A rule can be given a name, which causes a JMX mbean to be registered. The mbean has a name like "resin:Host=default,WebApp=/,name=Foo,type=RewriteRule" and an interface of . It provides the start() and stop() operations.

Contains one or more conditions and evaluates to true only if none of the contained conditions evaluate to true, false if any of the contained conditions evaluate to true.

Contains one or more conditions and evaluates to true if any of the contained conditions evaluate to true, false only if all of the contained conditions evaluate to false.

<not-found> sents a 404 not found to the browser for a matching URL.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <not-found regexp="^/protected"/>
 </rewrite-dispatch>

</web-app>

Evaluates to true if the value of a query parameter with a given name matches a regular expression regexp, false if it does not or if the parameter does not exist.

Form parameters submitted in the body of a POST are not available for the comparison performed by query-param.

<redirect> sends a HTTP 302 redirect response to the browser, indicating that the resource has moved.

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-dispatch>
    <redirect regexp="^/(foo)" target="http://$1.bar.com"/>
  </rewrite-dispatch>

</web-app>

  <host ... >
     <rewrite-dispatch>
        <redirect regexp="^" target="https://${host.name}">
          <when secure="false"/>
        </redirect>
      </rewrite-dispatch>
      ...
   </host>

Evaluates to true if the remote address of the client matches the specified ip address.

A Cache-Control header containing "private" is added to the response.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">
  <rewrite-dispatch>
    <forbidden regexp='^/foo'>
      <unless remote-addr="192.168.2.1/24"/>
    </forbidden>

  </rewrite-dispatch>
</web-app>

Evaluates to true if the user is authenticated and has the specified name.

If there is a current user, a Cache-Control header containing "private" is added to the response.

<rewrite> rewrites the current URL, continuing processing of the <rewrite-dispatch> tags. <rewrite> can be used as an intermediate rewriting stage for more complicated patterns.

<rewrite-real-path> configures an alias for the getRealPath() call, i.e. an enhancement to the <path-mapping> tag. It provides a virtual directory mapping that allows url patterns in the web application to have a local path anywhere on the physical filesystem.

The source path is a URL, the target path is a real filesystem path.

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-real-path>
    <real-path regexp="^/images" target="/usr/local/share/images"/>
  </rewrite-real-path>

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-real-path>
    <real-path regexp="^/" target="WEB-INF/SugarCE-Full-5.0.0a"/>
  </rewrite-real-path>

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-real-path>
    <real-path regexp="^/images" target="merge:(custom-images;images)"/>
  </rewrite-real-path>

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-real-path>
    <real-path regexp="^/" target="merge:(WEB-INF/SugarCE-local;WEB-INF/SugarCE-Full-5.0.0a)"/>
  </rewrite-real-path>

<rewrite-dispatch> evaluates the child tags in order. The first matching tag dispatches the request. If no children match, the request uses the standard servlet handling.

The child tags rewrite and dispatch based on regexp patterns.

<web-app xmlns="http://caucho.com/ns/resin">

 <rewrite-dispatch>
   <dispatch regexp="\.(php|gif|css|jpg|png)"/>
   <forward regexp="^" target="/index.php"/>
 </rewrite-dispatch>

</web-app>

<secure> specifies a condition for the ssl status of the request. If secure is true, then the request must be using ssl for the rule to match. If secure is false, then the request must not be using ssl for the rule to match. If secure is not specified, the ssl status of the request is not considered when testing if the rule matches.

<web-app xmlns="http://caucho.com/ns/resin">
  <rewrite-dispatch>
    <redirect regexp='^/foo' target='/secure'>
      <when secure='true'/>
    </redirect>

    <redirect regexp='^/foo' target='/insecure'>
      <when secure='false'/>
    </redirect>

    <redirect regexp='^/bar' target='/public'/>
  </rewrite-dispatch>
</web-app>

http://localhost:8080/foo/index.html
  --> redirect to /insecure/index.html

https://localhost:8080/foo/index.html
  --> redirect to /secure/index.html

http://localhost:8080/bar/index.html
  --> redirect to /public/index.html

https://localhost:8080/bar/index.html
  --> redirect to /public/index.html

Evaluates to true if the value of the request's server name matches the specified regexp, false if it does not. The comparison is always case insensitive. The server name is the name that the client has used to connect to the server and may not be the name of the actual server that is hosting Resin.

Most potential problems that can be solved by server-name are more efficiently solved using virtual hosts and the host-alias tag.

Evaluates to true if the value of the request's server port is the specified value, false if it does not. The server port is the port that the client has used to connect to the server and may not be the actual port that Resin is bound to.

<set> is used to set properties of the request or response before continuing on to the next rule. The properties are maintained after the rewriting is complete, for example a request that becomes secure because of <set> will continue to be regarded as secure when the request eventually reaches a jsp or servlet.

<web-app xmlns="http://caucho.com/ns/resin">

  <rewrite-dispatch>
    <set request-secure="true">
      <when header="X-SSL-cipher"/>
    </set>

    <forward regexp="^/checkout" target="https://hogwarts.com/checkout">
      <when secure="false"/>
    </forward>

  </rewrite-dispatch>

</web-app>

Contains a condition that further refines the match of the enclosing tag beyond the information provided by the url. If the condition does not evaluate to true, then the enclosing tag is applied.

See <when> for a description of possible conditions.

Evaluates to true if the user is authenticated and in the specified role. The special role of '*' means any role.

If the current user is any role, a Cache-Control header containing "private" is added to the response.

Contains a condition that further refines the match of the enclosing tag beyond the information provided by the url. If the condition evaluates to true, then the enclosing tag is applied.

Logging for the name com.caucho.server.rewrite at the "finer" level reveals successful matches. At the "finest" level both successful and unsuccessful matches are logged.

<logger name="com.caucho.server.rewrite" level="finest"/>

[1998/05/08 02:51:31.000] forward ^/foo: '/baz/test.jsp'  no match
[1998/05/08 02:51:31.000] forward ^/bar: '/baz/test.jsp'  no match
[1998/05/08 02:51:31.000] forward ^/baz: '/baz/test.jsp'  -->  '/hogwarts/test.jsp'

    http://anything.com/anything.html
      redirect => https://anything.com/anything.html
  

    <host ...>
      ...
      <rewrite-dispatch>
        <redirect regexp="^" target="https://${host.name}">
          <when secure="false"/>
        </redirect>
      </rewrite-dispatch>
      ...
    </host>
  

    http://gryffindor.hogwarts.com/anything.html
      forward => /gryffindor/*

    http://slytherin.hogwarts.com/anything.html
      forward => /slytherin/anything.html

    http://hogwarts.com/anything.html
      forward => /anything.html
  

    <cluster>
      ...
      <rewrite-dispatch>
        <forward regexp="http://gryffindor\.[^/]+" target="/gryffindor/"/>
        <forward regexp="http://slytherin\.[^/]+" target="/slytherin/"/>
      </rewrite-dispatch>
      ...
    </cluster>