caucho
Resin
FAQ
Reference Guide
Demo
Tutorial

Getting Started
Configuration
IDE
Topics
JSP
XML/XSLT

Basic Config
Directory
Servlets
Filters
Resources
Databases
Messaging
Security Config
Log Config
Taglib Config
Misc resin.conf
Host resin.conf
Port resin.conf
App resin.conf
Summary
Glossary
Index
 Basic Configuration

Configuration
Configuration
Directory

Because the flexibility of Resin's configuration can be overwhelming, we've collected the most important configuration here. Once you understand the basic configuration, you can use it as a framework to attach more detailed configuration as you need it.

You may want to look at:

Configuration Overview

Configuring Resin involves configuring the following:

Resin organizes classes and JNDI resources into a tree. Each node in the tree inherits classes and JNDI resources from its parents and adds it's own classes and resources. So a database jdbc/test configured for the foo.com virtual host would be available for every web-app in the host.

Complete resin.conf Example

The following creates a basic working configuration for a Resin standalone configuration. Resin will compile and load servlets and classes placed in /home/ferg/public_html/WEB-INF/classes and jars placed in in /home/ferg/public_html/WEB-INF/lib.

The url /servlet/test.MyServlet will invoke a servlet in /home/ferg/public_html/WEB-INF/classes/test/MyServlet.class.

The url /hello.jsp will run a JSP in /home/ferg/public_html/hello.jsp.

Example resin.conf
<caucho.com>
<http-server>

<http port='8080'/>

<host id=''>
  <doc-dir>/home/ferg/public_html</doc-dir>

  <war-dir>webapps</war-dir>

  <web-app id='/'>
  </web-app>
</host>

</http-server>
</caucho.com>

Servlet configuration normally belongs in the web.xml in the WEB-INF directory. Resin-specific configuration, e.g. database configuration, belongs in a resin-web.xml file in WEB-INF or in the resin.conf.

Because Resin merges the contents of resin-web.xml, web.xml, and resin.conf, so you can put everything in the resin.conf if that makes your application easier to maintain.

The following web.xml configures the special "invoker" servlet, which lets you call servlets using the classname in the URL like /servlet/qa.MyServlet. In general, it's a better idea to create specific servlet-mappings for each servlet for better security.

Example /WEB-INF/web.xml
<web-app>
  <servlet-mapping>
    <url-pattern>/servlet/*</url-pattern>
    <servlet-name>invoker</servlet-name>
  </servlet-mapping>
</web-app>

Index
caucho.comcaucho
hostEach http-server contains some virtual hosts
httpConfigures the HTTP port for Resin to listen at
http-serverhttp-server contains all configuration for the Resin server
servletDefines a servlet alias for later mapping
servlet-mappingMaps url patterns to servlets
srunConfigures a servlet runner port for Resin to listen at
web-appEach host contains some web applications

http configuration

caucho.com

caucho.com is just a container for any Caucho configuration

http-server

http-server contains all configuration for the Resin server.

The most important configuration variable is app-dir. app-dir configures the document root. app-dir can appear in <http-server>, <host>, and <web-app>. If it's not specified, it defaults to the parent.

Apache Config
<caucho.com>
<http-server>

<app-dir>/usr/local/apache/htdocs</app-dir>

  ...

</http-server>
</caucho.com>
IIS Config
<caucho.com>
<http-server>

<app-dir>d:\inetpub\wwwroot</app-dir>

  ...

</http-server>
</caucho.com>
Resin Config
<caucho.com>
<http-server>

<app-dir>doc</app-dir>

  ...

</http-server>
</caucho.com>

http

Configures the HTTP port for Resin to listen at.

AttributeMeaningDefault
portTCP post to listen torequired
hostTCP interface to listen toall interfaces

<caucho.com>
<http-server>
  <http host='localhost' port='6802'/>
  ...
</http-server>
</caucho.com>

srun

Configures a servlet runner port for Resin to listen at.

AttributeMeaningDefault
portTCP post to listen torequired
hostTCP interface to listen toall interfaces

<caucho.com>
<http-server>
  <srun host='localhost' port='6802'/>
  ...
</http-server>
</caucho.com>

host

Each http-server contains some virtual hosts. Most configurations will use the default host.

<caucho.com>
<http-server>

<host id=''>
  ...
</host>

</http-server>
</caucho.com>

web-app

Each host contains some web applications. A web application is just a container for some servlets. It's closely related to the javax.servlet.ServletContext. Most configurations will use the default web-app.

<caucho.com>
<http-server>

<host id=''>
<web-app id='/'>

...

</web-app>

</host>

</http-server>
</caucho.com>

Servlets

servlet-mapping

Maps url patterns to servlets. servlet-mapping has two children, url-pattern and servlet-name. url-pattern selects the urls which should execute the servlet.

The special servlet-name invoker is used to dispatch servlets by class name. For example, /servlets/test.HelloServlet.

url-patterns
/path/to/servletExact URL match
/prefix/*Matching everything with a prefix
*.jspMatching everything with an extension
/Replace the default servlet

In the following example, the URL /hello-world invokes the servlet

<web-app id='/'>

<servlet>
  <servlet-name>hello</servlet-name>
  <servlet-class>test.HelloWorld</servlet-class>
</servlet>

<servlet-mapping>
  <url-pattern>/hello-world</url-pattern>
  <servlet-name>hello</servlet-name>
</servlet-mapping>

<servlet-mapping>
  <url-pattern>*.xtp</url-pattern>
  <servlet-name>com.caucho.jsp.XtpServlet</servlet-name>
</servlet-mapping>

</web-app>

servlet

Defines a servlet alias for later mapping. More details are in the servlet configuration section.

servlet-nameThe servlet's name (alias)
servlet-classThe servlet's class (defaults to servlet-name)
init-paramInitialization parameters

In the following example, the url /hello.xtp invokes the servlet test.HelloWorld. The servlet will use getInitParameter("title") to get the string "Hello, World".

<web-app id='/'>

<servlet-mapping>
  <url-pattern>/hello.xtp</url-pattern>
  <servlet-name>hello</servlet-name>
</servlet-mapping>

<servlet>
  <servlet-name>hello</servlet-name>
  <servlet-class>test.HelloWorld</servlet-class>
  <init-param title='Hello, World'/>
</servlet>

</web-app>

Formal Description

The following description condenses the full configuration summary.

caucho.com ::= http-server 

http-server ::= http* |
                srun* |
                host*

host ::= war-dir |
         web-app*

web-app ::= servlet-mapping* |
            servlet*

servlet ::= servlet-name |
            servlet-class |
            init-param*

servlet-mapping ::= url-pattern |
                    servlet-name


Configuration
Configuration
Directory
Copyright © 1998-2002 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.