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

The application configuration is based on the Servlet 2.2 deployment descriptor.

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.

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.

resin.conf
<caucho.com> <http-server app-dir='doc'> <http port='8080'/> <host id=''> <web-app id='/test'/> </host> </http-server> </caucho.com>

web.xml

<web-app>
  <servlet servlet-name='hello'
           servlet-class='test.HelloServlet'>
    <init-param greeting='Hello, world'/>
  </servlet>

  <servlet-mapping url-pattern='/hello'
                   servlet-name='hello'/>

  <servlet-mapping url-pattern='/prefix/*'
                   servlet-name='hello'/>

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

<a href="../ref/resin-config.xtp">caucho.com</a> The Resin configuration file is based on XML. The <caucho.com> element encapsulates the entire configuration file. <a href="../ref/resin-config.xtp#http-server">http-server</a> Each resin.conf contains a single <http-server> element that contains the configuration for the web server and servlet engine. All configuration outside the http-server is non-server specific. For example, debug logging configuration and Java compiler configuration belongs outside the http-server element.

Despite its name, 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 http-server.

In the current version of Resin only allows a single http-server. <a href="../ref/app-config.xtp#app-dir">app-dir</a> 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.

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.

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

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

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

Note: JNI. Because of the way Java handles JNI, you should place the Java native classes outside the WEB-INF directories, putting them in resin1.2.x/lib or 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. <a href="../ref/http-config.xtp#http">http</a> 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.

Configurations using Resin as a servlet runner for another web server will use an srun tag to listen for the servlet runner.

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

To configure a virtual host, just copy the default host block and set the id attribute to the host name. You'll probably want to set the app-dir for the new virtual host so it will use a different application directory than the default host. <a href="../ref/http-config.xtp#web-app">web-app</a> web-app (web application) is the core of Resin's jsp and servlet configuration. Each application has its own class loader, ServletContext variable, and WEB-INF directory. web-app uses the same syntax as the servlet 2.2 deployment descriptor with a few optional extensions.

The web-app with 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 app-dir. If unspecified, as in the example, it defaults to the id path below the host's app-dir. A web-app id='foo' starts in resin1.2.x/doc/foo and the WEB-INF will be resin1.2.x/doc/foo/WEB-INF. <a href="../ref/servlet-config.xtp#servlet">servlet</a>

Servlet configuration follows the Servlet 2.2 deployment descriptor configuration. The servlet tag assigns a name to a servlet and specifies its class. Servlets which need configuration will use init-param to configure servlet parameters.

To actually use a servlet, you'll need to add a servlet-mapping tag for each servlet.

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

Servlets and their supporting classes generally belong in WEB-INF/classes or in a jar in WEB-INF/lib. A servlet class test.Hello would belong in 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, resin1.2.x/lib, but they will not be reloaded automatically. <a href="../ref/app-config.xtp#servlet-mapping">servlet-mapping</a>

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

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 caucho-status URL to look at the mapping.

The url-pattern specifies the URLs to match. The four patterns in the Servlet specification are *.foo, /specific, /prefix/*, and /.

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