<document>
  <header>
    <product>resin</product>
    <resin-2.0>$resin/java_tut/plugin-dispatch.xtp</resin-2.0>
    <title>How the Plugins Dispatch to Resin</title>
    <description>
      <p>When used with another web server, Resin serves JSPs and Servlets
        and the other web server serves static content like html and
        images.</p>

      <p>The web server plugins (mod_caucho and isapi_srun) 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>"mod_caucho" is used to mean all the plugins.  All of the plugins
        work the same, so "mod_caucho" is just a shorthand for
        "mod_caucho and isapi_srun".</note>
    </description>


  </header>

  <body>
    <summary/>

<section title="ResinConfigServer">

<p>mod_caucho discovers its configuration by contacting
the ResinConfigServer specified in the httpd.conf or resin.ini.
The ResinConfigServer can be any Resin server.  When a user requests a URL,
mod_caucho uses the configuration it has determined from the ResinConfigServer
to determine whether Resin or Apache should handle the request. That decision
is based on the configuration in the ResinConfigServer's resin.conf.</p>

</section>

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

<p>The <a href="doc|config|webapp#servlet-mapping">servlet-mapping</a>
tag selects the URLs to send to Resin.
<a href="doc|config|resin#host">&lt;host&gt;</a> and 
<a href="doc|config|webapp">&lt;web-app&gt;</a> group the
servlet-mapping tags.</p>

<section title="url-pattern">

<p>servlet-mapping's <a href="doc|config|webapp#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>

</section>

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

</section>

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

</section>

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

<p><a href="doc|config|webapp">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>

</section>

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

<p><a href="doc|config|resin#host">host</a> blocks configure
<a href="doc|config|virtual-host">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>

</section>

</section>

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

</section>

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

</section>
  </body>
</document>
