plugin-dispatch.xtp

解压在c盘

<s1 title="How the Plugins Dispatch to Resin">

<summarylist/>

<p>The web server plugins (mod_caucho, isapi_srun, and nsapi) have
two main tasks:</p>
<ol>
<li>Select urls to dispatch to the Java process
<li>Pass the request and retrieve the response from the Java process.
</ol>

<note>This page uses "mod_caucho" to mean all the plugins.  All of the plugins
work the same, so "mod_caucho" is just a shorthand for "mod_caucho,
isapi_srun, and nsapi".</note>

<p>In most cases, mod_caucho will just use resin.conf as expected.
This tutorial should help understand what's going for the
more complicated cases.</p>

<s2 title="servlet-mapping selects URLs">

<p>The <a href="../ref/app-config.xtp#servlet-mapping">servlet-mapping</a>
tag selects the URLs to send to Resin.
<a href="../ref/http-config.xtp#host">&lt;host&gt;</a> and 
<a href="../ref/http-config.xtp#web-app">&lt;web-app&gt;</a> group the
servlet-mapping tags.  mod_caucho ignores all other tags in the resin.conf.</p>

<p>(mod_caucho does understand
<a href="../ref/resin-config.xtp#include">resin:include</a> and how to
find web.xml, but that's part of the parsing, not part of the dispatch logic.)</p>

<p>When reading the resin.conf, mod_caucho uses only the following tags:</p>
<ul>
<li><a href="../ref/http-config.xtp#host">&lt;host&gt;</a> to select virtual hosts.  The <var/id/> attribute names the host.
<li><a href="../ref/http-config.xtp#web-app">&lt;web-app&gt;</a> to select applications.  The <var/id/> attribute selects a URL prefix.
<li><a href="../ref/app-config.xtp#servlet-mapping">&lt;servlet-mapping&gt;</a> to select URLs.  The <var/url-pattern/> attribute selects URLs.
</ul>

<s3 title="url-pattern">

<p>servlet-mapping's <a href="../ref/app-config.xtp#url-pattern">url-pattern</a>
selects the URLs to pass to Resin.  servlet-mapping and url-pattern
are part of the Servlet 2.3 standard, so there are many references explaining
how it works.</p>

<p>url-pattern can take one of four forms:</p>
<ul>
<li>"<var///>" matches all URLs.  Use this to pass all requests to Resin.
<li>"<var//prefix/url/*/>" matches any URL starting with <var//prefix/url/>,
including <var/prefix/url/> itself.  It does not match <var//prefix/urlfoo/>
because any slash must immediately follow <var/url/>
<li>"<var//exact/path/>" matches only the exact path.  In other words, it
will not match <var//exact/path/bogus/>.
<li>"<var/*.ext/>" matches any URL with the extension <var/ext/>.  Resin
allows path-infos, so <var//foo/bar.ext/path/info/> will also match.
</ul>

</s3>

<s3 title="url-regexp">

<note>mod_caucho does not understand regular expressions.  If you
put regular expressions in your resin.conf, mod_caucho will not send
the request to Resin.  Apache will handle the request itself.</note>

<p>If you want to use regular expressions in servlet-mapping, web-app, or
hosts, you must use Apache-specific configuration to send the request
to Resin.  You can see this by looking at /caucho-status.  /caucho-status
will not display any regular expressions.</p>

</s3>

<s3 title="special servlet-mappings">

<p>There are two special servlet-names which only affect the plugins:
<var/plugin_match/> and <var/plugin_ignore/>.</p>

<p><var/plugin_match/> will direct a request to Resin.
The servlet engine itself
will ignore the plugin_match directive.  You can use plugin_match to
direct an entire subtree to Resin, e.g. to workaround the
regexp limitation, but allow Resin's other servlet-mapping directives
to control which servlets are used.</p>

<p><var/plugin_ignore/> keeps the request at on the web server.  So you
could create a directory <var//static/> where all documents, including JSPs are
served by the web server.</p>

<example>
&lt;!-- send everything under /resin to Resin -->
&lt;servlet-mapping url-pattern='/resin/*'
                 servlet-name='plugin_match'/>

&lt;!-- keep everything under /static at the web server -->
&lt;servlet-mapping url-pattern='/static/*'
                 servlet-name='plugin_ignore'/>
</example>

</s3>

<s3 title="&lt;web-app>">

<p><a href="../ref/http-config.xtp#web-app">web-apps</a> collect servlets and
JSP files into separate applications.  All the servlet-mappings in a
web-app apply only to the URL suffix.</p>

<p>In the following example, every URL starting with /prefix/url maps to
the web-app.  The servlet-mapping only applies to URLs matching the prefix.
</p>

<example>
...
&lt;web-app id='/prefix/url'>
  &lt;servlet-mapping url-pattern='*.foo' .../>
&lt;/web-app>
..
</example>

<p>In the exaple, mod_caucho will match any URL matching /prefix/url/*.foo.
/prefix/url/bar.foo will match, but /test/bar.foo will not match.</p>

<note>Resin standalone allows a <var/regexp/> attribute instead of an
id.  Because mod_caucho does not understand regexps, it will ignore any
web-app with a <var/regexp/> attribute.</note>

<note>web.xml files and war files are treated exactly the same as web-apps
in the resin.conf.</note>

</s3>

<s3 title="&lt;host>">

<p><a href="../ref/resin-config.xtp#host">host</a> blocks configure
<a href="../ref/virtual-host.xtp">virtual hosts</a>.  There's a bit of
extra work for virtual hosts that we'll ignore here.  (Basically, you
need to add Apache <var/ServerName/> directives so Resin knows the name
of the virtual host.)</p>

<p>For dispatching, a host block gathers a set of web-apps.  Each host
will match a different set of URLs, depending on the web-app configuration.
The default host matches any host not matched by a specific rule.</p>

<p>As usual, /caucho-status will show the URLs matched for each host.</p>

<note>mod_caucho does not understand the host <var/regexp/> attribute.
It will ignore all hosts using <var/regexp/>.  To get around this, you can
either configure Apache directly (see below), or configure the default host
with the same set of servlet-mappings.  Since mod_caucho will use the
default host if no others match, it will send the right requests to
Resin.</note>

</s3>

</s2>

<s2 title="/caucho-status shows mod_caucho's URLs">

<p>The special URL <var//caucho-status/> is invaluable in debugging
Resin configurations.  <var//caucho-status/> displays all the resin.conf
patterns, so you can easily scan it to see which URLs mod_caucho is sending
to Resin and which ones are handled by Apache.</p>

</s2>

<s2 title="Dispatching using Apache's http.conf">

<p>You can configure Apache directly, instead of letting mod_caucho dispatch
from the resin.conf file.  If you use this method, you need to make
sure you match the Apache configuration with the Resin configuration.</p>

<note>This technique uses Apache-specific features, so it's not
directly applicable to IIS or iPlanet.</note>

<p>Apache's <var/Location/> and <var/SetHandler/> directives send requests
to Resin.  The mod_caucho handler is <var/caucho-request/>.</p>

<example title=httpd.conf>
LoadModule caucho_module libexec/mod_caucho.so
AddModule mod_caucho.c

CauchoHost localhost 6802
AddHandler caucho-request jsp
&lt;Location /servlet/*>
   SetHandler caucho-request
&lt;/Location>
</example>

<p>Because Apache's <var/SetHandler/> is external to mod_caucho,
/caucho-status will not show any <var/SetHandler/> dispatching.</p>

</s2>
</s1>