RESIN_HOME

RESIN_HOME is the directory containing the Resin binaries and classes. In the default configuration, RESIN_HOME will be the same as SERVER_ROOT, i.e. the document directories and log files are based on RESIN_HOME. A typical location for RESIN_HOME might be /usr/local/resin.

RESIN_HOME is controlled by the command-line and system environment when Resin starts. The heuristic for selecting RESIN_HOME is

1. -resin-home dir command-line argument
2. $RESIN_HOME system environment variable
3. The parent directory of the starting binary. bin/httpd, or bin/httpd.sh will look at its own directory and then use the parent directory as RESIN_HOME.

The Resin binary will set the Java system property resin.home to the value for RESIN_HOME, e.g. by setting -Dresin.home=$RESIN_HOME. If an application starts the Resin main class directly, it should set the resin. home system property.

Contents of RESIN_HOME

Directory/File	Description
bin/	Resin startup binaries
lib/	jar files automatically added to the system classpath. Applications may add third-party library .jar files.
libexec/	JNI *.so files to be automatically loaded
classes/	Optional directory of classes to be added to the system classpath. (Applications should use WEB-INF/classes instead.)
conf/	Directory containing configuration files when RESIN_HOME is the same as SERVER_ROOT.
conf/resin.conf	The main Resin configuration file when RESIN_HOME is the same as SERVER_ROOT.
doc/	Document root when RESIN_HOME is the same as SERVER_ROOT for the default virtual host.
webapps/	War expansion directory when RESIN_HOME is the same as SERVER_ROOT for the default virtual host.
log/	Log directory when RESIN_HOME is the same as SERVER_ROOT.

SERVER_ROOT

SERVER_ROOT is the directory containing the user's configuration, documents, and log files. By default, SERVER_ROOT is the same as RESIN_HOME, but sophisticated users will create a separate directory from the Resin binaries. For example, an ISP might have a separate SERVER_ROOT for each user's JVM. A typical location for SERVER_ROOT might be /usr/local/webroot.

SERVER_ROOT is controlled by the command-line when Resin starts. The heuristic for selecting SERVER_ROOT is:

1. The value of <root-dir> in the <http-server> section of the resin.conf.
2. -server-root dir command-line argument
3. The value of RESIN_HOME.

Contents of SERVER_ROOT

Directory/File	Description
conf/	Directory containing the resin.conf configuration file.
conf/resin.conf	The main Resin configuration file.
cache/	Directory Resin's cache files.
doc/	Document root for the default virtual host.
webapps/	War expansion directory for the default virtual hosts.
log/	Log directory.
WEB-INF/	Application classes and jars common to all virtual hosts.
foo.com/	Root directory for a virtual host.

virtual host root-dir

Each virtual host has its own root directory. The root directory contains virtual host's documents, war directory, and logs.

The virtual host's directory is configured in the resin.conf. root-dir configures the virtual host's root. doc-dir configures the virtual host's document directory.

Contents of the virtual host

Directory/File	Config	Description
webapps/	war-dir	.war expansion directory.
webapps/WEB-INF/	war-dir	Common classes for the virtual host
doc/	doc-dir	document directory.
log/access.log	access-log	per-virtual host access logs
log/error.log	error-log	per-virtual host error logs
log/stdout.log	stdout-log	per-virtual host System.out
log/stderr.log	stderr-log	per-virtual host System.err

webapps (war-dir)

The webapps directory automatically expands .war and .ear files.

Each .war file will be expanded into a web-app as a directory under the webapps directory. webapps/foo.war will expand into webapps/foo. /foo will then be a web-app for the virtual host. So the URL might be http://www.bar.com/foo.

Each .ear file will expand its jars and .war files. The jars will go into webapps/WEB-INF/lib. The .wars will be expanded into webapps.

The resin.conf configures the webapps directory with the war-dir configuration.

<host id="www.bar.com">
  <root-dir>bar.com</root-dir>
  <war-dir>webapps</war-dir>
</host>

.war file

A .war file is a packaged Servlet application. It's just a renamed .jar file of the web-app directory tree. Resin provides a special webapps directory which will automatically expand .war files, configured by the war-dir attribute in the resin.conf's host configuration.

Placing a foo.war in webapps/foo.war will prompt Resin to expand foo.war into webapps/foo/*. Resin will automatically create a new application browsable at the URL http://localhost:8080/foo

You can also use the < war-dir> for development. Just creating a webapps/bar directory will create an application browsable at http://localhost:8080/bar. A small warning, though, any bar.war placed in webapps will delete and replace your webapps/bar directory.

The special .war file ROOT.war can be used to configure the 'root' web-app, i.e. the web-app with no context path. webapps/ROOT is browsed with http://localhost:8080.

Resin always handles all files in a war, even when Resin is used with another webserver like Apache.

web-app directory

Each web application has its own document directory. The files in that directory are served as static file. The WEB-INF subdirectory contains classes and configuration files for the web-app.

Web applications are either configured implicitly by the webapps directory or explicitly in the resin.conf. Any .war files in the webapps directory will create a web application. foo.war will expand into the web-app directory webapps/foo. The WEB-INF directory is in webapps/foo/WEB-INF.

Web applicatoins configured in the resin.conf can be placed anywhere in the filesystem using the app-dir tag.

<host id='www.foo.com'>
  <web-app id='/bar' app-dir='/opt/bar'/>
</host>

The web-apps can also be configured using regular expressions. For example, /~ferg may translate into a web-app in /home/ferg/public_html.

<host id=''>
  <web-app url-regexp='/~([^/]*)'>
    <app-dir>/home/$1/public_html</app-dir>
  </web-app>
</host>

web-app directory contents

Directory/File	Description
test.html	Static HTML file served to user
foo.jsp	JSP file served to user
WEB-INF/	Directory for classes and servlets

WEB-INF

The WEB-INF contains the classes, jars, and configuration files for the web application. WEB-INF is at the root of the web-app's document directory.

Contents of WEB-INF

Directory/File	Description
classes/	Directory containing .class files
lib/	Directory containing .jar files
tld/	Directory containing tag library configuration files.
sessions/	Directory containing persistent sessions.
work/	Directory containing Resin's automatically generated java and class files for JSP, XSL, and EJB.
tmp/	Temporary directory for the web-app.
web.xml	Servlet standard configuration file for the web-app.
resin-web.xml	Resin-specific configuration.
foo.ejb	Resin-specific EJB configuration files.

WEB-INF for hosts and http-server

Hosts and the http-server may also have a WEB-INF directory. The host's WEB-INF will be shared for all web-apps in the virtual host. The http-server's WEB-INF will be shared for all virtual hosts in the server.

The host's WEB-INF directory is in webapps/WEB-INF. The http-server's WEB-INF is in SERVER_ROOT/WEB-INF.

Sites will typically use the host's WEB-INF to share resources, EJB servers, or single-signon authenticators for all applications in a host or in the server.

path-mapping (aliasing)

In the web.xml file, directories and files can be aliased using the path-mapping directive.

aliasing /images to /opt/images

<web-app> <path-mapping> <url-pattern>/images/*</url-pattern> <real-path>/opt/images</real-path> </path-mapping> </web-app>

Path Variable expansion

Paths in configuration variables can use path and regular expression variables.

Variable	Value
$server-root	The root of the server instance. Same as the -server-root argument.
$server-doc	The document root for the server instance.
$host-root	The root directory of the enclosing <host>
$host-doc	The document directory of the enclosing <host>
$app-dir	The app-dir of the enclosing <web-app>
$host0 ... $host9	Regular expression replacement from a host url-regexp.
$app0 ... $app9	Regular expression replacement from a web-app url-regexp.
$0 ... $9	Regular expression replacement for the containing context (host or web-app)
$foo	Java property value from System.getProperty("foo")

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