Resin Documentation

Aug 2012: Resin outscales C-based web server nginx in AutoBench benchmark
Feb 2012: NetCraft survey says Resin experiencing strong growth in last year and used in number of the Million Busiest Sites.

home company blog wiki docs
app server web server
health cloud java ee pro

resin 4.0

url rewriting and dispatching

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 mechanism contains much of the same functionality as Apache's mod_rewrite, you can translate older mod_rewrite rules to Resin's rewrite tags.

Dispatch Rules
Conditions
1. Basic Conditions
2. Combining Conditions
Filter Actions
1. Servlet Filters
Logging and Debugging
Examples
Tag listing by function

Dispatch Rules

Resin's dispatching is based on a list of dispatch rules 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 <resin:Redirect> sends a HTTP redirect, and a <resin:Dispatch> 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: 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>

Conditions

Some dispatches might depend on request attributes like the security attribute. The <resin:IfSecure> 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: 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>

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

Combining Conditions

Conditions can be combined using <resin:And>, <resin:Not>, etc. tags.

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

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: dispatching with a custom filter

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

Logging and Debugging

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.

Example: Logging example

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

Examples

Redirect http:// requests to https:// requests

The desired behaviour is to redirect plain connections to SSL connections.

Desired behaviour

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

Example: resin.xml configuration

<resin xmlns="http://caucho.com/ns/resin"
    xmlns:resin="urn:java:com.caucho.resin">
    
  <cluster ...>
  <host ...>
    ...
    <resin:Redirect regexp="^" target="https://${host.name}">
      <resin:IfSecure value="false"/>
    </resin:Redirect>
    ...
  </host>
</resin>

Make an alias for a web-app

The desired behaviour is to make it so that a web-app will match more than one url pattern. For example, a web-app is deployed in webapps/physics and available at http://hostname/physics/, the desired behaviour is to allow a request to http://hostname/classroom/physics to end up at the /physics web-app.

Desired behaviour

    http://hostname/classroom/physics
      forward => http://hostname/physics 

    http://hostname/classroom/physics/anything
      forward => http://hostname/physics/anything

The rewrite-dispatch tag is used at the <host> level. If it was placed in a <web-app> then it would be too late to forward to a different web-app because Resin would have already resolved the web-app.

Example: resin.xml configuration

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

<cluster id="">
<host id="">

  <resin:Forward regexp="^/classroom/physics" target="/physics"/>

Forward based on host name

The desired behaviour is to forward requests internally based on the host name.

Desired behaviour

    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

The rewrite-dispatch tag is used at the <cluster> level. If it was placed in the <host> or the <web-app> then it would be too late to forward to a different host because Resin would have already resolved the host.

Example: resin.xml Configuration

<resin xmlns="http://caucho.com/ns/resin"
    xmlns:resin="urn:java:com.caucho.resin">
    
  <cluster>
      ...
    <resin:Forward regexp="http://gryffindor\.[^/]+" target="/gryffindor/"/>
    <resin:Forward regexp="http://slytherin\.[^/]+" target="/slytherin/"/>
   ...
</cluster>
</resin>

Tag listing by function

Dispatch rules
NAME	DESCRIPTION
<resin:Dispatch>	Normal servlet dispatching with optional target rewriting.
<resin:FastCgiProxy>	Proxies the request to a backend server using FastCGI as a proxy protocol.
<resin:Forbidden>	Send a HTTP forbidden response.
<resin:Forward>	Forwards to the new URL using RequestDispatcher.forward with the target URL.
<resin:HttpProxy>	Proxies the request to a backend server using HTTP as a proxy protocol.
<resin:LoadBalance>	Load balance to a cluster of backend Resin servers.
<resin:MovedPermanently>	Send a HTTP redirect to a new URL specified by target.
<resin:Redirect>	Send a HTTP redirect to a new URL specified by target.
<resin:SendError>	Send a HTTP error response.
AbstractTargetDispatchRule	Base class for custom dispatch rules.

Basic conditions
NAME	DESCRIPTION
<resin:IfAuthType>	Checks for the authentication type, request.getAuthType().
<resin:IfCookie>	Checks for the presence of a named HTTP cookie from request.getCookies().
<resin:IfCron>	Matches if the current time is in an active range configured by cron-style times.
<resin:IfFileExists>	Matches if the URL corresponds to an actual file.
<resin:IfHeader>	Tests for a HTTP header and value match.
<resin:IfLocale>	Tests for a Locale match from the HTTP request.
<resin:IfLocalPort>	Compares the local port of the request, request.getLocalPort().
<resin:IfMethod>	Compares the HTTP method, request.getMethod().
<resin:IfNetwork>	Compares the remote IP address to a network pattern like 192.168/16.
<resin:IfQueryParam>	Tests for a HTTP query parameger, request.getParameter().
<resin:IfRemoteUser>	Tests against the remote user, request.getRemoteUser().
<resin:IfSecure>	True for SSL requests, i.e. if request.isSecure() is true.
<resin:IfUserInRole>	Tests is the user is in the servlet security role.
RequestPredicate	Interface for custom request predicates.

Combining conditions
NAME	DESCRIPTION
<resin:And>	Matches if all children match.
<resin:Or>	Matches if any children match.
<resin:Not>	Matches if the child does not match.
<resin:NotAnd>	Matches if any child does not match.
<resin:NotOr>	Matches if all the children do not match.

Rewrite filters
NAME	DESCRIPTION
<resin:SetHeader>	Sets a response header.
<resin:SetRequestSecure>	Marks the request as secure.
<resin:SetVary>	Sets the Vary header.
<mypkg:MyFilter>	Servlet filters.