Rewrite
From Resin 3.0
<document> <header> <title>URL Rewriting and Dispatching</title> <description>
When you need to rewrite an external URL to a more convenient internal format, like rewriting to *.php files, you can use Resin's rewrite capabilities. Because Resin's rewrite is patterned after Apache's mod_rewrite, you can translate older mod_rewrite rules to Resin's rewrite tags.
</description> </header> <body>
<localtoc/>
<s1 title="Samples">
<s2 title="MediaWiki rewrites">
PHP frameworks like MediaWiki often rewrite the public URLs to a server URL based on a PHP file, but pass through known file types like .jpg, .js, and .css file for normal webserver processing. The <resin:Dispatch> tag matches a URL with a regular expression, and optionally rewrites the URL. MediaWiki uses two: one to match the known files, and one to rewrite to a .php file.
<example title="Example: MediaWiki /Main_Page to /index.php/Main_Page"> <web-app xmlns="http://caucho.com/ns/resin"
xmlns:resin="urn:java:com.caucho.resin">
<resin:Dispatch regexp="\.(php|jpg|html|txt|gif|png|js|css)"/> <resin:Dispatch regexp="^" target="/index.php"/>
</web-app> </example>
Because the first matching rewrite rule stops processing, a URL like "/default.css" would match the first Dispatch and be processed like a normal URL. But a URL like "/foo" doesn't match the first tag, so falls through to the second, where it is rewritten to "/index.php/foo".
Other PHP packages like Drupal use the same kind of rewriting:
<example title="Example: Drupal node/1924"> <web-app xmlns="http://caucho.com/ns/resin"
xmlns:resin="urn:java:com.caucho.resin">
<resin:Dispatch regexp="\.(php|jpg|html|txt|gif|png|js|css)"/> <resin:Dispatch regexp="^/" target="/index.php?q="/>
</web-app> </example>
<example title="Example: Wordpress Rewriting"> <web-app xmlns="http://caucho.com/ns/resin"
xmlns:resin="urn:java:com.caucho.resin">
<resin:Dispatch> <resin:IfFileExists/> </resin:Dispatch>
<resin:Forward regexp="^" target='/index.php'/>
</web-app> </example>
</s2>
<s2 title="Redirects">
<example title="Example: redirecting old pages"> <web-app xmlns="http://caucho.com/ns/resin"
xmlns:resin="urn:java:com.caucho.resin">
<resin:Redirect regexp="^/old-page.html" target="/new-page.html"/> <resin:Redirect regexp="^/old/" target="/new/"/>
</web-app> </example>
</s2>
</s1>
<s1 title="Overview">
<deftable title="Dispatch rules"> <tr>
<th>name</th> <th>description</th>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/Dispatch.html"><resin:Dispatch></a></td> <td>Normal servlet dispatching with optional target rewriting.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/FastCgiProxy.html"><resin:FastCgiProxy></a></td> <td>Proxies the request to a backend server using FastCGI as a proxy protocol.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/Forbidden.html"><resin:Forbidden></a></td> <td>Send a HTTP forbidden response.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/Forward.html"><resin:Forward></a></td> <td>Forwards to the new URL using RequestDispatcher.forward with the target URL.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/HttpProxy.html"><resin:HttpProxy></a></td> <td>Proxies the request to a backend server using HTTP as a proxy protocol.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/LoadBalance.html"><resin:LoadBalance></a></td> <td>Load balance to a cluster of backend Resin servers.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/Redirect.html"><resin:Redirect></a></td> <td>Send a HTTP redirect to a new URL specified by target.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/SendError.html"><resin:SendError></a></td> <td>Send a HTTP error response.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/AbstractTargetDispatchRule.html">AbstractTargetDispatchRule</a></td> <td>Base class for custom dispatch rules.</td>
</tr> </deftable>
<deftable title="Basic conditions"> <tr>
<th>name</th> <th>description</th>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfAuthType.html"><resin:IfAuthType></a></td> <td>Checks for the authentication type, request.getAuthType().</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfCookie.html"><resin:IfCookie></a></td> <td>Checks for the presence of a named HTTP cookie from request.getCookies().</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfCron.html"><resin:IfCron></a></td> <td>Matches if the current time is in an active range configured by cron-style times.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfFileExists.html"><resin:IfFileExists></a></td> <td>Matches if the URL corresponds to an actual file.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfHeader.html"><resin:IfHeader></a></td> <td>Tests for a HTTP header and value match.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfLocale.html"><resin:IfLocale></a></td> <td>Tests for a Locale match from the HTTP request.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfLocalPort.html"><resin:IfLocalPort></a></td> <td>Compares the local port of the request, request.getLocalPort().</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfMethod.html"><resin:IfMethod></a></td> <td>Compares the HTTP method, request.getMethod().</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfNetwork.html"><resin:IfNetwork></a></td> <td>Compares the remote IP address to a network pattern like 192.168/16.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfQueryParam.html"><resin:IfQueryParam></a></td> <td>Tests for a HTTP query parameger, request.getParameter().</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfRemoteAddr.html"><resin:IfRemoteAddr></a></td> <td>Tests against the remote IP address, request.getRemoteAddr().</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfRemoteUser.html"><resin:IfRemoteUser></a></td> <td>Tests against the remote user, request.getRemoteUser().</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfSecure.html"><resin:IfSecure></a></td> <td>True for SSL requests, i.e. if request.isSecure() is true.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfUserInRole.html"><resin:IfUserInRole></a></td> <td>Tests is the user is in the servlet security role.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/RequestPredicate.html">RequestPredicate</a></td> <td>Interface for custom request predicates.</td>
</tr> </deftable>
<deftable title="Combining conditions"> <tr>
<th>name</th> <th>description</th>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/And.html"><resin:And></a></td> <td>Matches if all children match.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/Or.html"><resin:Or></a></td> <td>Matches if any children match.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/Not.html"><resin:Not></a></td> <td>Matches if the child does not match.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/NotAnd.html"><resin:NotAnd></a></td> <td>Matches if any child does not match.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/NotOr.html"><resin:NotOr></a></td> <td>Matches if all the children do not match.</td>
</tr> </deftable>
<deftable title="Rewrite filters"> <tr>
<th>name</th> <th>description</th>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/SetHeader.html"><resin:SetHeader></a></td> <td>Sets a response header.</td>
</tr> <tr>
<td><a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/SetRequestSecure.html"><resin:SetRequestSecure></a></td> <td>Marks the request as secure.</td>
</tr> <tr>
<td><mypkg:MyFilter></td> <td>Servlet filters.</td>
</tr> </deftable>
</s1>
<s1 title="Dispatch Rules">
Resin's dispatching is based on a list of <a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/DispatchRule.html">dispatch rules</a> configured in the resin-web.xml or the resin.xml configuration files. Each rule has a regular expression matching request URLs. The first dispatch rule that matches takes control of the request. For example, a <a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/Redirect.html"><resin:Redirect></a> sends a HTTP redirect, and a <a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/Dispatch.html"><resin:Dispatch></a> dispatches the request as normal.
Each matching rule can rewrite the URL using a target attribute. The target uses regexp replacement syntax like Perl's rewrite or sed. The following rule flips the first two segments around, so /foo/bar would become /bar/foo.
<example title="Example: redirect flipping"> <web-app xmlns="http://caucho.com/ns/resin"
xmlns:resin="urn:java:com.caucho.resin">
<resin:Redirect regexp="^/([^/]+)/([^/]+)" target="/$2/$1"/>
</web-app> </example>
</s1>
<s1 title="Conditions">
Some dispatches might depend on request attributes like the security attribute. The <a href="http://caucho.com/resin-javadoc/com/caucho/rewrite/IfSecure.html"><resin:IfSecure></a> tag checks if the request is an SSL request, i.e. if request.isSecure() is true. For non-SSL requests, the following <resin:Forbidden> applies.
The rewrite conditions can all be used as security conditions, e.g. for <resin:Allow> or <resin:Deny>.
<example title="Example: dispatch on header"> <web-app xmlns="http://caucho.com/ns/resin"
xmlns:resin="urn:java:com.caucho.resin">
<resin:Forbidden regexp="^/secret"> <resin:IfSecure value="false"/> </resin:Forbidden>
</web-app> </example>
<s2 title="Basic Conditions">
Basic conditions check the request and return true if the condition matches. Conditions can check on authentication (IsUserInRole), the remote IP (IfNetwork), check for SSL (IfSecure), and check for activation time (IfCron) or if a file exists (IfFileExists).
</s2>
<s2 title="Combining Conditions">
Conditions can be combined using <resin:And>, <resin:Not>, etc. tags.
</s2>
</s1>
<s1 title="Filter Actions">
The rewrite capability can also add standard predefined filters to modify the output, e.g. setting a response header. Filters can use conditions as restrictions, just like the dispatch rules.
<example title="Example: SetHeader"> <web-app xmlns="http://caucho.com/ns/resin"
xmlns:resin="urn:java:com.caucho.resin">
<resin:SetHeader regexp="^/secret" name="Foo" value="bar"/>
</web-app> </example>
<s2 title="Servlet Filters">
Standard servlet filters can also be invoked as an action to the Dispatch target. Your filter is created using Java Injection syntax and will be applied if the Dispatch rule matches.
<example title="Example: SetHeader"> <web-app xmlns="http://caucho.com/ns/resin"
xmlns:resin="urn:java:com.caucho.resin">
<resin:Dispatch regexp="^/test">
<mypkg:MyFilter xmlns:my="urn:java:com.foo.mypkg">
<mypkg:my-param>my-value</mypkg:my-param>
</mypkg:MyFilter>
</resin:Dispatch>
</web-app> </example>
</s2> </s1>
</body> </document>
