<title>Servlet Configuration</title>

<p/>Resin configuration is based on the <var/resin.conf/> file located
in <var/resin1.2.x/conf/resin.conf/>.  It's XML-based, although it
allows for some non-XML laziness like omitting quotes from attributes.

<p/>The application configuration is based on the Servlet 2.2
deployment descriptor.

<p/>The configuration file parses into a (key, value) structure.  LISP
fans will recognize it as similar to an A-list and Windows fans will
recognize it as similar to the NT registry.  Unlike either, though,
multiple items with the same key are allowed.

<p/><note>Because the internal format has less structure than XML does,
you can use either an element-based configuration or an
equivalent attribute-based configuration.  You should use whichever
configuration simplifies your maintenance.  The following example uses
the element-based configuration exclusively.</note>

<example title="resin.conf">
&lt;caucho.com>
&lt;http-server app-dir='doc'>
  &lt;http port='8080'/>

  &lt;host id=''>
    &lt;web-app id='/test'/>
  &lt;/host>
&lt;/http-server>
&lt;/caucho.com>
</example>

<example title="web.xml">
&lt;web-app>
  &lt;servlet servlet-name='hello'
           servlet-class='test.HelloServlet'>
    &lt;init-param greeting='Hello, world'/>
  &lt;/servlet>

  &lt;servlet-mapping url-pattern='/hello'
                   servlet-name='hello'/>

  &lt;servlet-mapping url-pattern='/prefix/*'
                   servlet-name='hello'/>

  &lt;servlet-mapping url-pattern='*.hello'
                   servlet-name='hello'/>
&lt;/web-app>
</example>

<subsection>
  <title><a href="../ref/resin-config.xtp">caucho.com</a></title>

The Resin configuration file is based on XML.  The
<var/&lt;caucho.com>/> element encapsulates the entire
configuration file.

</subsection>


<subsection>
  <title><a href="../ref/resin-config.xtp#http-server">http-server</a></title>

Each resin.conf contains a single <var/&lt;http-server>/> element that
contains the configuration for the web server and servlet engine.  All
configuration outside the <var/http-server/> is non-server specific.
For example, debug logging configuration and Java compiler
configuration belongs outside the <var/http-server/> element.

<p/>Despite its name, <var/http-server/> contains configuration for
the standalone HTTP server and the servlet runner.  In fact, you can
listen to multiple HTTP and servlet runner ports in the name
<var/http-server/>.

<p/>In the current version of Resin only allows a single <var/http-server/>.

</subsection>

<subsection>
  <title><a href="../ref/app-config.xtp#app-dir">app-dir</a></title>

<var/app-dir/> configures the application directory, which contains
the documents, the servlets, the bean classes, and some extra
configuration files like web.xml and taglib.tld.  For many, the
app-dir is the most important configuration.  For example, if you're
using Apache or IIS, you'll change app-dir to point to the Apache
htdocs or the IIS inetpub/wwwroot.

<p/><var/app-dir/> can be used in the http-server, as above, in the host and
in the web-app.  If unspecified, it defaults to the directory of the
enclosing block.

<p/>The sample resin.conf in the distribution points to an
app-dir <var/doc/>.  If you start Resin from the distribution, you can
put a hello.jsp in <var/resin1.2.x/doc/hello.jsp/> and you'll view it
from a browser using <var/http://localhost:8080/hello.jsp/>.

<p/>Application servlets and classes belong in <var/WEB-INF/classes/> and jars
belong in <var/WEB-INF/lib/>.  Resin will automatically reload a class
placed in either location.  External jars, for example a database
driver, should be put in <var/resin1.2.x/lib/> instead.

<p/>The <var/WEB-INF/> directory is hidden by the web server.  So, it
is not possible for a browser to look at anything in that directory.

<p/><b>Note: JNI</b>.  Because of the way Java handles JNI, you should
place the Java <var/native/> classes outside the <var/WEB-INF/>
directories, putting them in <var/resin1.2.x/lib/> or
<var/resin1.2.x/classes/> instead.  That means you'll need to restart
Resin when you change those classes, so you should only put the
interface classes outside WEB-INF.

</subsection>

<subsection>
  <title><a href="../ref/http-config.xtp#http">http</a></title>

In Resin 1.2, you must specify each port and protocol for the web
server.  In the example, Resin will listen to port 8080 using the
HTTP protocol.  Earlier versions of Resin would listen to port 8080 by
default.

<p/>Configurations using Resin as a servlet runner for another web
server will use an <a href="../ref/http-config.xtp#srun">srun</a> tag
to listen for the servlet runner.

<p/>Resin 1.2 allows multiple <var/http/> and <var/srun/> tags.  A
virtual host configuration might use separate <var/http/> tags for
each IP interface on the server.  A load balancing configuration will
use several <var/srun/> tags, each representing a different backend
server, and selected by the <a href="../ref/http-config.xtp#srun">id</a> attribute.

</subsection>

<subsection>
  <title><a href="../ref/http-config.xtp#host">host</a></title>

The <var/host/> element contains configuration for a virtual host.
The virtual host with <var/id=''/> is the default virtual host.  If
Resin doesn't match any other host, it will use the configuration in
the default virtual host.  This example and most configurations will
use the default virtual host.

<p/>To configure a virtual host, just copy the default <var/host/>
block and set the <var/id/> attribute to the host name.  You'll
probably want to set the <a
href="../ref/app-config.xtp#app-dir">app-dir</a>
for the new virtual host
so it will use a different application directory than the default host.

</subsection>

<subsection>
  <title><a href="../ref/http-config.xtp#web-app">web-app</a></title>

<var/web-app/> (web application) is the core of Resin's jsp and
servlet configuration.  Each application has its own class loader,
ServletContext variable, and <var/WEB-INF/> directory.
web-app uses the same syntax as the servlet 2.2
deployment descriptor with a few optional extensions.

<p/>The web-app with <var/id='/'/> is the default web application.
It's a good idea not to go overboard in creating web-apps.  Most
sites should just use the single default.  Each web-app has its
own <a href="../ref/app-config.xtp#app-dir">app-dir</a>.  If
unspecified, as in the example, it defaults to the <var/id/> path
below the host's app-dir.  A web-app <var/id='foo'/> starts
in <var/resin1.2.x/doc/foo/> and the WEB-INF will
be <var/resin1.2.x/doc/foo/WEB-INF/>.

</subsection>

<subsection>
  <title><a href="../ref/servlet-config.xtp#servlet">servlet</a></title>

<p/>Servlet configuration follows the Servlet 2.2 deployment
descriptor configuration.  The
<a href="../ref/servlet-config.xtp#servlet">servlet</a> tag assigns a 
name to a servlet and specifies its class.  Servlets which need
configuration will use
<a href="../ref/servlet-config.xtp#servlet">init-param</a> to configure
servlet parameters.

<p/>To actually use a servlet, you'll need to add a
<a href="../ref/app-config.xtp#servlet-mapping">servlet-mapping</a> tag
for each servlet.

<p/>Each <var/servlet/> tag specifies a separate servlet instance.
You can create several servlet instances, each with different init
parameters and different names, by creating multiple <var/servlet/>
tags.

<p/>Servlets and their supporting classes generally
belong in <var/WEB-INF/classes/> or in a jar in <var/WEB-INF/lib/>.
A servlet class <var/test.Hello/> would belong in
<var/WEB-INF/classes/test/Hello.class/>.
Resin will automatically reload the servlets when
they change.  You can put servlets and their classes in the system
classpath, for example, <var/resin1.2.x/lib/>, but they will not be
reloaded automatically.

</subsection>

<subsection>
  <title><a
href="../ref/app-config.xtp#servlet-mapping">servlet-mapping</a></title>

<p/><var/servlet-mapping/> specifies the URLs that invoke a servlet.
The longest match between the URL and all the <var/servlet-mapping/>
entries will select the servlet.  If none of the
<var/servlet-mapping/> entries match, Resin will serve the URL as a
static file.

<p/>With a web-server like Apache, the servlet-mapping entries
determine which URLs belong to Resin and which belong to Apache.  Any
match belongs to Resin and a non-match will belong to Apache.  You can
use the special <var/caucho-status/> URL to look at the mapping.

<p/>The <a href="../ref/app-config.xtp#url-pattern">url-pattern</a>
specifies the URLs to match.  The four patterns in the Servlet
specification are <var/*.foo/>, <var//specific/>, <var//prefix/*/>,
and <var///>.

<p/>The <var/servlet-name/> in the <var/servlet-mapping/> matches a
<var/servlet-name/> in a <var/servlet/>.  As a Resin extension, you
can specify all the <var/servlet/> configuration in the
<var/servlet-mapping/> itself, avoiding the double entry.


</subsection>
