Note: I'll be using "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".

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.

The servlet-mapping tag selects the URLs to send to Resin. <host> and <web-app> group the servlet-mapping tags. mod_caucho ignores all other tags in the resin.conf.

(mod_caucho does understand resin:include and how to find web.xml, but that's part of the parsing, not part of the dispatch logic.)

When reading the resin.conf, mod_caucho uses only the following tags:

<host> to select virtual hosts. The id attribute names the host.
<web-app> to select applications. The id attribute selects a URL prefix.
<servlet-mapping> to select URLs. The url-pattern attribute selects URLs.

servlet-mapping's url-pattern selects the URLs to pass to Resin. servlet-mapping and url-pattern are part of the Servlet 2.2 standard, so there are many references explaining how it works.

url-pattern can take one of four forms:

"/" matches all URLs. Use this to pass all requests to Resin.
"/prefix/url/*" matches any URL starting with /prefix/url, including prefix/url itself. It does not match /prefix/urlfoo because any slash must immediately follow url
"/exact/path" matches only the exact path. In other words, it will not match /exact/path/bogus.
"*.ext" matches any URL with the extension ext. Resin allows path-infos, so /foo/bar.ext/path/info will also match.

Note: mod_caucho does not understand regular expressions. This is a limitation in Resin 1.2 that will likely be fixed in Resin 1.3. If you put regular expressions in your resin.conf, mod_caucho will not send the request to Resin. Apache will handle the request itself.

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.

Note: The special servlet-mappings are only available in the Resin 1.2.s001215 snapshot or later.

There are two special servlet-names which only affect the plugins: plugin_match and plugin_ignore.

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.

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

<servlet-mapping url-pattern='/resin/*' servlet-name='plugin_match'/>  <servlet-mapping url-pattern='/static/*' servlet-name='plugin_ignore'/>

web-apps collect servlets and JSP files into separate applications. All the servlet-mappings in a web-app apply only to the URL suffix.

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.

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

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.

Note: Resin standalone allows a regexp attribute instead of an id. Because mod_caucho does not understand regexps, it will ignore any web-app with a regexp attribute.

Note: web.xml files and war files are treated exactly the same as web-apps in the resin.conf.

host blocks configure virtual hosts. There's a bit of extra work for virtual hosts that we'll ignore here. (Basically, you need to add Apache ServletName directives so Resin knows the name of the virtual host.)

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.

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

Note: mod_caucho does not understand the host regexp attribute. It will ignore all hosts using 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.