rewrite-tags.xtp

RESIN 3.2 最新源码

<!-- server/13n8.qa -->
<example title="Merge path: replacing some images with custom images">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;

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

<!-- server/13n9.qa -->
<example title="Merge path: managing the versioning and customization of a php application">
&lt;web-app xmlns="http://caucho.com/ns/resin">

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

</s2>

</defun>

<defun title="&lt;rewrite-dispatch>">
<parents>server, host, web-app</parents>

<p>&lt;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.</p>

<p>The child tags rewrite and dispatch based on regexp patterns.</p>

<example title="Mediawiki dispatch in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

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

&lt;/web-app>
</example>

<deftable-childtags>
<tr><td><a href="#dispatch">&lt;dispatch></a></td>
    <td>Dispatch the request immediately
        and do not process any more rules</td>
    <td></td></tr>
<tr><td><a href="#forbidden">&lt;forbidden></a></td>
    <td>Send a 403 Forbidden response to browser
        and do not process any more rules</td>
    <td></td></tr>
<tr><td><a href="#forward">&lt;forward></a></td>
    <td>Rewrite the URL and internally forward the request
        without processing any more rules</td>
    <td></td></tr>
<tr><td><a href="#forbidden">&lt;forbidden></a></td>
    <td>Send a 410 Gone response to  the browser
        and do not process any more rules</td>
    <td></td></tr>
<tr><td><a href="#import">&lt;import></a></td>
    <td>Import rules from an external file</td>
    <td></td></tr>
<tr><td><a href="#load-balance">&lt;load-balance></a></td>
    <td>Forward requests to another instance or instances of Resin
        and do not process any more rules</td>
    <td></td></tr>
<tr><td><a href="#match">&lt;match></a></td>
    <td>Group more specific rules</td>
    <td></td></tr>
<tr><td><a href="#moved-permanently">&lt;moved-permanently></a></td>
    <td>Send a 310 Moved Permanently response to the browser
        and do not process any more rules</td>
    <td></td></tr>
<tr><td><a href="#redirect">&lt;redirect></a></td>
    <td>Send a 302 Moved response to the browser
        and do not process any more rules</td>
    <td></td></tr>
<tr><td><a href="#rewrite">&lt;rewrite></a></td>
    <td>Rewrite the current URL
        and continue processing rules</td>
    <td></td></tr>
<tr><td><a href="#set">&lt;set></a></td>
    <td>Set a property of the request or response
        and continue processing rules</td>
    <td></td></tr>
</deftable-childtags>

</defun>

<defun title="secure">
<parents>when, unless</parents>

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

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

    &lt;redirect regexp='^/foo' target='/insecure'&gt;
      &lt;when secure='false'/&gt;
    &lt;/redirect&gt;

    &lt;redirect regexp='^/bar' target='/public'/&gt;
  &lt;/rewrite-dispatch&gt;
&lt;/web-app&gt;
</example>

<results>
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
</results>
</defun>

<defun title="server-name">
<parents>when, unless</parents>

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

<p>
Most potential problems that can be solved by  <code>server-name</code> are
more efficiently solved using <g>virtual hosts</g> and the
<a href="host-tags.xtp#host">host-alias</a> tag.
</p>

<deftable-childtags>
<tr><td>server-name</td>
    <td>A regular expression to match.</td>
    <td>required</td></tr>
</deftable-childtags>

</defun>

<defun title="server-port">
<parents>when, unless</parents>

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

<deftable-childtags>
<tr><td>server-port</td>
    <td>The server port to match.</td>
    <td>required</td></tr>
</deftable-childtags>

</defun>

<defun title="&lt;set>">
<parents>rewrite-dispatch, match</parents>

<p>
&lt;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 &lt;set> will continue to be regarded as secure when the request eventually reaches a jsp
or servlet.
</p>

<example title="Making the request secure in response to a header from a hardware load balancer">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;

  &lt;rewrite-dispatch&gt;
    &lt;set request-secure="true"&gt;
      &lt;when header="X-SSL-cipher"/&gt;
    &lt;/set&gt;

    &lt;forward regexp="^/checkout" target="https://hogwarts.com/checkout"&gt;
      &lt;when secure="false"/&gt;
    &lt;/forward&gt;

  &lt;/rewrite-dispatch&gt;

&lt;/web-app&gt;
</example>

<deftable-childtags>
<tr><td><a href="#disable-at">disable-at</a></td>
    <td>A cron syntax time specification for triggering disablement of the rule</td>
    <td>none</td></tr>
<tr><td><a href="#enable-at">enable-at</a></td>
    <td>A cron syntax time specification for triggering enablement of the rule</td>
    <td>none</td></tr>
<tr><td>enabled</td>
    <td>False to start with the rule initially disabled</td>
    <td>true</td></tr>
<tr><td><a href="#name">name</a></td>
    <td>A name to use for registering a JMX mbean with type=RewriteRule</td>
    <td>do not register an mbean</td></tr>
<tr><td>regexp</td>
    <td>A regexp that must match the <a href="#URL">URL</a></td>
    <td>optional</td></tr>
<tr><td>request-character-encoding</td>
    <td>Sets the character encoding of the request, used for parsing POST data, request.setCharacterEncoding(value)</td>
    <td>none</td></tr>
<tr><td>request-secure</td>
    <td>Sets the value of request.isSecure()</td>
    <td>none</td></tr>
<tr><td>response-character-encoding</td>
    <td>Sets the value of the character encoding sent for the response
        with response.setCharacterEncoding(value).  If a Content-Type is
        not set either with a set rule, or by some other process involved in
        servicing the request, this has no effect.</td>
    <td>none</td></tr>
<tr><td>response-content-type</td>
    <td>Sets the value of the content type sent for the response. If the final
        destination is a file with a corresponding
        <a href="webapp-tags.xtp#mime-mapping">mime-mapping</a>,
        the mime-mapping will override the content-type set here</td>
    <td>none</td></tr>
<tr><td><a href="#when">when</a></td>
    <td>A condition which must evaluate to true</td>
    <td>optional</td></tr>
<tr><td><a href="#unless">unless</a></td>
    <td>A condition which must not evaluate to true</td>
    <td>optional</td></tr>
</deftable-childtags>

</defun>

<defun title="&lt;unless&gt;">

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

<p>See <a href="#when">&lt;when></a> for a description of possible conditions.</p>

</defun>

<defun title="user-in-role">
<parents>when, unless</parents>

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

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

<deftable-childtags>
<tr><td>user-in-role</td>
    <td>A role name.</td>
    <td>required</td></tr>
<tr><td>send-vary</td>
    <td>Send a <code>Vary</code> header containing "<code>Cookie</code>" as part of the response</td>
    <td>true</td></tr>
</deftable-childtags>

</defun>

<defun title="&lt;when>">

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

<deftable-childtags>
<tr><td><a href="#and">&lt;and></a></td>
    <td>A subgroup of conditions that must all pass</td>
    <td></td></tr>
<tr><td><a href="#auth-type">auth-type</a></td>
    <td>Evaluates to true if the authorization mechanism used in the request
        is the given value</td>
    <td></td></tr>
<tr><td><a href="#cookie">cookie</a></td>
    <td>Evaluates to true if a cookie exists and matches an
        optional <var/regexp/></td>
    <td></td></tr>
<tr><td><a href="#header">header</a></td>
    <td>Evaluates to true if a request header exists and matches an
        optional <var/regexp/></td>
    <td></td></tr>
<tr><td><a href="#locale">locale</a></td>
    <td>Evaluates to true if the request locale matches the specified value</td>
    <td></td></tr>
<tr><td><a href="#local-port">local-port</a></td>
    <td>Evaluates to true if the local port is the specified value
        (the local port is the actual port that Resin is using)</td>
    <td></td></tr>
<tr><td><a href="#method">method</a></td>
    <td>Evaluates to true if the http method used for the request is
         the specified value</td>
    <td></td></tr>
<tr><td><a href="#not">&lt;not></a></td>
    <td>A subgroup of conditions, none of which may pass</td>
    <td></td></tr>
<tr><td><a href="#or">&lt;or></a></td>
    <td>A subgroup of conditions, any of which may pass</td>
    <td></td></tr>
<tr><td><a href="#query-param">query-param</a></td>
    <td>Evaluates to true if a query parameter exists and matches an
        optional <var/regexp/></td>
    <td></td></tr>
<tr><td>regexp</td>
    <td>Used in conjunction with <var/cookie/>, <var/header/>,
        and <var/query-param/></td>
    <td></td></tr>
<tr><td><a href="#remote-addr">remote-addr</a></td>
    <td>Evaluates to true if the remote address of the client matches
        the specified ip address</td>
    <td></td></tr>
<tr><td><a href="#remote-user">remote-user</a></td>
    <td>Evaluates to true if the user is authenticated and has the specified
        name</td>
    <td></td></tr>
<tr><td><a href="#secure">secure</a></td>
    <td>Evaluates to true if the ssl status of the request is equal to the
        specified value of true or false</td>
    <td></td></tr>
<tr><td><a href="#server-name">server-name</a></td>
    <td>Evaluates to true if the server name used by the client matches
        the specified value</td>
    <td></td></tr>
<tr><td><a href="#server-port">server-port</a></td>
    <td>Evaluates to true if the port used by the client equals
        the specified value</td>
    <td></td></tr>
<tr><td><a href="#user-in-role">user-in-role</a></td>
    <td>Evaluates to true if the user is authenticated and in the specified role</td>
    <td></td></tr>
</deftable-childtags>

</defun>

<s1 title="Logging and Debugging">
<p>
Logging for the name <code>com.caucho.server.rewrite</code>
at the "finer" level reveals successful matches.  At the "finest" level both
successful and unsuccessful matches are logged.
</p>

<example title="Logging example">
&lt;logger name="com.caucho.server.rewrite" level="finest"/&gt;
</example>

<results>
[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'
</results>

</s1>

<s1 title="Examples">
<s2 title="Redirect http:// requests to https:// requests">
  <p>
  The desired behaviour is to redirect plain connections to SSL connections.
  </p>

  <example title="Desired behaviour">
    http://anything.com/anything.html
      redirect => https://anything.com/anything.html
  </example>

  <example title="Configuration">
    &lt;host ...&gt;
      ...
      &lt;rewrite-dispatch&gt;
        &lt;redirect regexp="^" target="https://${host.name}"&gt;
          &lt;when secure="false"/&gt;
        &lt;/redirect&gt;
      &lt;/rewrite-dispatch&gt;
      ...
    &lt;/host&gt;
  </example>
</s2>

<s2 title="Make an alias for a web-app">
  <p>
  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
  <code>webapps/physics</code> and available at
  <code>http://hostname/physics/</code>, the desired behaviour is to allow a
  request to <code>http://hostname/classroom/physics</code> to end up at the
  <code>/physics</code> web-app.

  </p>

  <example title="Desired behaviour">
    http://hostname/classroom/physics
      forward => http://hostname/physics 

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

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

  <example title="Configuration">
    &lt;host&gt;
      &lt;rewrite-dispatch&gt;
        &lt;forward regexp="^/classroom/physics" target="/physics"/&gt;
      &lt;/rewrite-dispatch&gt;
       ...
  </example>
</s2>

<s2 title="Forward based on host name">
  <p>
  The desired behaviour is to internally forward requests based on the host name.
  </p>

  <example title="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
  </example>

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

  <example title="Configuration">
    &lt;cluster&gt;
      ...
      &lt;rewrite-dispatch&gt;
        &lt;forward regexp="http://gryffindor\.[^/]+" target="/gryffindor/"/&gt;
        &lt;forward regexp="http://slytherin\.[^/]+" target="/slytherin/"/&gt;
      &lt;/rewrite-dispatch&gt;
      ...
    &lt;/cluster&gt;
  </example>
</s2>
</s1>

</body>

</document>