As a child of web-app, overrides the definition in the host that the web-app is deployed in. As a child of host, overrides the definition in the server that the host is in.

The default archive format is

path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

The access log formatting variables follow the Apache variables:

format patterns
PATTERN	DESCRIPTION
%b	result content length
%D	time taken to complete the request in microseconds (since 3.0.16)
%h	remote IP addr
%{xxx}i	request header xxx
%{xxx}o	response header xxx
%{xxx}c	cookie value xxx
%n	request attribute
%r	request URL
%s	status code
%S	requested session id
%{xxx}t	request date with optional time format string.
%T	time taken to complete the request in seconds
%u	remote user
%U	request URI
%v	name of the virtual host serving the request

The default format is:

default access log format

"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

resin:type allows for custom logging. Applications can extend a custom class from com.caucho.http.log.AccessLog. Resin-IoC initialization can be used to set bean parameters in the custom class.

<access-log> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
path	Output path for the log entries, see "Log Paths".	required
path-format	Selects a format for generating path names. The syntax is the same as for archive-format.	optional
archive-format	the format for the archive filename when a rollover occurs, see Rollovers.	see below
auto-flush	true to flush the memory buffer with each request.	false
auto-flush-time	sets time interval for flushing the memory buffers	60s
exclude	access logging exclude patterns for request URIs. Access to matching URIs does not get logged.	none
format	Access log format.	see above
hostname-dns-lookup	log the dns name instead of the IP address (has a performance hit).	false
rollover-period	how often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See "Rollovers".	none
rollover-size	maximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See "Rollovers".	1mb
rollover-count	maximum number of rollover files before the oldest ones get overwritten. See "Rollovers".	1mb
resin:type	a class extending com.caucho.server.log.AccessLog for custom logging	com.caucho.server.log.AccessLog
init	Resin-IoC initialization for the custom class	n/a

<access-log> schema

element access-log {
  path?
  & path-format?
  & archive-format?
  $amp;auto-flush?
  & auto-flush-time?
  & exclude*
  & format?
  & hostname-dns-lookup?
  & rollover-period?
  & rollover-size?
  & rollover-count?
  & resin:type?
  & init?
}

Example: <access-log> in host configuration

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">

  <host id="">
    <access-log path='log/access.log'>
      <rollover-period>2W</rollover-period>
    </access-log>
  </host>
</cluster>
</resin>

Example: custom access log

<resin xmlns="http://caucho.com/ns/resin">

<cluster id="app-tier">

  <host id='foo.com'>

    <access-log>
      <test:MyLog xmlns:test="urn:java:test">
                 path='${resin.root}/foo/error.log'
                 rollover-period='1W'>
          <test:foo>bar</test:foo>
      </test:MyLog>
    </access-log>
    ...
  </host>

</cluster>
</resin>

<ear-deploy>

child of host,web-app

Specifies ear expansion.

ear-deploy can be used in web-apps to define a subdirectory for ear expansion.

<ear-deploy> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
archive-path	The path to the directory containing ear files	path
ear-default	resin.xml default configuration for all ear files, e.g. configuring database, JMS or EJB defaults.
expand-cleanup-fileset	Specifies the files which should be automatically deleted when a new .ear version is deployed.
expand-directory	directory where ears should be expanded	value of path
expand-prefix	automatic prefix of the expanded directory	_ear_
expand-suffix	automatic suffix of the expanded directory
lazy-init	if true, the ear file is only started on first access	false
path	The path to the deploy directory	required
redeploy-mode	"automatic" or "manual". If automatic, detects new .ear files automatically and deploys them.	automatic
url-prefix	optional URL prefix to group deployed .ear files

<ear-deploy> schema

element ear-deploy {
  path
  & archive-directory?
  & ear-default?
  & expand-cleanup-fileset?
  & expand-directory?
  & expand-path?
  & expand-prefix?
  & expand-suffix?
  & lazy-init?
  & redeploy-mode?
  & require-file*
  & url-prefix?
}

<error-page>

child of web-app

Allows applications to customize the response generated for errors. By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages. With <error-page>, you may specify a handler page for these errors.

The handler page has several request attributes set so that it may log, display, or otherwise use information about the error that occured. The following table describes the available attributes.

Request attributes for error handling
ATTRIBUTE	TYPE
javax.servlet.error.status_code	java.lang.Integer
javax.servlet.error.message	java.lang.String
javax.servlet.error.request_uri	java.lang.String
javax.servlet.error.servlet_name	java.lang.String
javax.servlet.error.exception	java.lang.Throwable
javax.servlet.error.exception_type	java.lang.Class

<error-page> Attributes
ATTRIBUTE	DESCRIPTION
error-code	Select the error page based on an HTTP status code
exception-type	Select the error page based on a Java exception
location	The error page to display

<error-page> schema

element error-page {
  (error-code | exception-type)?
  & location
}

Catching File Not Found

<web-app xmlns="http://caucho.com/ns/resin">
  <error-page>
    <error-code>404</error-code>
    <location>/file_not_found.jsp</location>
  </error-page>
</web-app>

Catching Exceptions

<web-app xmlns="http://caucho.com/ns/resin">
   <error-page exception-type="java.lang.NullPointerException"
               location="/nullpointer.jsp"/>
</web-app>

Using request attributes to obtain information about the request that caused the error

<%@ page session="false" isErrorPage="true" %>

<html>
<head><title>404 Not Found</title></head>
<body>
<h1>404 Not Found</h1>

The url <code>${requestScope["javax.servlet.error.request_uri"]}</code> 
was not found.
</body>
</html>

<host-alias>

child of host

<host-alias> defines a URL alias for matching HTTP requests. Any number of <host-alias> can be used for each alias.

The host-alias can be used either in the resin.xml or in a host.xml when use host-deploy together with resin:import.

Since the <host-deploy> and <host> tags lets you add a host.xml file to customize configuration, the <host-alias> can also fit in the custom host.xml page.

<host-alias> schema

element host-alias {
  string
}

Example: host-alias in the resin.xml

<resin xmlns="http://caucho.com">
<cluster id="">

  <host id="www.foo.com" root-directory="/var/www/foo.com">
    <host-alias>foo.com</host-alias>

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

</cluster>
</resin>

Example: host-alias in a /var/www/hosts/foo/host.xml

<host xmlns="http://caucho.com">

  <host-name>www.foo.com</host-name>
  <host-alias>foo.com</host-alias>

  <web-app id="" root-directory="htdocs"/>

</host>

<host-alias-regexp>

child of host

<host-alias-regexp> defines a regular expression for matching URLs for a given virtual host.

<host-alias-regexp> schema

element host-alias-regexp {
  string
}

Example: host-alias-regexp in the resin.xml

<resin xmlns="http://caucho.com">
<cluster id="">

  <host id="www.foo.com" root-directory="/var/www/foo.com">
    <host-alias-regexp>.*foo.com</host-alias-regexp>

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

</cluster>
</resin>

<host-default>

child of cluster

Defaults for a virtual host.

The host-default can contain any of the host configuration tags. It will be used as defaults for any virtual host.

<host-deploy>

child of cluster

<host-deploy> configures an automatic deployment directory for virtual hosts.

The host-deploy will add an EL variable ${host.name}, referring to the name of the host jar file.

<host-deploy> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
archive-directory	path to the archive directory	path
path	path to the deploy directory	required
expand-cleanup-fileset	an ant-style fileset defining which directories to cleanup when an archive is redeployed
expand-directory	path to the expansion directory	path
host-default	defaults for the expanded host
host-name	the default hostname, based on the directory	${name}

<host-deploy> schema

element host-deploy {
  archive-directory?
  & expand-cleanup-fileset?
  & expand-directory?
  & host-default?
  & host-name?
  & path?
}

The following example configures /var/www/hosts as a host deployment directory. Each virtual host will have a webapps directory for .war deployment. So the directory /var/www/hosts/www.foo.com/webapps/bar/test.jsp would serve the URL http://www.foo.com/bar/test.jsp.

<host-deploy>

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
    <root-directory>/var/www</root-directory>

    <host-deploy path="hosts">
      <host-default>
        <resin:import path="host.xml" optional="true"/>

        <web-app-deploy path="webapps"/>
      </host-default>
    </host-deploy>
  </cluster>
</resin>

<host-name>

child of host

<host-name> defines the canonical name for a virtual host. The <host-name> will be used in Resin's logging, management, and is available in the host's variables.

<host-name> schema

element host-name {
  string
}

<redeploy-mode>

child of web-app

default automatic

<redeploy-mode> specifies how Resin handles updates to web-apps and .war files. By default, Resin restarts web-apps when classes or configuration files change.

<redeploy-mode> Attributes
MODE	DESCRIPTION
automatic	checks for redeployment and auto-redeploy if modified
manual	does not check for redeployment. Only checks if manual (JMX)

<redeploy-mode> schema

element redeploy-mode {
  automatic | manual
}

<root-directory>

child of resin,cluster,host,web-app

<root-directory> specifies the base directory for the contexts. All EL-style directory paths are relative to the root-directory.

<root-directory> schema

element root-directory {
  r_path-Type
}

Example: cluster root-directory

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <root-directory>/var/www/app-tier</root-directory>

        <server id="a" ...>

        <host host-name="www.foo.com">
    </cluster>
</resin>

<secure-host-name>

<secure-host-name> sets a host-name or URL to be used for secure redirection. For some security configurations, Resin needs to redirect from an insecure site to a secure one. The <secure-host-name> configures the host to redirect to.

See Resin security.

<secure-host-name> schema

element secure-host-name {
  string
}

<startup-mode>

child of host,web-app,web-app-deploy

<startup-mode> configures the virtual-host's behavior on Resin startup, either "automatic", "lazy" or "manual".

<startup-mode> Attributes
MODE	DESCRIPTION
automatic	automatically start when Resin starts
lazy	start only when the first request is received
manual	start only when JMX administration requests a start

<startup-mode> schema

element startup-mode {
  string
}

<web-app>

child of host,web-app

web-app configures a web application.

When specified by id, the application will be initialized on server start. When specified by url-regexp, the application will be initialized at the first request. This means that load-on-startup servlets may start later than expected for url-regexp applications.

<web-app> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
active-wait-time	how long a thread should wait for the web-app to initialize before returning a 503-busy.	15s
archive-path	Specifies the location of the web-app's .war file.	n/a
context-path	Specifies the URL prefix for the web-app.	the id value
id	The url prefix selecting this application.	n/a
redeploy-mode	'automatic' or 'manual', see redeploy-mode	automatic
redeploy-check-interval	how often to check the .war archive for redeployment	60s
root-directory	The root directory for the application, corresponding to a url of /id/. A relative path is relative to the root-directory of the containing host. Can use regexp replacement variables.	A relative path constricted with the id or the regexp match
startup-mode	'automatic', 'lazy', or 'manual', see startup-mode	automatic
startup-priority	specifies a priority for web-app startup to force an ordering between webapps	-1
url-regexp	A regexp to select this application.	n/a

The following example creates a web-app for /apache using the Apache htdocs directory to serve pages.

<host id=''>
  <web-app id='/apache' root-directory='/usr/local/apache/htdocs'>

  ...

</host>

The following example sets the root web-app to the IIS root directory.

  <web-app id='/' root-directory='C:/inetpub/wwwroot'>

When the web-app is specified with a url-regexp, root-directory can use replacement variables ($2).

In the following, each user gets his or her own independent application using ~user.

<host id=''>

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

    ...

  </web-app>

</host>

<web-app-default>

child of cluster

<web-app-default> defines default values for any web-app in the cluster.

Example: web-app-default

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">

        <web-app-default>
            <servlet servlet-name="resin-php"
                     servlet-class="com.caucho.quercus.servlet.QuercusServlet"/>

            <servlet-mapping url-pattern="*.php"
                             servlet-name="resin-php"/>
        </web-app-default>

        <host id="">
          ...
    </cluster>
</resin>

<web-app-deploy>

child of host,web-app

Specifies war expansion.

web-app-deploy can be used in web-apps to define a subdirectory for war expansion. The tutorials in the documentation use web-app-deploy to allow servlet/tutorial/helloworld to be an independent war file.

<web-app-deploy> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
archive-directory	directory containing the .war files	value of path
dependency-check-interval	How often to check the .war files for a redeploy	60s
expand-cleanup-fileset	defines the files which should be automatically deleted when an updated .war expands	all files
expand-directory	directory where wars should be expanded	value of path
expand-prefix	prefix string to use when creating the expansion directory, e.g. _war_
expand-suffix	prefix string to use when creating the expansion directory, e.g. .war
path	The path to the webapps directory	required
redeploy-mode	"automatic" or "manual"	automatic
require-file	additional files to use for dependency checking for auto restart
startup-mode	"automatic", "lazy" or "manual"	automatic
url-prefix	url-prefix added to all expanded webapps	""
versioning	if true, use the web-app's numeric suffix as a version	false
web-app-default	defaults to be applied to expaned web-apps
web-app	overriding configuration for specific web-apps

<web-app-deploy> schema

element web-app-deploy {
  archive-directory?
  expand-cleanup-fileset?
  expand-directory?
  expand-prefix?
  expand-suffix?
  path?
  redeploy-check-interval?
  redeploy-mode?
  require-file*
  startup-mode?
  url-prefix?
  versioning?
  web-app-default*
  web-app*
}

Overriding web-app-deploy configuration

The web-app-deploy can override configuration for an expanded war with a matching <web-app> inside the <web-app-deploy>. The <root-directory> is used to match web-apps.

Example: resin.xml overriding web.xml

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">
<host id="">

<web-app-deploy path="webapps">
  <web-app context-path="/wiki"
              root-directory="wiki">
    <context-param database="jdbc/wiki">
  </web-app>
</web-app-deploy>

</host>
</cluster>
</resin>

versioning

The versioning attribute of the <web-app-deploy> tag improves web-app version updates by enabling a graceful update of sessions. The web-apps are named with numeric suffixes, e.g. foo-10, foo-11, etc, and can be browsed as /foo. When a new version of the web-app is deployed, Resin continues to send current session requests to the previous web-app. New sessions go to the new web-app version. So users will not be aware of the application upgrade.