When used with another web server, Resin serves JSPs and Servlets and the other web server serves static content like html and images.

The web server plugins (mod_caucho and isapi_srun) have two main tasks:

1. Select urls to dispatch to the Java process
2. Pass the request and retrieve the response from the Java process.

ResinConfigServer

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.

servlet-mapping selects URLs

The servlet-mapping tag selects the URLs to send to Resin. <host> and <web-app> group the servlet-mapping tags.

url-pattern

servlet-mapping's url-pattern 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.

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.

url-regexp

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.

special servlet-mappings

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.

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

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

<web-app>

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.

<host>

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 ServerName 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.

/caucho-status shows mod_caucho's URLs

The special URL /caucho-status is invaluable in debugging Resin configurations. /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.

Dispatching using Apache's http.conf

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.

Apache's Location and SetHandler directives send requests to Resin. The mod_caucho handler is caucho-request.

LoadModule caucho_module libexec/mod_caucho.so
AddModule mod_caucho.c

CauchoHost localhost 6802
AddHandler caucho-request jsp
<Location /servlet/*>
   SetHandler caucho-request
</Location>

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