rewrite-tags.xtp

RESIN 3.2 最新源码

    <td>Whether or not sessions should be sticky</td>
    <td>true</td></tr>
<tr><td>strategy</td>
    <td>The load balancing strategy, `round-robin' or `least-connection'</td>
    <td>least-connection</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="locale">
<parents>when, unless</parents>

<p>
Evaluates to true if the value of the Locale matches a regular
expression, false if it does not.   The comparison is always case
insensitive.
</p>

<p>
The Locale is a normalization of the value of the Accept-Language header.
For example "fr" remains "fr" and "FR-CA" becomes "fr_CA".
If the request does not include the Accept-Language header then the Locale is
the default Locale for the server.
</p>

<example>
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core"&gt;

  &lt;rewrite-dispatch&gt;
    &lt;forward regexp='^/' target='/fr/'&gt;
      &lt;when locale="^fr"/&gt;
    &lt;/forward&gt;

    &lt;forward regexp='^/' target='/en/'/&gt;
  &lt;/rewrite-dispatch&gt;
&lt;/web-app&gt;
</example>

<deftable-childtags>
<tr><td>locale</td>
    <td>Regular expression to match</td>
    <td>required</td></tr>
<tr><td>send-vary</td>
    <td>Send a <code>Vary</code> header containing "<code>Accept-Language</code>" as part of the response</td>
    <td>true</td></tr>
</deftable-childtags>

</defun>

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

<p>
Evaluates to true if the value of the request's local port is the specified
value, false if it does not.  The local port is the port that Resin has bound
to and has used to receive the request.
</p>

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

</defun>

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

<p>
Evaluates to true if the http method used in the request is the given value.
The comparison is always case insensitive.  Common methods include HEAD, GET,
POST, DELETE, OPTIONS, PUT, and TRACE, although a method by any name may be
used by a client.
</p>

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

</defun>

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

<p>
&lt;match> provides a way to group more specific rules based on the url.
The contents of the &lt;match> are any rule, and they are considered only if
the regexp of the &lt;match> is satsified and the match is <var>enabled</var>.
</p>

<p>
Judicious use of &lt;match> will provide better performance in situations where
there are many rules and some of them contain <a href="#when">when</a> or
<a href="#if">if</a> conditions.
</p>

<p>
&lt;match> also provides a convenient way to group a set of rules that can be
enabled or disabled using an mbean.  If the <var>name</var> attribute is specified
for the &lt;match> then an mbean with a name like
<code>resin:Host=default,WebApp=/,name=<i>name</i>,type=RewriteRule</code>
is registered and the <code>start()</code> and <code>stop()</code> operations
are available.
</p>

<p>
The documentation for <a href="#rewrite-dispatch">&lt;rewrite-dispatch></a> provides
a table of all rules.  In addition to the rules that can be contained within &lt;match>,
the following configuration tags are available.
</p>

<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><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;moved-permanently>">
<parents>rewrite-dispatch, match</parents>

<p>&lt;moved-permanently> sends a HTTP 301 moved permanently
response to the browser, indicating that the resource has moved.</p>

<p>
The following example causes all requests to the "old.com" host to be
immediately redirected to "new.com".  The urls will be maintained, so for
example a request to <code>http://old.com/hello/world.html?foo=bar</code> will
get redirected to <code>http://new.com/hello/world.html?foo=bar</code>.
</p>

<example title="Forwarding to a new virtual host">
  &lt;host id="old.com"&gt;
    &lt;web-app id="/"&gt;
      &lt;rewrite-dispatch&gt;
        &lt;moved-permanently regexp="^/(.*)$"
                           target="http://new.com/$1"/&gt;
      &lt;/rewrite-dispatch&gt;
    &lt;/web-app&gt;
  &lt;/host&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><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="name">
<p>
A rule can be given a <i>name</i>, which causes a JMX mbean to be registered.
The mbean has a name like "resin:Host=default,WebApp=/,name=Foo,type=RewriteRule"
and an interface of <a href="javadoc|com.caucho.management.server.RewriteRuleMXBean|"/>.
It provides the <code>start()</code> and <code>stop()</code> operations.
</p>
</defun>

<defun title="&lt;not&gt;">
<parents>when, unless</parents>

<p>
Contains one or more conditions and evaluates to true only if none of the
contained conditions evaluate to true, false if any of the contained conditions
evaluate to true.
</p>

</defun>

<defun title="&lt;or&gt;">
<parents>when, unless</parents>

<p>
Contains one or more conditions and evaluates to true if any of the contained
conditions evaluate to true, false only if all of the contained conditions
evaluate to false.
</p>

</defun>

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

<p>&lt;not-found> sents a 404 not found to the browser
for a matching URL.</p>

<example title="Hiding a directory">
&lt;web-app xmlns="http://caucho.com/ns/resin">

 &lt;rewrite-dispatch>
   &lt;not-found regexp="^/protected"/>
 &lt;/rewrite-dispatch>

&lt;/web-app>
</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><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="query-param">
<parents>when, unless</parents>

<p>
Evaluates to true if the value of a query parameter with a given <var/name/> matches a regular
expression <var/regexp/>, false if it does not or if the parameter does not exist.
</p>

<p>
Form parameters submitted in the body of a POST are not available for the comparison performed by query-param.
</p>

<deftable-childtags>
<tr><td>query-param</td>
    <td>Name of the parameter</td>
    <td>required</td></tr>
<tr><td>regexp</td>
    <td>The regular expression to match</td>
    <td>optional</td></tr>
</deftable-childtags>

</defun>

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

<p>&lt;redirect> sends a HTTP 302 redirect response to the browser,
indicating that the resource has moved.</p>

<example title="Forwarding to a new virtual host">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;rewrite-dispatch>
    &lt;redirect regexp="^/(foo)" target="http://$1.bar.com"/>
  &lt;/rewrite-dispatch>

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

<example title="Redirecting all http:// requests to https://">
  &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>

<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><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;regexp>">

<p>The regular expression in a regexp tag or attribute is a standard
Java regular expression.</p>

<p>To make the regexp case insensitive, you can use the <code>(?i:...)</code> syntax:</p>

<example title="case-insensitive match">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core"&gt;
  &lt;rewrite-dispatch&gt;
    &lt;forbidden regexp='(?i:^/foo)'/&gt;
  &lt;/rewrite-dispatch&gt;
&lt;/web-app&gt;
</example>

</defun>

<defun title="remote-addr">
<parents>when, unless</parents>

<p>
Evaluates to true if the remote address of the client matches the specified ip
address.
</p>

<p>
A <code>Cache-Control</code> header containing "<code>private</code>" is added
to the response.
</p>

<example title="Forbidding admin access to clients outside of the local network">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core"&gt;
  &lt;rewrite-dispatch&gt;
    &lt;forbidden regexp='^/foo'&gt;
      &lt;unless remote-addr="192.168.2.1/24"/&gt;
    &lt;/forbidden&gt;

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

<deftable-childtags>
<tr><td>remote-addr</td>
    <td>An IP address, optionally followed by a <code>/</code> and a number of bits to match.</td>
    <td>required</td></tr>
</deftable-childtags>

</defun>

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

<p>
Evaluates to true if the user is authenticated and has the specified name.
</p>

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

<deftable-childtags>
<tr><td>remote-user</td>
    <td>A user 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;rewrite>">
<parents>rewrite-dispatch, match</parents>

<p>&lt;rewrite> rewrites the current URL, continuing processing of
the &lt;rewrite-dispatch> tags.  &lt;rewrite> can be used as an
intermediate rewriting stage for more complicated patterns.</p>

</defun>

<defun title="&lt;rewrite-real-path>">
<parents>web-app</parents>

<p>
&lt;rewrite-real-path> configures an alias for the getRealPath() call, i.e.
an enhancement to the &lt;path-mapping> tag. It provides a virtual directory
mapping that allows url patterns in the web application to have a local path anywhere
on the physical filesystem.
</p>
<!-- note: "virtual-directory-mapping" "local-path" and "url-pattern" are weblogic terms/config for the same thing -->

<p>The source path is a URL, the target path is a real filesystem path.</p>

<example title="/images located outside of /var/www">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;rewrite-real-path>
    &lt;real-path regexp="^/images" target="/usr/local/share/images"/>
  &lt;/rewrite-real-path>
</example>

<example title="Managing versions of software bundles">
&lt;web-app xmlns="http://caucho.com/ns/resin">

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

<s2 title="Merge paths">

<p>
A merge path is a collection of paths, similar to a classpath.  It allows the
specification of multiple paths that are merged together and presented to the
application as if it was one unified path.  Merge paths are specified with a
syntax of "<code>merge:(path1[;path2[;pathN]])</code>".  If a file is in
<code>path1</code> it overrides a file with the same name in <code>path2</code>,
if a file is not in <code>path1</code> then the file will be matched to
<code>path2</code>.
</p>

<p>
Merge paths are useful for specifying customization directories that allow for
the insertion of files that replace the usual file that is shipped with a web
application.
</p>