<dispatch> matches the current URL, passing the request to the 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 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>

element dispatch {
  regexp
}

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

element forward {
  regexp
}

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

element forward {
  regexp & target
}

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

element gone {
  regexp
}

<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="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>

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

element load-balance {
  regexp & cluster
}

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

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

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

</web-app>

element forward {
  regexp & target
}

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

element not-found {
  regexp
}

<real-path> maps a URL to a filesystem path inside a <rewrite-real-path tag.

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" real-path="/usr/local/share/images"/>
  </rewrite-real-path>

element real-path {
  regexp & target
}

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

element forward {
  regexp & target
}

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

element rewrite {
  regexp & replacement
}

<rewrite-real-path> configures an alias for the getRealPath() call, i.e. an enhancement to the <path-mapping> tag.

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" real-path="/usr/local/share/images"/>
  </rewrite-real-path>

element rewrite-real-path {
  (real-path { regexp & target }
  | rewrite { regexp & replacement })*
}

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

element rewrite-dispatch {
  (dispatch { regexp }
  | forward { regexp & target }
  | forbidden { regexp }
  | gone { regexp }
  | moved-permanently { regexp & target }
  | not-found { regexp }
  | redirect { regexp & target }
  | rewrite { regexp & replacement })*
}