Caucho Technology
  • 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

    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
    NAMEDESCRIPTION
    <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.
    AbstractTargetDispatchRuleBase class for custom dispatch rules.
    Basic conditions
    NAMEDESCRIPTION
    <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.
    RequestPredicateInterface for custom request predicates.
    Combining conditions
    NAMEDESCRIPTION
    <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
    NAMEDESCRIPTION
    <resin:SetHeader>Sets a response header.
    <resin:SetRequestSecure>Marks the request as secure.
    <resin:SetVary>Sets the Vary header.
    <mypkg:MyFilter>Servlet filters.

    Copyright © 1998-2011 Caucho Technology, Inc. All rights reserved.
    Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.