	<document>
<header>
  <product>resin</product>
  <title>references</title>
  <description>
  <p>Complete reference documentation</p>
  </description>
</header>
<body>
<reference-legend/>
<localtoc/>
<defun title="AbstractAuthenticator" name="AbstractAuthenticator">
<description>
<p>
While this case is rare, it may sometimes be useful to
create your own Resin custom authenticator (for example
to use a legacy resource as an authentication store). The
Resin security framework provides an abtract base class (<a
javadoc="com.caucho.security.AbstractAuthenticator"/>) that
you can extend to do this.
</p>
<p>
The following is a simple example that you can use a starting point for your 
application:
</p>
</description>
<example title="WEB-INF/resin-web.xml - Custom Authenticator Configuration">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:foo="urn:java:com.caucho.foo">
  ...
  &lt;foo:MyAuthenticator>
    &lt;foo:foo>bar&lt;/foo:foo>
  &lt;/foo:MyAuthenticator>
  ...
&lt;/web-app>
</example>
<example title="MyAuthenticator.java">
package com.foo;

import com.caucho.security.AbstractAuthenticator;
import com.caucho.security.PasswordUser;

public class MyAuthenticator extends AbstractAuthenticator {
  private PasswordUser _user;

  public MyAuthenticator()
  {
    _user = new PasswordUser("harry", "quidditch",
                             new String[] { "user" });
  }

  public PasswordUser getPasswordUser(String userName)
  {
    if (userName.equals(_user.getName()))
      return _user;
    else
      return null;
  }
}
</example>
</defun>

<defun title="&lt;accept-listen-backlog>" name="accept-listen-backlog" version="Resin 3.1">
<parents>http, connection-port, protocol</parents>
<default>4000</default>

<description>
<p>&lt;accept-listen-backlog> configures operating system TCP listen
queue size for the port.</p>

<p>When a browser connects to a server, the server's operating
system handles the TCP initialization before handing the socket to
the server's application.  The operating system will hold the opened
connections in a small queue, until the application is ready to
receive them.  When the queue fills up, the operating system will
start refusing new connections.</p>

</description>

</defun>

<defun title="&lt;accept-thread-max>" name="accept-thread-max" version="Resin 3.1">
<parents>http, connection-port, protocol</parents>
<default>10</default>
<description>

<p>&lt;accept-thread-max> configures the maximum number of 
threads listening for new connections on this port.  &lt;accept-thread-max>
works with &lt;accept-thread-min> to handle spiky loads without
creating and destroying too many threads.</p>

<p>Socket connections are associated with a thread which handles
the request.  In Resin, a number of threads wait to accept a new
connection and then handle the request.  &lt;accept-thread-max>
specifies the maximum number of threads which are waiting for
a new connection.</p>

<p>Larger values handle spiky loads better but require more threads
to wait for the connections.  Smaller values use less threads, but may
be slower handling spikes.</p>

</description>

</defun>

<defun title="&lt;accept-thread-min>" name="accept-thread-min" version="Resin 3.1">
<parents>http, connection-port, protocol</parents>

<description>
<p>&lt;accept-thread-min> configures the minimum number of 
threads listening for new connections on this port   &lt;accept-thread-min>
works with &lt;accept-thread-max> to handle spiky loads without
creating and destroying too many threads.</p>

<p>Socket connections are associated with a thread which handles
the request.  In Resin, a number of threads wait to accept a new
connection and then handle the request.  &lt;accept-thread-min>
specifies the minimum number of threads which are waiting for
a new connection.  If many connections appear rapidly with a small
value of &lt;accept-thread-min>, the application
may pause until a new thread is available for the new connection.</p>

<p>Larger values handle spiky loads better but require more threads
to wait for the connections.  Smaller values use less threads, but may
be slower handling spikes.</p>
</description>

</defun>


<defun title="&lt;access-log>" version="Resin 4.0" name="access-log">
<parents>cluster, cluster-default, server, server-default, host, host-default, web-app, web-app-default</parents>

<description>
<p>&lt;access-log> configures the access log file.</p>

<p>As a child of <a config-tag="web-app"/>, overrides the
definition in the <a config-tag="host"/> that the web-app is
deployed in. As a child of <a config-tag="host"/>, overrides the
definition in the <a config-tag="server"/> that the host is
in.</p>

<p>The default archive format is
</p><pre>
  <var>path</var> + ".%Y%m%d" or
  <var>path</var> + ".%Y%m%d.%H" if rollover-period &lt; 1 day.
</pre>

<p>The access log formatting variables follow the Apache variables:</p>

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

<p>The default format is:</p>

<def title="default access log format">
"%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\" \"%{User-Agent}i\""
</def>

<p><var>resin:type</var> allows for custom logging.  Applications can
extend a custom class from <a javadoc="com.caucho.http.log.AccessLog"/>.  
<a doc="admin/config-candi.xtp">Resin-IoC initialization</a> can be used to set bean
parameters in the custom class.</p>


</description>

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

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

<example title="Example: &lt;access-log> in host configuration">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="app-tier">

  &lt;host id=""&gt;
    &lt;access-log path='log/access.log'&gt;
      &lt;rollover-period&gt;2W&lt;/rollover-period&gt;
    &lt;/access-log&gt;
  &lt;/host>
&lt;/cluster&gt;
&lt;/resin&gt;
</example>

<example title="Example: custom access log">
&lt;resin xmlns="http://caucho.com/ns/resin">

&lt;cluster id="app-tier">

  &lt;host id='foo.com'&gt;

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

&lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;active-wait-time>" name="active-wait-time">
<parents>web-app</parents>

<description>
<p>&lt;active-wait-time> sets a 503 busy timeout for requests
trying to access a restarting web-app.  If the timeout expires
before the web-app complete initialization, the request will return
a 503 Busy HTTP response.</p>
</description>

<schema>
element active-wait-time {
  r_period-Type
}
</schema>

</defun>

<defun title="&lt;address>" name="address" version="Resin 3.1">
<parents>server</parents>
<default>127.0.0.1</default>
<description>
<p>The server &lt;address> defines the IP interface for Resin
cluster communication and load balancing.  It will be an
internal IP address like 192.168.* for a clustered configuration
or 127.* for a single-server configuration.  No wild cards are allowed
because the other cluster servers and load balancer use the address
to connect to the server.</p>
</description>
<example title="server address">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;http port="80"/>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.1.1" port="6800"/>
    &lt;server id="web-b" address="192.168.1.2" port="6800"/>

    ...
  &lt;/cluster>

  &lt;cluster id="app-tier"&gt;
    &lt;server id="app-a" address="192.168.2.11" port="6800"/>
    &lt;server id="app-b" address="192.168.2.12" port="6800"/>

    ...
  &lt;/cluster>
&lt;/resin>
</example>
</defun>

<defun title="&lt;allow-forward-after-flush>" name="allow-forward-after-flush">
<parents>web-app</parents>

<description>
<p>The &lt;allow-forward-after-flush> flag configures whether
IllegalStateExcdeption is thrown when using forward() method after
response has been committed. Flag configures behavior of servlet and
jsp.</p>
</description>

<schema>
element allow-forward-after-flush {
  r_boolean-Type
}
</schema>

</defun>
  
<defun title="&lt;allow-servlet-el>" name="allow-servlet-el">
<parents>web-app</parents>

<description>
<p>The &lt;allow-servlet-el> flag configures whether &lt;servlet>
tags allow EL expressions in the init-param.</p>
</description>

<schema>
element allow-servlet-el {
  r_boolean-Type
}
</schema>

</defun>

<defun title="&lt;archive-path>" name="archive-path">
<parents>web-app</parents>

<description>
<p>&lt;archive-path> configures the location of the web-app's .war file.
In some configurations, the .war expansion might not
use the <var>webapps/</var> directory, but will still want automatic
war expantion.</p>
</description>

<schema>
element archive-path {
  r_path-Type
}
</schema>

<example title="Example: resin.xml explicit archive location">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">

  &lt;host id="">

    &lt;web-app id="/foo"
             root-directory="/var/resin/foo"
             archive-path="/var/resin/wars/foo.war"/>

  &lt;/host>
&lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;auth-constraint>" name="auth-constraint" version="Servlet">
<parents>security-constraint</parents>

<description>
<p>Requires that authenticated users fill the specified role.
In Resin's JdbcAuthenticator, normal users are in the "user" role.
Think of a role as a group of users.</p>

<p>The roles are defined by the authenticators (see <a href="admin/security-overview.xtp">Resin security</a>).  When using Resin's &lt;resin:AdminAuthenticator>
as a default, the role name is <var>resin-admin</var>.  (See
<a href="admin/resin-admin.xtp">Resin management</a>.)</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>role-name</td>
  <td>Roles which are allowed to access the resource.</td>
</tr>
</attributes>

<schema>
element auth-constraint {
  description*,

  role-name*
}
</schema>

<!-- XXX URI
<p>The following example protects the /admin subdirectory of a web-app
by requiring a user to logon with Resin's &lt;management> users, i.e.
using the same requirement as /resin-admin.</p>

<example title="Example: WEB-INF/resin-web.xml auth constraints">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;login uri="basic:"/>

  &lt;security-constraint url-pattern="/admin/*">
    &lt;auth-constraint role-name="resin-admin"/>
  &lt;/security-constraint>

&lt;/web-app>
</example>
-->

</defun>

<defun title="&lt;authenticator>" version="Resin 3.1" name="authenticator">
<parents>cluster, host, web-app</parents>
<!-- deprecated -->

<description>
<p>The &lt;authenticator> tag as been replaced by CDI-style
authenticator configuration. It exists only for backward compatibility.
To upgrade, see the authenticator-specific tags like <a href="#resin:XmlAuthenticator">resin:XmlAuthenticator</a>.</p>

<p>The new name will be the old class="..." name. So class="com.caucho.security.XmlAuthenticator"
becomes &lt;resin:XmlAuthenticator>.</p>

</description>

<example title="XmlAuthenticator in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:XmlAuthenticator password-digest="none">
    &lt;resin:user name="Harry Potter" password="quidditch" group="user,gryffindor"/>
    &lt;resin:user name="Draco Malfoy" password="pureblood" group="user,slytherin"/>
  &lt;/resin:XmlAuthenticator>
  ...
&lt;/web-app>  
</example>

</defun>

<defun title="&lt;bean>" version="Resin 3.1" name="bean">
<parents>cluster, host, web-app</parents>
<!-- deprecated -->

<description>
<p>The &lt;bean> tag as been replaced by CDI-style
configuration. It exists only for backward compatibility.</p>

<p>The new tag name will be the old class="..." name and the XML prefix
will be the package. So class="com.mycom.FooBean"
becomes &lt;mycom:FooBean xmlns:mycom="urn:com.mycom">.</p>

</description>

<example title="MyBean in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"
            xmlns:mypkg="urn:java:com.mycom.mypkg">
  ...
  &lt;mypkg:MyBean resin:Jndi="java:comp/env/my-name">
    &lt;my-attribute>my-value&lt;/my-attribute>
  &lt;/mypkg:MyBean>
  ...
&lt;/web-app>  
</example>

</defun>

<defun title="&lt;proxy-cache>" name="proxy-cache">
<parents>cluster</parents>

<description>
<p>&lt;proxy-cache&gt; configures the proxy cache (requires Resin Professional).  The
proxy cache improves performance by caching the output of servlets,
jsp and php pages.  For database-heavy pages, this caching can improve
performance and reduce database load by several orders of magnitude.</p>

<p>The proxy cache uses a combination of a memory cache and a disk-based
cache to save large amounts of data with little overhead.</p>

<p>Management of the proxy cache uses the
<a javadoc="com.caucho.management.server.ProxyCacheMXBean">ProxyCacheMXBean</a>.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr><td>path</td>
    <td>Path to the persistent cache files.</td>
    <td>resin-data/</td></tr>
<tr><td>disk-size</td>
    <td>Maximum size of the cache saved on disk.</td>
    <td>1024M</td></tr>
<tr><td>enable</td>
    <td>Enables the proxy cache.</td>
    <td>true</td></tr>
<tr><td>enable-range</td>
    <td>Enables support for the HTTP Range header.</td>
    <td>true</td></tr>
<tr><td>entries</td>
    <td>Maximum number of pages stored in the cache.</td>
    <td>8192</td></tr>
<tr><td>max-entry-size</td>
    <td>Largest page size allowed in the cache.</td>
    <td>1M</td></tr>
<tr><td>memory-size</td>
    <td>Maximum heap memory used to cache blocks.</td>
    <td>16M</td></tr>
<tr><td>rewrite-vary-as-private</td>
    <td>Rewrite Vary headers as Cache-Control: private to avoid browser
and proxy-cache bugs (particularly IE).</td>
    <td>false</td></tr>
</attributes>

<schema>
element proxy-cache {
  disk-size?
  &amp; enable?
  &amp; enable-range?
  &amp; entries?
  &amp; path?
  &amp; max-entry-size?
  &amp; memory-size?
  &amp; rewrite-vary-as-private?
}
</schema>

<example title="Example: enabling proxy cache">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="web-tier"&gt;
        &lt;proxy-cache entries="16384" disk-size="2G" memory-size="256M"/&gt;

        &lt;server id="a" address="192.168.0.10"/&gt;

        &lt;host host-name="www.foo.com"&gt;
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

<s2 title="rewrite-vary-as-private">

<p>Because not all browsers understand the Vary header, Resin can rewrite
Vary to a Cache-Control: private.  This rewriting will cache the page
with the Vary in Resin's proxy cache, and also cache the page in the browser.
Any other proxy caches, however, will not be able to cache the page.</p>

<p>The underlying issue is a limitation of browsers such as IE.  When IE
sees a Vary header it doesn't understand, it marks the page as uncacheable.
Since IE only understands "Vary: User-Agent", this would mean IE would
refuse to cache gzipped pages or "Vary: Cookie" pages.</p>

<p>With the &lt;rewrite-vary-as-private> tag, IE will cache the page
since it's rewritten as "Cache-Control: private" with no Vary at all.
Resin will continue to cache the page as normal.</p>

</s2>

</defun>


<defun title="&lt;cache-mapping>" name="cache-mapping">
<parents>web-app</parents>

<description>
<p>&lt;cache-mapping&gt; specifies <var>max-age</var> and <var>Expires</var> times for cacheable pages.</p>

<p>See <a doc="admin/http-proxy-cache.xtp">proxy-cache</a> for more information.</p>

<p>&lt;cache-mapping&gt; is intended to provide Expires times for pages that
have ETags or Last-Modified specified, but do not wish to hard-code the
max-age timeout in the servlet.  For example, Resin's FileServlet relies
on cache-mapping to set the expires times for static pages.  Using
cache-mapping lets cacheable pages be configured in a standard manner.</p>

<p>&lt;cache-mapping&gt; does not automatically make dynamic (non-static) pages cacheable.  Your
servlets must already set the <var>ETag</var> (or Last-Modified) header
to activate &lt;cache-mapping&gt;.  For static resources, Resin's FileServlet
sets the <var>ETag</var> header.</p>

<ul>
<li>cache-mapping requires an enabled &lt;proxy-cache&gt;.  If the cache is disabled,
cache-mapping will be ignored.</li>
<li>cache-mapping does not automatically make a page cacheable.  Only
cacheable pages are affected by cache-mapping, i.e. pages with an ETag or Last-Modified.</li>
</ul>

<p>The time intervals default to seconds, but will allow other 
  <a config-tag="time intervals"/>.</p>

</description>
      
<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>expires</td>
  <td>A time interval to be used for the HTTP Expires header.</td>
  <td></td>
</tr>
<tr>
  <td>max-age</td>
  <td>A time interval to be used for the "Cache-Control max-age=xxx" header.
max-age affects proxies and browsers.</td>
  <td></td>
</tr>
<tr>
  <td>s-max-age</td>
  <td>A time interval to be used for the "Cache-Control s-max-age=xxx" header.
s-max-age affects proxy caches (including Resin), but not browsers.</td>
  <td></td>
</tr>
<tr><td>url-pattern</td>
    <td>A pattern matching the url:<var>/foo/*</var>, <var>/foo</var>, or <var>*.foo</var></td>
    <td></td>
</tr>
<tr><td><a config-tag="url-regexp"/></td>
    <td>A regular expression matching the url</td>
    <td></td>
</tr>
</attributes>

<schema>
element cache-mapping {
  (url-pattern | url-regexp)
  &amp; expires?
  &amp; max-age?
  &amp; s-max-age?
}
</schema>

<example title="Example: caching .gif files for 15 minutes">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;

  &lt;cache-mapping url-pattern='/*'
                 max-age='10'/&gt;

  &lt;cache-mapping url-pattern='*.gif'
                 max-age='15m'/&gt;

&lt;/web-app&gt;
</example>
</defun>

<defun title="&lt;case-insensitive>" name="case-insensitive" occur="?">
<parents>resin, cluster, host, web-app</parents>
<default>true on Windows, false on Unix.</default>

<description>
<p>&lt;case-insensitive> specifies whether the environment
context is case sensitive or insensitive.</p>

<p>Because some operating systems are case-insensitive, it is important
for security reasons for Resin to behave differently for case-sensitive
and case-insensitive directories.  For example, when case-insensitive
is true, url-patterns will match in a case-insensitive manner, so TEST.JSP
will work like test.jsp.</p>

</description>

<schema>
r_case-insensitive = element case-insensitive {
  r_boolean-Type
}
</schema>

</defun>

<defun title="&lt;character-encoding>" name="character-encoding" occur="?" version="Resin 1.1" type="defun">
<parents>resin, cluster, host, web-app</parents>
<default>The default value is ISO-8859-1.</default>

<description>
<p>&lt;character-encoding> specifies the default character
encoding for the environment.</p>

</description>

<schema>
r_character-encoding = element character-encoding {
  string
}
</schema>

<example title="Example: utf-8 as default character encoding">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;character-encoding&gt;utf-8&lt;/character-encoding&gt;
  ...

&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;class-loader>" name="class-loader" occur="*" version="Resin 3.0">
  <parents>resin, cluster, host, web-app</parents>
  <!-- com.caucho.loader.EnvironmentClassLoader -->

<description>
<p>&lt;class-loader> configures a dynamic classloader
for the current environment.</p>

<p>Each environment (&lt;cluster&gt;, &lt;host&gt;, &lt;web-app&gt;) etc,
can add dynamic classloaders.  The environment will inherit the parent
classloaders.  Each &lt;class-loader&gt; is comprised of several implementing
loader items: library-loader for WEB-INF/lib, compiling-loader for
WEB-INF/classes.</p>

<p>For web-apps, the classloaders generally belong in a &lt;prologue>
section, which ensures that Resin evaluates them first.  The evaluation
order is particularly important in cases like resin-web.xml vs web.xml,
because the resin-web.xml is evaluated after the web.xml.</p>
</description>

<attributes>
<tr>
  <th>Element</th>
  <th>Description</th>
</tr>
<tr>
  <td>&lt;compiling-loader></td>
  <td>Automatically compiles sources code to
classes.  It its the default loader for WEB-INF/classes.</td>
</tr>
<tr>
  <td>&lt;library-loader></td>
  <td>Loads jar files from a directory.  It is the default loader
for WEB-INF/lib.</td>
</tr>
<tr>
  <td>&lt;simple-loader></td>
  <td>Loads classes from a directory, but does not compile them
automatically.</td>
</tr>
<tr>
  <td>&lt;tree-loader></td>
  <td>Loads jar files from a directory, recursively searching subdirectories.
</td>
</tr>
</attributes>

<schema>
r_class-loader = element class-loader {
  r_compiling-loader*

  &amp; r_library-loader*

  &amp; r_simple-loader*

  &amp; r_tree-loader*
}
</schema>

<example title="Example: WEB-INF/resin-web.xml defined &lt;class-loader>">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;prologue>
    &lt;class-loader&gt;
      &lt;compiling-loader path="WEB-INF/classes"/&gt;

      &lt;library-loader path="WEB-INF/lib"/&gt;
    &lt;/class-loader&gt;
  &lt;/prologue>
&lt;/web-app&gt;
</example>

</defun>

<defun title="&lt;close-dangling-connections>" name="close-dangling-connections" version="Resin 3.1.1">
<parents>database</parents>
<default>true</default>

<description>
<p>&lt;close-dangling-connections> closes open connections at the
end of a request and logs a warning and stack trace.</p>
</description>


</defun>


<defun title="&lt;cluster>" name="cluster">
<parents>resin</parents>
<description>
<p>&lt;cluster> configures a set of identically-configured servers.
The cluster typically configures a set of &lt;server&gt;s, each with some
ports, and a set of virtual &lt;host&gt;s.</p>
<p>Only one &lt;cluster&gt; is active in any on server.  At runtime,
the &lt;cluster&gt; is selected by the &lt;server&gt; with <var>id</var>
matching the -server on the command line.</p>
</description>
<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>id</td>
  <td>The cluster identifier.</td>
  <td>required</td>
</tr>
<tr>
  <td><a config-tag="access-log">access-log</a></td>
  <td>An access-log shared for all virtual hosts.</td>
  <td></td>
</tr>
<tr>
  <td><a config-tag="cache">cache</a></td>
  <td>Proxy cache for HTTP-cacheable results.</td>
  <td></td>
</tr>
<tr>
  <td><a config-tag="connection-error-page">connection-error-page</a></td>
  <td>IIS error page to use when isapi_srun to Resin connection fails</td>
  <td></td>
</tr>
<tr>
  <td><a config-tag="ear-default">ear-default</a></td>
  <td>default values for deployed ear files</td>
  <td></td>
</tr>
<tr>
  <td><a config-tag="error-page">error-page</a></td>
  <td>Custom error-page when virtual-hosts fail to match</td>
  <td></td>
</tr>
<tr>
  <td>host</td>
  <td>Configures a virtual host</td>
  <td></td>
</tr>
<tr>
  <td>host-default</td>
  <td>Configures defaults to apply to all virtual hosts</td>
  <td></td>
</tr>
<tr>
  <td>host-deploy</td>
  <td>Automatic host deployment based on a deployment directory</td>
  <td></td>
</tr>
<tr>
  <td>ignore-client-disconnect</td>
  <td>Ignores socket exceptions thrown because browser clients have prematurely disconnected</td>
  <td>false</td>
</tr>
<tr>
  <td>invocation-cache-size</td>
  <td>Size of the system-wide URL to servlet invocation mapping cache</td>
  <td>16384</td>
</tr>
<tr>
  <td>invocation-cache-max-url-length</td>
  <td>Maximum URL length saved in the invocation cache</td>
  <td>256</td>
</tr>
<tr>
  <td>max-uri-length</td>
  <td>Maximum URI length allowed in request</td>
  <td>1024</td>
</tr>
<tr>
  <td>machine</td>
  <td>Configuration for grouping &lt;server> onto physical machines</td>
  <td></td>
</tr>
<tr>
  <td>ping</td>
  <td>Periodic checking of server URLs to verify server activity</td>
  <td></td>
</tr>
<tr>
  <td>redeploy-mode</td>
  <td>"automatic" or "manual"</td>
  <td>automatic</td>
</tr>
<tr>
  <td><a config-tag="resin:choose">resin:choose</a></td>
  <td>Conditional configuration based on EL expressions</td>
  <td></td>
</tr>
<tr>
  <td><a config-tag="resin:import">resin:import</a></td>
  <td>Imports a custom cluster.xml files for a configuration management </td>
  <td></td>
</tr>
<tr>
  <td><a config-tag="resin:if">resin:if</a></td>
  <td>Conditional configuration based on EL expressions</td>
  <td></td>
</tr>
<tr>
  <td>rewrite-dispatch</td>
  <td>rewrites and dispatches URLs using regular expressions, similar to mod_rewrite</td>
  <td></td>
</tr>
<tr>
  <td>root-directory</td>
  <td>The root filesystem directory for the cluster</td>
  <td>${resin.root}</td>
</tr>
<tr>
  <td><a config-tag="server">server</a></td>
  <td>Configures JVM instances (servers).  Each cluster needs at least one server</td>
  <td></td>
</tr>
<tr>
  <td>server-default</td>
  <td>Configures defaults for all server instances</td>
  <td></td>
</tr>
<tr>
  <td>server-header</td>
  <td>Configures the HTTP "Server: Resin/xxx" header</td>
  <td>Resin/Version</td>
</tr>
<tr>
  <td>session-cookie</td>
  <td>Configures the servlet cookie name</td>
  <td>JSESSIONID</td>
</tr>
<!--
<tr>
  <td>session-sticky-disable</td>
  <td>Disables sticky-sessions on the load balancer</td>
  <td>false</td>
</tr>
-->
<tr>
  <td>url-character-encoding</td>
  <td>Configures the character encoding for URLs</td>
  <td>utf-8</td>
</tr>
<tr>
  <td>url-length-max</td>
  <td>Configures the maximum length of an allowed URL</td>
  <td>8192</td>
</tr>
<tr>
  <td>web-app-default</td>
  <td>Configures defaults to apply to all web-apps in the cluster</td>
  <td></td>
</tr>
</attributes>

<schema>
element cluster {
  attribute id { string }
  &amp; <a href="admin/config-overview.xtp">environment resources</a>
  &amp; access-log?
  &amp; cache?
  &amp; connection-error-page?
  &amp; ear-default*
  &amp; error-page*
  &amp; host*
  &amp; host-default*
  &amp; host-deploy*
  &amp; ignore-client-disconnect?
  &amp; invocation-cache-size?
  &amp; invocation-cache-max-url-length?
  &amp; machine*
  &amp; ping*
  &amp; redeploy-mode?
  &amp; resin:choose*
  &amp; resin:import*
  &amp; resin:if*
  &amp; rewrite-dispatch?
  &amp; root-directory?
  &amp; server*
  &amp; server-default*
  &amp; server-header?
  &amp; session-cookie?
  &amp; url-character-encoding?
  &amp; url-length-max?
  &amp; web-app-default*
}
</schema>

<example title="Example: cluster-default">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="web-tier"&gt;
        &lt;server-default&gt;
            &lt;http port="8080"/&gt;
        &lt;/server-default&gt;

        &lt;server id="a" address="192.168.0.10"/&gt;
        &lt;server id="b" address="192.168.0.11"/&gt;

        &lt;host host-name="www.foo.com"&gt;
          ...
        &lt;/host&gt;
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;cluster-default>" version="Resin 3.1" name="cluster-default">
<parents>resin</parents>
<description>
<p>&lt;cluster-default> defines default cluster configuration for all
clusters in the &lt;resin&gt; server.</p>
</description>
<example title="Example: cluster-default">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster-default&gt;
        &lt;cache entries="16384" memory-size="64M"/&gt;
    &lt;/cluster-default&gt;

    &lt;cluster id="web-tier"&gt;
        ...
    &lt;/cluster&gt;

    &lt;cluster id="app-tier"&gt;
        ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>
</defun>

<defun title="&lt;cluster-port>" version="Resin 3.0">
<parents>server</parents>
<p>&lt;cluster-port> configures the cluster and load balancing socket,
for load balancing, distributed sessions, and distributed management.</p>
<p>When configuring Resin in a load-balanced cluster, each Resin instance
will have its own &lt;server&gt; configuration, which Resin uses for distributed
session management and for the load balancing itself.</p>
<p>When configuring multiple JVMs, each &lt;server&gt; has a
unique &lt;server-id&gt; which allows the -server command-line to select
which ports the server should listen to.</p>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr><td>address</td>
    <td>hostname of the interface to listen to</td>
    <td>*</td></tr>
<tr><td>jsse-ssl</td>
    <td>configures the port to use JSSE for SSL</td>
    <td>none</td></tr>
<tr><td>openssl</td>
    <td>configures the port to use OpenSSL</td>
    <td>none</td></tr>
<tr><td>port</td>
    <td>port to listen to</td>
    <td>required</td></tr>
<tr><td>read-timeout</td>
    <td>timeout waiting to read from idle client</td>
    <td>65s</td></tr>
<tr><td>write-timeout</td>
     <td>timeout waiting to write to idle client</td>
     <td>65s</td></tr>
<tr><td>accept-listen-backlog</td>
    <td>The socket factory's listen backlog for receiving sockets</td>
    <td>4000</td></tr>
<tr><td>tcp-no-delay</td>
    <td>sets the NO_DELAY socket parameter</td>
    <td>true</td></tr>
</attributes>

</defun>

<defun title="&lt;compiling-loader>" name="compiling-loader" occur="*" version="Resin 3.0" type="defun">
  <parents>class-loader</parents>
  <!-- com.caucho.loader.CompilingLoader -->

<description>
<p>&lt;compiling-loader> automatically compiles Java code into .class
files before loading them.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>args</td>
  <td>Additional arguments to be passed to the Java compiler. Resin 3.0</td>
  <td></td>
</tr>
<tr><td>batch</td>
    <td>If true, multiple changed *.java files will be compiled in a single batch. Resin 3.0.7</td>
     <td>true</td></tr>
<tr>
  <td>encoding</td>
  <td>I18N encoding for the Java compiler. Since Resin 3.0</td>
  <td></td></tr>
<tr>
  <td>path</td>
  <td>Filesystem path for the class loader.  Since Resin 3.0</td>
  <td>required</td></tr>
<tr>
  <td>source</td>
  <td>Java source directory. Since Resin 3.0</td>
  <td>value of path</td></tr>
<tr>
  <td>require-source</td>
  <td>If true, .class files without matching .java files will be deleted. Since Resin 3.0</td>
  <td>false</td>
</tr>
</attributes>

<example title="Example: WEB-INF/resin-web.xml &lt;compiling-loader>">
&lt;web-app xmlns="http://caucho.com/ns/resin">
  &lt;prologue>
    &lt;class-loader>
      &lt;compiling-loader path="WEB-INF/classes"
                        source="WEB-INF/src"/>
    &lt;/class-loader>
  &lt;/prologue>
&lt;/web-app>
</example>

</defun>

<defun title="connection" title="&lt;connection>">
<parents>database</parents>

<description>
  <p>Initialize all <a
  href="http://java.sun.com/j2se/1.5.0/docs/api/java/sql/Connection.html">java.sql.Connection</a>
  objects managed by <a config-tag="database"/>.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>catalog</td>
  <td>Sets catalog property on <code>java.sql.Connection</code> object.</td>
  <td> </td>
</tr>
<tr>
  <td>read-only</td>
  <td>Sets readOnly property on <code>java.sql.Connection</code> object.</td>
  <td>false</td>
</tr>
<tr>
  <td>transaction-isolation</td>
  <td>Sets transaction isolation property on <code>java.sql.Connection</code> object.
    All levels defined in <code>java.sql.Connection.TRANSACTION_*</code>
    are supported via value set:
    none, read-committed, read-uncommitted, repeatable-read, serializable.
  </td>
  <td> unspecified </td>
</tr>
</attributes>

<schema>
element connection {
  catalog?
  &amp; read-only?
  &amp; transaction-isolation?
}
</schema>

<example title="Setting values for Connections in a pool">
&lt;web-app xmlns="http://caucho.com/ns/resin">
  &lt;database>
    &lt;driver type="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource">
      &lt;url>jdbc:mysql://localhost:3306/test&lt;/url>
      &lt;user>&lt;/user>
      &lt;password>&lt;/password>
    &lt;/driver>

    &lt;connection>
      &lt;transaction-isolation>serializable&lt;/transaction-isolation>
      &lt;catalog>my-catalog&lt;/catalog>
    &lt;/connection>
  &lt;/database>
&lt;/web-app>
</example>

</defun>


<defun title="&lt;connection-error-page>" version="Resin 3.1" name="connection-error-page">
<parents>cluster</parents>

<description>
<p>&lt;connection-error-page> specifies an error page to be used
by IIS when it can't contact an app-tier Resin.  This directive
only applies to IIS.</p>
</description>

<schema>
element connection-error-page {
  string
}
</schema>

</defun>

<defun title="&lt;connection-wait-time>" version="Resin 4.0" name="connection-wait-time">
<parents>database</parents>
<default>30s</default>

<description>
<p>&lt;connection-wait-time> configures the time a <code>getConnection</code>
call should wait when then pool is full before trying to create an
overflow connection.</p>

</description>

</defun>
<defun title="&lt;constraint>" name="constraint" version="Resin">
<parents>security-constraint</parents>

<description>
<p>
Defines a custom constraint.  Applications can define their own
security constraints to handle custom authentication requirements.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>resin:type</td>
  <td>A class that extends <a javadoc="com.caucho.server.security.AbstractConstraint">AbstractConstraint</a></td>
</tr>
<tr>
  <td>init</td>
  <td>initialization parameters, set in the object using Bean-style setters and getters</td>
</tr>
</attributes>

<schema>
element constraint {
  class
  &amp; init?
}
</schema>

</defun>

<defun title="&lt;context-param>" name="context-param" version="Servlet 2.2">
<parents>web-app</parents>

<description>
<p>Initializes application (ServletContext) variables.  <var>context-param</var>
defines initial values for <code>application.getInitParameter("foo")</code>.  See also
<a javadoc="javax.servlet.ServletContext">ServletContext.getInitParameter()</a>.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>param-name</td>
  <td>Named parameter</td>
</tr>
<tr>
  <td>param-value</td>
  <td>Parameter value</td>
</tr>
<tr>
  <td><var/foo/></td>
  <td>Parameter name</td>
</tr>
</attributes>

<schema>
element context-param {
  (param-name, param-value)*
  | (attribute * { string })*
  | (element * { string })*
}
</schema>

<example title="Example: context-param in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;context-param&gt;
    &lt;param-name&gt;baz&lt;/param-name&gt;
    &lt;param-value&gt;value&lt;/param-value&gt;
  &lt;/context-param&gt;

  &lt;!-- shortcut --&gt;
  &lt;context-param foo="bar"/&gt;

&lt;/web-app&gt;
</example>
</defun>

<defun title="&lt;cookie-http-only>" name="cookie-http-only">
<parents>web-app</parents>

<description>

<p>The &lt;cookie-http-only> flag configures the Http-Only attribute
for the JSESSIONID cookie generated from the web-app.  The
Http-Only attribute can add security to a website by not
forwarding HTTP cookies to
SSL HTTPS requests.</p>
</description>

<schema>
element cookie-http-only {
  r_boolean-Type
}
</schema>

<example title="Example: &lt;cookie-http-only> in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">

  &lt;host id="www.foo.com">
    &lt;web-app id="" root-directory="/var/resin/foo">
      &lt;cookie-http-only>true&lt;/cookie-http-only>
    &lt;web-app id="">
  &lt;/host>

  &lt;host id="www.foo.com:443">
    &lt;web-app id="" root-directory="/var/resin/foo-secure">
      &lt;secure/>
    &lt;web-app id="">
  &lt;/host>

&lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="cron trigger syntax" name="cron">

<description>
<p>
A time syntax used in a number of tags. Originally used in the Unix
cron program. The <a href="http://en.wikipedia.org/wiki/Crontab">wikipedia
cron entry</a> contains this descriptive chart:
</p>

<def title="cron fields">
# +---------------- minute (0 - 59)
# |  +------------- hour (0 - 23)
# |  |  +---------- day of month (1 - 31)
# |  |  |  +------- month (1 - 12)
# |  |  |  |  +---- day of week (0 - 6) (Sunday=0 or 7)
# |  |  |  |  |
  *  *  *  *  *
</def>

<deftable title="cron patterns">
<tr>
  <th>Pattern</th>
  <th>Description</th>
</tr>
<tr>
  <td>*</td>
  <td>matches all time periods</td>
</tr>
<tr>
  <td>15</td>
  <td>matches the specific time, e.g. 15 for minutes</td>
</tr>
<tr>
  <td>15,45</td>
  <td>matches a list of times, e.g. every :15 and :45</td>
</tr>
<tr>
  <td>*/5</td>
  <td>matches every <var>n</var> times, e.g. every 5 minutes</td>
</tr>
<tr>
  <td>1-5</td>
  <td>matches a range of times, e.g. mon, tue, wed, thu, fri (1-5)</td>
</tr>
</deftable>
</description>
</defun>
   
<defun title="&lt;development-mode-error-page>" version="Resin 3.2.0">
<parents>cluster</parents>

<description>
<p>&lt;development-mode-error-page> enables browser error reporting
with extra information.  Because it can expose internal data, it is not
generally recommended in production systems.  (The information is generally
copied to the log.</p>
</description>

</defun>

<defun title="&lt;database>" name="database" occur="*">
<parents>resin, cluster, host, web-app</parents>
  <!-- com.caucho.sql.DBPool -->

<description>
<p>&lt;database&gt; defines a database (i.e. DataSource) resource.</p>

</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>backup-driver</td>
  <td>Configures a backup database driver.  If Resin can't connect to
any of the main drivers, it will use one of the. backups</td>
  <td></td>
</tr>
<tr>
  <td>close-dangling-connections</td>
  <td>If an application does not close a Connection by the end of the
request, Resin will close it automatically an issue a warning.</td>
  <td>true</td>
</tr>
<tr>
  <td>commit-on-timeout</td>
  <td>true to commit the transaction on timeout, false to rollback</td>
  <td>false</td>
</tr>
<tr>
  <td><a config-tag="connection"/></td>
  <td>Defines initialization attributes for new connections, e.g.
setting the transaction-isolation.</td>
  <td>true</td>
</tr>
<tr>
  <td>connection-wait-time</td>
  <td>When max-connections has been reached, how long Resin will wait for
a connection to become idle before giving up.</td>
  <td>30s</td>
</tr>
<tr>
  <td>driver</td>
  <td>Configures the database driver, giving the driver's class name
as well as its JDBC URL and any other configuration.</td>
  <td>required</td>
</tr>
<tr>
  <td>jndi-name</td>
  <td>The JNDI name to register the connection's <code>DataSource</code>
under.  The name can be relative to <var>java:comp/env</var>.</td>
  <td></td>
</tr>
<tr>
  <td>max-active-time</td>
  <td>The maximum time Resin will allow a connection to remain open
before forcing a close.</td>
  <td>6h</td>
</tr>
<tr>
  <td>max-close-statements</td>
  <td>The maximum number of Statements Resin will hold to automatically
close when the Connection closes.</td>
  <td>256</td>
</tr>
<tr>
  <td>max-connections</td>
  <td>The maximum number of Connections allowed.</td>
  <td>1024</td>
</tr>
<tr>
  <td>max-create-connections</td>
  <td>The maximum number of connection creation allowed at one time.</td>
  <td>5</td>
</tr>
<tr>
  <td>max-idle-count</td>
  <td>The maximum number of Connections in the idle pool.</td>
  <td>1024</td>
</tr>
<tr>
  <td>max-idle-time</td>
  <td>The maximum time a connection will spend in the idle pool before closing.</td>
  <td>60s</td>
</tr>
<tr>
  <td>max-overflow-connections</td>
  <td>The number of extra connection creation if the number of connections exceeds to pool size.</td>
  <td>1024</td>
</tr>
<tr>
  <td>max-pool-time</td>
  <td>The total time a connection can be used before it is automatically closed instead of returned to the idle pool.</td>
  <td>24h</td>
</tr>
<tr>
  <td>name</td>
  <td>The IoC name to save the <code>ConnectionFactory</code> as,
used with <code>@Named</code> to inject the resource.</td>
  <td></td>
</tr>
<tr>
  <td>password</td>
  <td>The JDBC password for the connection.</td>
  <td></td>
</tr>
<tr>
  <td>ping</td>
  <td>If true, Resin will ping the database before returning a connection
from the pool (if ping-interval is exceeded).</td>
  <td>false</td>
</tr>
<tr>
  <td>ping-interval</td>
  <td>How often an idle connection should ping the database
to ensure it is still valid.</td>
  <td>1s</td>
</tr>
<tr>
  <td>ping-query</td>
  <td>A custom query used to ping the database connection.</td>
  <td></td>
</tr>
<tr>
  <td>ping-table</td>
  <td>A table used to ping the database connection.</td>
  <td></td>
</tr>
<tr>
  <td>prepared-statement-cache-size</td>
  <td>How many <code>PreparedStatements</code> to save in the
prepared statement cache.</td>
  <td>0</td>
</tr>
<tr>
  <td>save-allocation-stack-trace</td>
  <td>If true, saves the location of the connection allocation as a
stack trace.</td>
  <td>false</td>
</tr>
<tr>
  <td>spy</td>
  <td>Enables spy logging of database statements.  The logging occurs with
name="com.caucho.sql" and level="fine".</td>
  <td>false</td>
</tr>
<tr>
  <td>transaction-timeout</td>
  <td>Sets the transaction timeout.</td>
  <td>none</td>
</tr>
<tr>
  <td>user</td>
  <td>Sets the authentication user.</td>
  <td></td>
</tr>
<tr>
  <td>wrap-statements</td>
  <td>If true, Resin wraps statements and automatically closes them
on connection close.</td>
  <td>true</td>
</tr>
<tr>
  <td>xa</td>
  <td>Enables automatic enlistment of <code>Connections</code>
with any <code>UserTransaction</code>.  Disabling &lt;xa> means the
connection are independent of transactions, useful for read-only
connections.</td>
  <td>true</td>
</tr>
<tr>
  <td>xa-forbid-same-rm</td>
  <td>Workaround flag to handle certain database drivers that do
not properly implement the XAResource API.</td>
  <td>false</td>
</tr>
</attributes>

<schema>
database = element database {
  backup-driver*
  &amp; close-dangling-connections?
  &amp; commit-on-timeout?
  &amp; connection?
  &amp; connection-wait-time?
  &amp; driver+
  &amp; jndi-name?
  &amp; max-active-time?
  &amp; max-close-statements?
  &amp; max-connections?
  &amp; max-create-connections?
  &amp; max-idle-count?
  &amp; max-idle-time?
  &amp; max-overflow-connections?
  &amp; max-pool-time?
  &amp; name?
  &amp; password?
  &amp; ping?
  &amp; ping-interval?
  &amp; ping-query?
  &amp; ping-table?
  &amp; prepared-statement-cache-size?
  &amp; save-allocation-stack-trace?
  &amp; spy?
  &amp; transaction-timeout?
  &amp; user?
  &amp; wrap-statements?
  &amp; xa?
  &amp; xa-forbid-same-rm?
}

backup-driver = element backup-driver {
  class?
  &amp; url?
  &amp; element * { * }?
}

connection = element connection {
  catalog?
  &amp; read-only?
  &amp; transaction-isolation?
}

driver = element driver {
  class?
  &amp; url?
  &amp; element * { * }?
}

</schema>

<example title="Example: WEB-INF/resin-web.xml database">
&lt;web-app xmlns="http://caucho.com/ns/resin">

&lt;database jndi-name='jdbc/test_mysql'&gt;
  &lt;driver type="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource"&gt;
    &lt;url&gt;jdbc:mysql://localhost:3306/test&lt;/url&gt;
    &lt;user&gt;&lt;/user&gt;
    &lt;password&gt;&lt;/password&gt;
  &lt;/driver&gt;
&lt;/database&gt;

&lt;/web-app>
</example>

</defun>

<defun title="&lt;database-default>" name="database-default" version="Resin 4.0">
<parents>resin, cluster, host, web-app</parents>
  <!-- com.caucho.sql.DBPool -->

<description>
<p>&lt;database-default> defines default database values to be used
for any &lt;database> definition, or runtime database creation
(see <a javadoc="com.caucho.sql.DatabaseManager">DatabaseManager</a>).</p>
</description>

<schema>
element database-default {
  r_database-Content
}
</schema>

<example title="Example: WEB-INF/resin-web.xml idle-time defaults">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;database-default>
    &lt;max-idle-time>10s&lt;/max-idle-time>
  &lt;/database-default>

&lt;/web-app>
</example>

</defun>

<defun title="&lt;dependency>" name="dependency" occur="?" version="Resin 3.0.1">
<parents>resin, cluster, host, web-app</parents>

<description>
<p>&lt;dependency> adds dependent files which should force a
reload when changed, like web.xml and resin-web.xml.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>path</td>
  <td>Filesystem path to the dependent file.  Since Resin 3.0</td>
  <td>required</td>
</tr>
</attributes>

<schema>
element dependency {
  string
}
</schema>

<example title="Example: struts dependency">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;dependency path="WEB-INF/struts-config.xml"/&gt;
  ...
&lt;/web-app&gt;
</example>

</defun>

<defun title="&lt;dependency-check-interval>" name="dependency-check-interval" occur="?" version="Resin 3.0">
<parents>resin, cluster, host, web-app</parents>
<default>2s</default>

<description>
<p>&lt;dependency-check-interval> Configures how often the environment context
should be checked for changes.  The default value is set low for
development purposes, deployments should use something larger like
5m or 1h.</p>

<p>Resin automatically checks each environment for updates, generally
class or configuration updates.  Because these checks can take a considerable
amount of time, deployment servers should use high values like 60s or more while development machines will want low values like 2s.</p>

<p>The interval defaults to the parent's interval.  So the web-app will
default to the host's value.</p>

</description>

<schema>
element dependency-check-interval {
  string
}
</schema>

<example title="Example: deployment dependency-check-interval">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">
    &lt;dependency-check-interval>1h&lt;dependency-check-interval>

    &lt;server id="app-a" .../>

    &lt;host id=""/>
      ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;driver>" name="driver" version="Resin 4.0">
<parents>database</parents>

<description>
<p>&lt;driver> configures a database driver for a connection pool.
The individual driver information is available from the driver vendor
or on the <a href="http://wiki.caucho.com/Main_Page">Caucho Wiki</a>.</p>

<p>The content of the driver tag configures bean properties of
the driver class, e.g. url, user, password.</p>
</description>

<schema>
element driver {
  type,
  *
}
</schema>

</defun>


<defun title="&lt;ear-default>" version="Resin 3.1" name="ear-default">
<parents>cluster</parents>

<description>
<p>&lt;ear-default> configures defaults for .ear resource,
i.e. enterprise applications.</p>
</description>

</defun>

<defun title="&lt;ear-deploy>" name="ear-deploy">
<parents>host, web-app</parents>

<description>
<p>Specifies ear expansion.</p>

<p>ear-deploy can be used in web-apps to define a subdirectory
for ear expansion.</p>
</description>

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

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

</defun>


<defun title="&lt;ejb-message-bean>" name="ejb-message-bean" occur="*" version="Resin 3.0">
<parents>resin, cluster, host, web-app</parents>
  <!-- com.caucho.ejb.EJBServer -->

<description>
<p>&lt;ejb-message-bean> configures a bean as a message listener.
The listener can be a simple bean that just implements the
<code>javax.jms.MessageListener interface</code>.  No other packaging
or complications are necessary.  Resin will retrieve messages from a
configured queue and pass them to the listener as they arrive.  The
listeners are typically pooled.
</p>

<p>The bean has full access to Resin-IoC capabilities, including
dependency injection, transaction attributes, and aspect interception.
</p>

<p>The message bean can plug into custom messaging systems.  The
application will need to define a <a javadoc="javax.resource.spi.ResourceAdapter">ResourceAdapter</a> and
an <code>ActivationSpec</code>.  </p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>activation-spec</td>
  <td>Configures a custom message-listener driver</td>
  <td></td>
</tr> <tr>
  <td>class</td>
  <td>Classname of the listener bean</td>
  <td>required</td>
</tr>
<tr>
  <td>destination</td>
  <td>Queue or Topic for JMS message receiving</td>
  <td></td>
</tr>
<tr>
  <td>destination-type</td>
  <td>javax.jms.Queue or javax.jms.Topic</td>
  <td></td>
</tr>
<tr>
  <td>init</td>
  <td>IoC configuration for the listener bean</td>
  <td></td>
</tr>
<tr>
  <td>message-consumer-max</td>
  <td>The number of listener instances to create for the pool.</td>
  <td>5</td>
</tr>
</attributes>

<schema>
element ejb-message-bean {
  class
  &amp; init?
  &amp; (activation-spec?
     | (destination?
        &amp; destination-type?
        &amp; destination-name?
        &amp; message-consumer-max?)
    )
}
</schema>

<!-- XXX  convert these from uris

<example title="Example: JMS listener in WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;jms-connection-factory uri="resin:"/>
  &lt;jms-queue name="my_queue" uri="memory:"/>

  &lt;ejb-message-bean class="qa.MyListener">
    &lt;destination>${my_queue}&lt;/destination>
  &lt;/ejb-message-bean>

&lt;/web-app>
</example>
-->

</defun>


<defun title="&lt;ejb-server>" name="ejb-server" occur="*" version="Resin 3.0">
<parents>resin, cluster, host, web-app</parents>
  <!-- com.caucho.ejb.EJBServer -->

<description>
  <p>Configures an EJB server.</p>
<!-- XXX broken link
    See <a href="../doc/resin-ejb.xtp">Resin EJB</a> for more details.-->
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>auto-compile</td>
  <td>enables auto-compilation of EJB stubs and skeletons</td>
  <td>true</td>
</tr>
<tr>
  <td>create-database-schema</td>
  <td>enables JPA auto-creation of missing database tables</td>
  <td>false</td>
</tr>
<tr>
  <td>data-source</td>
  <td>specifies the default database for JPA</td>
  <td></td>
</tr>
<tr>
  <td>config-directory</td>
  <td>specifies a directory containing *.ejb configuration files</td>
  <td></td>
</tr>
<tr>
  <td>ejb-descriptor</td>
  <td>path to a *.ejb file to load</td>
  <td></td>
</tr>
<tr>
  <td>ejb-jar</td>
  <td>path to a jar file containing a META-INF/ejb-jar.xml with EJBs</td>
  <td></td>
</tr>
<tr>
  <td>jndi-prefix</td>
  <td>prefix for JNDI registration of EJBs</td>
  <td></td>
</tr>
<tr>
  <td>validate-database-schema</td>
  <td>verifies the actual database tables against the JPA definitions</td>
  <td>true</td>
</tr>
<tr>
  <td>jms-connection-factory</td>
  <td>specifies the default JMS ConnectionFactory for message beans</td>
  <td></td>
</tr>
<tr>
  <td>xa-data-source</td>
  <td>specifies a separate database for transactions</td>
  <td>data-source</td>
</tr>
</attributes>

<schema>
element ejb-server {
  auto-compile
  &amp; create-database-schema
  &amp; data-source
  &amp; config-directory
  &amp; ejb-descriptor
  &amp; ejb-jar
  &amp; jndi-prefix
  &amp; validate-database-schema
  &amp; jms-connection-factory
  &amp; xa-data-source
}
</schema>

</defun>

<defun title="&lt;ejb-stateful-bean>" name="ejb-stateful-bean">
<parents>resin, host-default, host, web-app-default, web-app</parents>
<!-- deprecated -->

<description>
<p>&lt;ejb-stateful-bean> is deprecated and replaced by CDI-style
configuration. EJB stateful beans are now either scanned automatically
if configured with the @Stateful annotation or can be configured as
CDI beans with the &lt;ee:Stateful> tag.</p>
</description>

<example title="Stateful bean in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:ee="urn:java:ee"
         xmlny:mypkg="urn:java:com.mycom.mypkg">

  &lt;mypkg:MyBean>
    &lt;ee:Stateful/>

    &lt;my-attribute>my-value&lt;/my-attribute>
  &lt;/mypkg:MyBean>

&lt;/web-app>  
</example>
</defun>

<!-- old description
     XXX there's some good description in here, even though the actual
     configuration has changed to CDI. Consider retaining some for 
     a topic page or the CDI page.

<description>
<p>&lt;ejb-stateful-bean> configures an EJB @Stateful bean.  The
@Stateful bean is a single-threaded component bean suitable for
transaction processing.</p>

<p>The stateful-bean is registered in the Resin-IoC/WebBeans context and
optionally with JNDI.</p>

<p>Since @Stateful beans are components, they are created at the request
of the application and destroyed by the application.  @Stateful beans are
never singletons.  For singleton-style beans, either use a &lt;bean> or
a @Stateless session bean.</p>

<p>@Stateful beans may optionally implement a <a javadoc="javax.ejb.SessionSynchronization">SessionSynchronization</a> interface for transaction callbacks.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>class</td>
  <td>the classname of the bean implementation</td>
  <td>required</td>
</tr>
<tr>
  <td>init</td>
  <td>IoC initialization for each bean instance</td>
  <td></td>
</tr>
<tr>
  <td>jndi-name</td>
  <td>A JNDI name to store the bean as.</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td>The Resin-IoC/WebBeans @Named registration</td>
  <td>The classname</td>
</tr>
<tr>
  <td>scope</td>
  <td>The Resin-IoC/WebBeans scope: dependent, request, session, conversaion</td>
  <td>dependent classname</td>
</tr>
</attributes>

<schema>
element ejb-stateful-bean {
  class
  &amp; init?
  &amp; jndi-name?
  &amp; name?
  &amp; scope?
}
</schema>

</defun>

<defun title="&lt;ejb-stateless-bean>" name="ejb-stateless-bean">
<parents>resin, host-default, host, web-app-default, web-app</parents>

<description>
<p>&lt;ejb-stateless-bean> configures an EJB @Stateless bean.  The
@Statelesss bean is a pooled, proxied, singleton component bean suitable.
</p>

<p>The stateless-bean is registered in the Resin-IoC/WebBeans context and
optionally with JNDI.</p>

<p>@Stateless beans are similar to &lt;bean> singletons, but pool instances.
Each instance executes a single thread at a time, unlike &lt;bean>
singletons which are multithreaded like servlets.  Both styles can
use the same aspect capabilities like dependency injection, transactions,
and interceptors.  Because @Stateless beans are singletons, they
do not have a scope attribute.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>class</td>
  <td>the classname of the bean implementation</td>
  <td>required</td>
</tr>
<tr>
  <td>init</td>
  <td>IoC initialization for each bean instance</td>
  <td></td>
</tr>
<tr>
  <td>jndi-name</td>
  <td>A JNDI name to store the bean as.</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td>The Resin-IoC/WebBeans @Named registration</td>
  <td>The classname</td>
</tr>
</attributes>

<schema>
element ejb-stateless-bean {
  class
  &amp; init?
  &amp; jndi-name?
  &amp; name?
}
</schema>

</defun>
-->

<defun title="&lt;ejb-stateless-bean>" name="ejb-stateless-bean">
<parents>resin, host-default, host, web-app-default, web-app</parents>
<!-- deprecated -->

<description>
<p>&lt;ejb-stateless-bean> is deprecated and replaced by CDI-style
configuration. EJB stateless beans are now either scanned automatically
if configured with the @Stateless annotation or can be configured as
CDI beans with the &lt;ee:Stateless> tag.</p>
</description>

<example title="Stateless bean in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:ee="urn:java:ee"
         xmlny:mypkg="urn:java:com.mycom.mypkg">

  &lt;mypkg:MyBean>
    &lt;ee:Stateless/>

    &lt;my-attribute>my-value&lt;/my-attribute>
  &lt;/mypkg:MyBean>

&lt;/web-app>  
</example>
</defun>

<defun title="&lt;environment-system-properties>" name="environment-system-properties">
<default>true</default>

<description>
<p>By default, Resin's <code>System.getProperties()</code> is
environment-dependent, so the settings in on web-app do not affect the
properties in any other web-app.  Some sites may need to disable
this virtualization capability, when using certain JVM agents.</p>
</description>

<schema>
element environment-system-properties {
  r_boolean-Type
}
</schema>

</defun>

<defun title="&lt;env-entry>" name="env-entry" occur="*" version="Resin 3.0">
<parents>resin, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.config.types.EnvEntry -->

<description>
<p>&lt;env-entry> configures a JNDI scalar value
for JNDI-based application configuration.</p>

<p>Some application beans prefer to retrieve configuration data from JNDI,
including String, Integer, and Double constants.  env-entry configures
that data in the current context.</p>

<p>The value can not use JSP-EL expressions, because the env-entry is
part of the JavaEE spec.  To set EL expressions, use resin:set instead.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>env-entry-name</td>
  <td>JNDI name to store the value.  Since Servlet 2.1</td>
  <td>required</td>
</tr>
<tr>
  <td>env-entry-type</td>
  <td>Java type for the value.  Since Servlet 2.1</td>
  <td>required</td>
</tr>
<tr>
  <td>env-entry-value</td>
  <td>Value to be stored.  Since Servlet 2.1</td>
  <td>required</td>
</tr>
</attributes>

<schema>
element env-entry {
  description*,

  env-entry-name,

  env-entry-type,

  env-entry-value
}
</schema>

<examples>
<p>The example configuration stores a string in java:comp/env/greeting.
Following the J2EE spec, the env-entry-name is relative to
java:comp/env.  If the env-entry is in the &lt;host&gt; context, it will
be visible to all web-apps in the host.</p>

<example title="Example: WEB-INF/resin-web.xml with env-entry">
&lt;web-app xmlns="http://caucho.com/ns/resin">
  &lt;env-entry&gt;
    &lt;env-entry-name&gt;greeting&lt;/env-entry-name&gt;
    &lt;env-entry-type&gt;java.lang.String&lt;/env-entry-type&gt;
    &lt;env-entry-value&gt;Hello, World&lt;/env-entry-value&gt;
  &lt;/env-entry&gt;

  &lt;servlet ...>
  &lt;/servlet>
&lt;/web-app>
</example>

<p>The following servlet fragment is a typical use in a servlet.  The
servlet only looks up the variable once and stores it for later use.
</p>

<example title="Example: GreetingServlet.java">
import java.io.*;
import javax.naming.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class TestServlet extends HttpServlet {
  private String greeting;

  public void init()
    throws ServletException
  {
    try {
      Context env = 
        (Context) new InitialContext().lookup("java:comp/env");
      greeting = (String) env.lookup("greeting");
    } catch (NamingException e) {
      throw new ServletException(e);
    }
  }

  ...
}
</example>
</examples>

</defun>

<defun title="&lt;error-page>" name="error-page" version="Servlet 2.2">
<parents>web-app</parents>

<description>
  <p>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
  &lt;error-page>, you may specify a handler page for these errors.</p>

  <p>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.</p>
  
<deftable title="Request attributes for error handling">
<tr>
  <th>Attribute</th>
  <th>Type</th>
</tr>
<tr>
  <td>javax.servlet.error.status_code</td>
  <td>java.lang.Integer</td>
</tr>
<tr>
  <td>javax.servlet.error.message</td>
  <td>java.lang.String</td>
</tr>
<tr>
  <td>javax.servlet.error.request_uri</td>
  <td>java.lang.String</td>
</tr>
<tr>
  <td>javax.servlet.error.servlet_name</td>
  <td>java.lang.String</td>
</tr>
<tr>
  <td>javax.servlet.error.exception</td>
  <td>java.lang.Throwable</td>
</tr>
<tr>
  <td>javax.servlet.error.exception_type</td>
  <td>java.lang.Class</td>
</tr>
</deftable>


</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>error-code</td>
  <td>Select the error page based on an HTTP status code</td>
</tr>
<tr>
  <td>exception-type</td>
  <td>Select the error page based on a Java exception</td>
</tr>
<tr>
  <td>location</td>
  <td>The error page to display</td>
</tr>
</attributes>

<schema>
element error-page {
  (error-code | exception-type)?
  &amp; location
}
</schema>

<example title="Catching File Not Found">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;error-page&gt;
    &lt;error-code&gt;404&lt;/error-code&gt;
    &lt;location&gt;/file_not_found.jsp&lt;/location&gt;
  &lt;/error-page&gt;
&lt;/web-app&gt;
</example>

<example title="Catching Exceptions">
&lt;web-app xmlns="http://caucho.com/ns/resin">
   &lt;error-page exception-type="java.lang.NullPointerException"
               location="/nullpointer.jsp"/&gt;
&lt;/web-app&gt;
</example>

<example title="Using request attributes to obtain information about the request that caused the error">
&lt;%@ page session="false" isErrorPage="true" %&gt;

&lt;html&gt;
&lt;head&gt;&lt;title&gt;404 Not Found&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;
&lt;h1&gt;404 Not Found&lt;/h1&gt;

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

</defun>

<defun title="&lt;expand-cleanup-fileset>" name="expand-cleanup-fileset">
<parents>web-app-deploy</parents>

<description>
<p>The expand-cleanup-fileset tag lets you configure which files are to
be kept on a .war redeploy. By default, Resin deletes the entire .war
directory on a restart.</p>
</description>

</defun>

<defun title="&lt;fileset>" name="fileset" version="Resin 3.0.7">

<description>
<p>&lt;fileset&gt; provides the ability to match a set of files.  It is
modelled after the ant tag by the same name.  The fileset matches
files from a base directory defined by 'dir'.  Files can be included
by patterns defined by &lt;include> tags or excluded by patterns defined in
&lt;exclude> tags.</p>

<p>A pattern can contain two special characters: '*' and '**'.  '*' matches any
part of path, but does not match the path separator.  '**' matches any part of
a path, including the path separator. </p>

</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr><td>dir</td>
    <td>the starting directory</td>
    <td>required</td></tr>
<tr><td>include</td>
    <td>an include pattern</td>
    <td>do not include all files</td></tr>
<tr><td>exclude</td>
    <td>an exclude pattern</td>
    <td>do not exclude any files</td></tr>
</attributes>

<schema>
element fileset {
  dir
  &amp; exclude*
  &amp; include*
</schema>

<example title="Matching jars in WEB-INF/lib (non-recursive)">
&lt;fileset dir="WEB-INF/lib"&gt;
  &lt;include name="*.jar"/&gt;
&lt;/fileset&gt;

MATCH    lib/foo.jar
MATCH    lib/bar.jar
NO MATCH lib/baz/foo.jar
</example>

<example title="Matching jars in WEB-INF/lib (recursive)">
&lt;fileset dir="WEB-INF/tree"&gt;
  &lt;include name="**/*.jar"/&gt;
&lt;/fileset&gt;

MATCH    lib/foo.jar
MATCH    lib/bar.jar
MATCH    lib/baz/foo.jar
</example>

</defun>

<defun title="&lt;filter>" name="filter" version="Servlet 2.3">
<parents>web-app</parents>

<description>
<p>Defines a filter name for later mapping.  Because Filters are fully
integrated with <a href="admin/config-candi.xtp">Resin CanDI</a>, they can
use dependency-injection, transactional aspects, custom interception
with @InterceptorType, and event handling with @Observes.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>filter-name</td>
  <td>The filter's name (alias)</td>
</tr>
<tr>
  <td>filter-class</td>
  <td>The filter's class (defaults to filter-name), which extends <a javadoc="javax.servlet.Filter">javax.servlet.Filter</a></td>
</tr>
<tr>
  <td>init</td>
  <td>Resin-IoC initialization configuration, see <a href="admin/config-candi.xtp">Resin-IoC</a></td>
</tr>
<tr>
  <td>init-param</td>
  <td>Initialization parameters, see <a javadoc="javax.servlet.FilterConfig">FilterConfig.getInitParameter</a></td>
</tr>
</attributes>

<schema>
element filter {
  filter-name
  &amp; filter-class
  &amp; init*
  &amp; init-param*
}
</schema>

<example title="Defining a filter name 'image'">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;filter&gt;
    &lt;filter-name&gt;image&lt;/filter-name&gt;
    &lt;filter-class&gt;test.MyImage&lt;/filter-class&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;title&lt;/param-name&gt;
      &lt;param-value&gt;Hello, World&lt;/param-value&gt;
    &lt;/init-param&gt;
  &lt;/filter&gt;

  &lt;filter-mapping&gt;
    &lt;filter-name&gt;image&lt;/filter-name&gt;
    &lt;url-pattern&gt;/images/*&lt;/url-pattern&gt;
  &lt;/filter-mapping&gt;

&lt;/web-app&gt;
</example>

<example title="init-param shortcut syntax">
&lt;web-app id='/'&gt;

&lt;filter filter-name='test.HelloWorld'&gt;
  &lt;init-param foo='bar'/&gt;

  &lt;init-param&gt;
    &lt;param-name&gt;baz&lt;/param-name&gt;
    &lt;param-value&gt;value&lt;/param-value&gt;
  &lt;/init-param&gt;
&lt;/servlet&gt;

&lt;/web-app&gt;
</example>
</defun>

<defun title="&lt;filter-mapping>" name="filter-mapping" version="Servlet 2.3">
<parents>web-app</parents>

<description>
<p>Maps url patterns to filters.  <var>filter-mapping</var> has two
children, <var>url-pattern</var> and <var>filter-name</var>.
<var>url-pattern</var> selects the urls which should execute the filter.
</p>

<p><code>filter-name</code> can either specify a filter class directly or it
can specify a filter alias defined by <a config-tag="filter"/>.
</p>

</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>dispatcher</td>
  <td>REQUEST, INCLUDE, FORWARD, ERROR</td>
  <td>REQUEST</td>
</tr>
<tr>
  <td>filter-name</td>
  <td>The filter name</td>
  <td>required</td>
</tr>
<tr>
  <td>url-pattern</td>
  <td>A pattern matching the url: <var>/foo/*</var>, <var>/foo</var>, or <var>*.foo</var></td>
  <td></td>
</tr>
<tr>
  <td><a config-tag="url-regexp"/></td>
  <td>A regular expression matching the portion of the url that follows the <g>context path</g></td>
  <td></td>
</tr>
</attributes>

<schema>
element filter-mapping {
  (url-pattern | url-regexp | servlet-name)+
  &amp; filter-name
  &amp; dispatcher*
}
</schema>

<example title="Example: resin-web.xml filters">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;

  &lt;filter&gt;
    &lt;filter-name&gt;test-filter&lt;/filter-name&gt;
    &lt;filter-class&gt;test.MyFilter&lt;/filter-class&gt;
  &lt;/filter&gt;

  &lt;filter-mapping&gt;
    &lt;filter-name&gt;test-filter&lt;/filter-name&gt;
    &lt;url-pattern&gt;/hello/*&lt;/url-pattern&gt;
  &lt;/filter-mapping&gt;

  &lt;servlet&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;servlet-class&gt;test.HelloWorld&lt;/servlet-class&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/hello&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;
&lt;/web-app&gt;
</example>

</defun>

<defun title="&lt;form-login-config>" name="form-login-config" version="Servlet" type="defun">
<parents>login-config</parents>

<description>
<p>Configures authentication using forms.  The login form has
specific parameters that the servlet engine's login form processing
understands.  If the login succeeds, the user will see the original
page.  If it fails, she will see the error page.</p>

<p>The form itself must have the action <var>j_security_check</var>.  It
must also have the parameters <var>j_username</var> and <var>j_password</var>.
Optionally, it can also have <var>j_uri</var> and
<var>j_use_cookie_auth</var>.  <var>j_uri</var> gives the next page to display
when login succeeds.  <var>j_use_cookie_auth</var> allows Resin to send a
persistent cookie to the user to make following login easier.</p>

<p><var>j_use_cookie_auth</var> gives control to the user whether to generate
a persistent cookie.  It lets you implement the "remember me" button.  By
default, the authentication only lasts for a single session.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>form-login-page</td>
  <td>The page to be used to prompt the user login</td>
  <td></td>
</tr>
<tr>
  <td>form-error-page</td>
  <td>The error page for unsuccessful login</td>
  <td></td>
</tr>
<tr>
  <td>internal-forward</td>
  <td>Use an internal redirect on success instead of a sendRedirect</td>
  <td>false</td>
</tr>
<tr>
  <td>form-uri-priority</td>
  <td>If true, the form's j_uri will override a stored URI</td>
  <td>false</td>
</tr>
</attributes>

<attributes title="Special form input names">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>j_security_check</td>
  <td>The form's mandatory action</td>
</tr>
<tr>
  <td>j_username</td>
  <td>The user name</td>
</tr>
<tr>
  <td>j_password</td>
  <td>The password</td>
</tr>
<tr>
  <td>j_uri</td>
  <td>Optional Resin extension for the successful display page.</td>
</tr>
<tr>
  <td>j_use_cookie_auth</td>
  <td>Optional Resin extension to allow cookie login.</td>
</tr>
</attributes>

<schema>
element form-login-config {
  form-login-page,
  form-error-page,
  internal-forward,
  form-uri-priority
}
</schema>

<example title="Example: login.html">
&lt;form action='j_security_check' method='POST'&gt;
&lt;table&gt;
&lt;tr&gt;&lt;td&gt;User:&lt;td&gt;&lt;input name='j_username'&gt;
&lt;tr&gt;&lt;td&gt;Password:&lt;td&gt;&lt;input name='j_password'&gt;
&lt;tr&gt;&lt;td colspan=2&gt;hint: the password is 'quidditch'
&lt;tr&gt;&lt;td&gt;&lt;input type=submit&gt;
&lt;/table&gt;
&lt;/form&gt;
</example>

</defun>
   
<defun title="&lt;group-name>" version="Resin 4.0" name="group-name">
<parents>server</parents>

<description>
<p>&lt;group-name> configures the operating system group Resin should
run as.  Since the HTTP port 80 is protected in Unix, the web server
needs to start as root to bind to port 80.  For security, Resin should
switch to a non-root user after binding to port 80.</p>
</description>

<example title="resin.xml with user-name">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">

    &lt;server-default>
      &lt;http port="80"/>

      &lt;user-name>resin&lt;/user-name>
      &lt;group-name>www&lt;/group-name>
    &lt;/server-default>

    &lt;server id="web-a"/>
    ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;health:ActionSequence>" name="health:ActionSequence">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.ActionSequence"/>

<description>
<p>Executes a sequence of child health actions in order.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:ActionSequence> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:ActionSequence>
    &lt;health:DumpThreads/>
    &lt;health:DumpHeap/>
    &lt;health:IfHealthCritical time="5m"/>
  &lt;/health:ActionSequence>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:And>" name="health:And">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.And"/>

<description>
<p>Qualifies an action to match if all of the child predicates match.</p>

<p><i>Note: &lt;health:And> is implied and thus not strictly necessary except 
when used in conjunction with more complex combining conditions.</i></p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:And> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:And>
      &lt;health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
      &lt;health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/>      
    &lt;/health:And>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:AnomalyAnalyzer>" name="health:AnomalyAnalyzer">

<parents>cluster</parents>
<javadoc class="com.caucho.health.AnomalyAnalyzer"/>

<description>
<p>AnomalyAnalyzer examines a meter value, checking for deviations from the 
average value. So unusual changes like a spike in blocked threads can be 
detected, logged, and trigger health actions.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>meter</td>
    <td>Name of the meter to analyze (ie. from &lt;health:JmxMeter>)</td>
    <td>String</td>
    <td>required</td>
  </tr>
  <tr>
    <td>health-event</td>
    <td>A string to use to match using &lt;health:IfHealthEvent></td>
    <td>String</td>
    <td>None: when absent no health event will fire</td>
  </tr>
  <tr>
    <td>min-samples</td>
    <td>Minimum number of samples required to calculate an average</td>
    <td>int</td>
    <td>60 (typically 1 hour of data)</td>
  </tr>
  <tr>
    <td>sigma-threshold</td>
    <td>The number of standard deviations for a sample to be considered an anomaly.</td>
    <td>int</td>
    <td>5</td>
  </tr>
</attributes>

<example title="Example: &lt;health:AnomalyAnalyzer> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:JmxMeter>
    &lt;name>JVM|Thread|JVM Blocked Count&lt;/name>
    &lt;objectName>resin:type=JvmThreads&lt;/objectName>
    &lt;attribute>BlockedCount&lt;/attribute>
  &lt;/health:JmxMeter>

  &lt;health:AnomalyAnalyzer>
    &lt;meter>JVM|Thread|JVM Blocked Count&lt;/meter>
    &lt;health-event>caucho.thread.anomaly.jvm-blocked&lt;/health-event>
  &lt;/health:AnomalyAnalyzer>

  &lt;health:DumpThreads>
    &lt;health:IfHealthEvent regexp="caucho.thread"/>
    &lt;health:IfNotRecent time="15m"/>
  &lt;/health:DumpThreads>
  
&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:CallJmxOperation>" name="health:CallJmxOperation">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.CallJmxOperation"/>

<description>
<p>Executes a JMX MBean operation with parameters.</p>
<p>Note: Calling a JMX operation can also be performed on-demand using the 
<var>jmx-call</var> command line.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>objectName</td>
    <td>The JMX MBean name</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>operation</td>
    <td>The method name</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>operationIndex</td>
    <td>Unique method index in case multiple methods match operation</td>
    <td>int</td>
    <td>-1</td>
  </tr>
  <tr>
    <td>param</td>
    <td>Method parameters that will be converted to the appropriate type.</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:CallJmxOperation> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:CallJmxOperation>
    &lt;objectName>java.lang:type=Threading&lt;/objectName>
    &lt;operation>resetPeakThreadCount&lt;/operation>
    &lt;health:IfNotRecent time='5m'/>
  &lt;/health:CallJmxOperation>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:ConnectionPoolHealthCheck>" name="health:ConnectionPoolHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.ConnectionPoolHealthCheck"/>

<description>
<p>Monitors the health of Resin database connection pools.   See 
<a config-tag="database">&lt;database></a> for additional information.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
</attributes>

<deftable title="&lt;health:ConnectionPoolHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>WARNING</td>
    <td>Upon exceeding <a config-tag="database">max-connections</a>.</td>
  </tr>
  <tr>
    <td>CRITICAL</td>
    <td>Upon exceeding <a config-tag="database">max-overflow-connections</a>.</td>
  </tr>
</deftable>

<example title="Example: &lt;health:ConnectionPoolHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:ConnectionPoolHealthCheck/>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:CpuHealthCheck>" name="health:CpuHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.CpuHealthCheck"/>

<description>
<p>Monitors CPU usage.  On multi-core machines, each CPU is checked 
individually.</p>
</description>  

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
  <tr>
    <td>warning-threshold</td>
    <td>CPU usage warning threshold</td>
    <td>int (percentage 0-100)</td>
    <td>95</td>
  </tr>
  <tr>
    <td>critical-threshold</td>
    <td>CPU usage critical threshold</td>
    <td>int (percentage 0-100)</td>
    <td>200 (disabled)</td>
  </tr>
</attributes>

<deftable title="&lt;health:CpuHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>WARNING</td>
    <td>Upon exceeding <var>warning-threshold</var> on any CPU.</td>
  </tr>
  <tr>
    <td>CRITICAL</td>
    <td>Upon exceeding <var>critical-threshold</var> on any CPU.</td>
  </tr>
</deftable>

<example title="Example: &lt;health:CpuHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:CpuHealthCheck>
    &lt;warning-threshold>95&lt;/warning-threshold>
    &lt;critical-threshold>99&lt;/critical-threshold>
  &lt;/health:CpuHealthCheck>
  
&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:DumpHeap>" name="health:DumpHeap">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.DumpHeap"/>

<description>
<p>Create a memory heap dump.  The heap dump will be logged to the internal log 
database and to the resin log file using 
<code>com.caucho.health.action.DumpHeap</code> as the class at 
<var>info</var> level.</p>
<p>Note: Creating a heap dump can also be performed on-demand using the 
<var>heap-dump</var> command line, and from /resin-admin.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>hprof</td>
    <td>Creates an HPROF format dump instead of human readable type.</td>
    <td>boolean</td>
    <td>false</td>
  </tr>
  <tr>
    <td>hprof-path</td>
    <td>Output path write HPROF files, if hprof = true</td>
    <td>String</td>
    <td>log/heap.hprof</td>
  </tr>
  <tr>
    <td>hprof-path-format</td>
    <td>Selects a format for generating dynamic path names using timestamp tokens.</td>
    <td>String</td>
    <td></td>
  </tr>
  <tr>
    <td>log</td>
    <td>If true, JMX dump is written to the server log in addition to 
    being stored in the internal Resin database</td> 
    <td>boolean</td>
    <td>true</td>
  </tr>
</attributes>

<example title="Example: &lt;health:DumpHeap> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:DumpHeap/>

&lt;/cluster>
</example>

<example title="Example: &lt;health:DumpHeap> in health.xml with hprof-path-format">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:DumpHeap>
    &lt;hprof>true&lt;/hprof>
    &lt;hprof-path-format>${resin.home}/log/dump-%H:%M:%S.%s.hprof&lt;/hprof-path-format>
    &lt;health:OnAbnormalStop/>
  &lt;/health:DumpHeap>

&lt;/cluster>
</example>


</defun>

<defun title="&lt;health:DumpHprofHeap>" name="health:DumpHprofHeap">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.DumpHprofHeap"/>

<description>
<p>Shortcut for &lt;health:DumpHeap hprof='true'/></p>
</description>

</defun>

<defun title="&lt;health:DumpJmx>" name="health:DumpJmx">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.DumpJmx"/>

<description>
<p>Health action to create a dump of all JMX attributes and values.  The JMX 
dump will be logged to the internal log database and to the resin log file 
using <code>com.caucho.health.action.DumpJmx</code> as the class at 
<var>info</var> level.</p>
<p>Note: Creating a JMX dump can also be performed on-demand using the 
<var>jmx-dump</var> command line.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>log</td>
    <td>If true, JMX dump is written to the server log in addition to 
    being stored in the internal Resin database</td> 
    <td>boolean</td>
    <td>false</td>
  </tr>
</attributes>

<example title="Example: &lt;health:DumpJmx> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:DumpJmx/>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:DumpThreads>" name="health:DumpThreads">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.DumpThreads"/>

<description>
<p>Create a thread dump.  The thread dump will be logged to the internal log 
database and log file using <code>com.caucho.health.action.DumpThreads</code> 
as the class at <var>info</var> level.</p>
<p>Note: Creating a thread dump can also be performed on-demand using the 
<var>thread-dump</var> command line.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>only-active</td>
    <td>Output only currently active threads (<var>RUNNABLE</var> state)</td>
    <td>boolean</td>
    <td>false</td>
  </tr>
  <tr>
    <td>log</td>
    <td>If true, JMX dump is written to the server log in addition to 
    being stored in the internal Resin database</td> 
    <td>boolean</td>
    <td>true</td>
  </tr>
</attributes>

<example title="Example: &lt;health:DumpThreads> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:DumpThreads>
    &lt;only-active>false&lt;/only-active>
  &lt;/health:DumpThreads>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:ExecCommand>" name="health:ExecCommand">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.ExecCommand"/>

<description>
<p>Execute an operating system shell command.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>command</td>
    <td>The command to execute, relative to <var>dir</var> if set</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>dir</td>
    <td>The directory to execute from</td>
    <td>java.io.File</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>timeout</td>
    <td>Timeout on execution of the command, after which it will be killed if not complete</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>2s</td>
  </tr>
  <tr>
    <td>env</td>
    <td>A custom env variable, available to the command.</td>
    <td>Name/Value Pair</td>
    <td>N/A (System variables are available by default)</td>
  </tr>
</attributes>

<example title="Example: &lt;health:ExecCommand> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:ExecCommand>
    &lt;dir>/tmp&lt;/dir>
    &lt;command>remediation.sh&lt;/command>
    &lt;timeout>2s&lt;/timeout>
    &lt;env>
      &lt;name>resin_home&lt;/name>
      &lt;value>${resin.home}&lt;/value>
    &lt;/env>
    &lt;env>
      &lt;name>password&lt;/name>
      &lt;value>foo&lt;/value>
    &lt;/env>
  &lt;/health:ExecCommand>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:ExprHealthCheck>" name="health:ExprHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.ExprHealthCheck"/>

<description>
<p>Evaluates user supplied EL expressions to a boolean.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
  <tr>
    <td>fatal-test</td>
    <td>EL expression that will trigger FATAL if it evaluates to true</td>
    <td><a javadoc="com.caucho.el.Expr">Expr</a></td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>critical-test</td>
    <td>EL expression that will trigger CRITICAL if it evaluates to true</td>
    <td><a javadoc="com.caucho.el.Expr">Expr</a></td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>warning-test</td>
    <td>EL expression that will trigger WARNING if it evaluates to true</td>
    <td><a javadoc="com.caucho.el.Expr">Expr</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<deftable title="&lt;health:ExprHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>FATAL</td>
    <td>If any fatal-test expression evaluates to true</td>
  </tr>
  <tr>
    <td>CRITICAL</td>
    <td>If any critical-test expression evaluates to true</td>
  </tr>
  <tr>
    <td>WARNING</td>
    <td>If any warning-test expression evaluates to true</td>
  </tr>
</deftable>

<example title="Example: &lt;health:ExprHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:ExprHealthCheck>
    &lt;critical-test>${mbean('java.lang:type=Threading').ThreadCount > 100}&lt;/critical-test>
  &lt;/health:ExprHealthCheck>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:FailSafeRestart>" name="health:FailSafeRestart">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.FailSafeRestart"/>

<description>
<p>A timed restart of Resin, normally used in conjunction with an 
ActionSequence to gather shutdown information</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>timeout</td>
    <td>Time to force a restart if one has not yet occurred.</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:FailSafeRestart> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:ActionSequence>
    &lt;health:FailSafeRestart timeout="10m"/>
    &lt;health:DumpThreads/>
    &lt;health:DumpHeap/>
    &lt;health:StartProfiler active-time="5m"/>
    &lt;health:Restart/>
    
    &lt;health:IfHealthCritical time="5m"/>
  &lt;/health:ActionSequence>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:HealthSystem>" name="health:HealthSystem">

<parents>cluster</parents>
<javadoc class="com.caucho.health.HealthSystem"/>

<description>
<p>Configures overall health checking frequency and recheck rules.  This 
element is present in health.xml for clarity, but is not strictly required 
since it will be created upon startup with default values.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>All health checking enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
  <tr>
    <td>startup-delay</td>
    <td>The time after startup before actions are triggered (checks still execute).</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>15m</td>
  </tr>
  <tr>
    <td>period</td>
    <td>The time between checks</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>5m</td>
  </tr>
  <tr>
    <td>recheck-period</td>
    <td>The time between rechecks</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>30s</td>
  </tr>
  <tr>
    <td>recheck-max</td>
    <td>The number of rechecks before returning to the normal checking period</td>
    <td>int</td>
    <td>10</td>
  </tr>
</attributes>

<example title="Example: &lt;health:HealthSystem> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:HealthSystem>
    &lt;enabled>true&lt;/enabled>
    &lt;startup-delay>15m&lt;/startup-delay>
    &lt;period>5m&lt;/period>
    &lt;recheck-period>30s&lt;/recheck-period>
    &lt;recheck-max>10&lt;/recheck-max>
  &lt;/health:HealthSystem>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:HealthSystemHealthCheck>" name="health:HealthSystemHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.HealthSystemHealthCheck"/>

<description>
<p>Monitors the health system itself by using a separate thread to detect if 
health checking is frozen or taking too long.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
  <tr>
    <td>thread-check-period</td>
    <td>The polling frequency of the independent thread.</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>1m</td>
  </tr>
  <tr>
    <td>freeze-timeout</td>
    <td>The max time for no health checks to occur to declare the health system frozen</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>15m</td>
  </tr>
</attributes>

<deftable title="&lt;health:HealthSystemHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>FATAL</td>
    <td>If health checking has not occurred within <var>freeze-timeout</var>.</td>
  </tr>
  <tr>
    <td>FATAL</td>
    <td>If health checking has not completed within an acceptable time, 
    calculated using <a config-tag="health:HealthSystem">&lt;health:HealthSystem></a>  <var>startup-delay</var>, <var>period</var>, and 
    <var>recheck-period</var>.</td>
  </tr>
</deftable>

<example title="Example: &lt;health:HealthSystemHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:HealthSystemHealthCheck>
    &lt;thread-check-period>1m&lt;/thread-check-period>
    &lt;freeze-timeout>15m&lt;/freeze-timeout>
  &lt;/health:HealthSystemHealthCheck>
  
&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:HeartbeatHealthCheck>" name="health:HeartbeatHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.HeartbeatHealthCheck"/>

<description>
<p>Monitors for heartbeats from other members of the cluster.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
</attributes>

<deftable title="&lt;health:HeartbeatHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>WARNING</td>
    <td>If no heartbeat has been received from a know member of the cluster.</td>
  </tr>
  <tr>
    <td>WARNING</td>
    <td>If a heartbeat has not been received in the last 180 seconds from a known member of the cluster.</td>
  </tr>
</deftable>

<example title="Example: &lt;health:HeartbeatHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:HeartbeatHealthCheck/>
  
&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:HttpStatusHealthCheck>" name="health:HttpStatusHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.HttpStatusHealthCheck"/>

<description>
<p>Monitors one or more URLs on the current Resin instance by making an HTTP 
GET request and comparing the returned HTTP status code to a pattern.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
  <tr>
    <td>ping-host</td>
    <td>The server's ping host (for use where <var>url</var> is a URI)</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>ping-port</td>
    <td>The server's ping port (for use where <var>url</var> is a URI)</td>
    <td>int</td>
    <td>80</td>
  </tr>
  <tr>
    <td>url</td>
    <td>A URL or URI to be tested</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>socket-timeout</td>
    <td>The socket connection timeout</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>10s</td>
  </tr>
  <tr>
    <td>regexp</td>
    <td>The HTTP status regular expression</td>
    <td>java.util.regex.Pattern</td>
    <td>200</td>
  </tr>

</attributes>

<deftable title="&lt;health:HttpStatusHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>CRITICAL</td>
    <td>If the HTTP GET request failed to connect or the status code 
    does not match the regexp.</td>
  </tr>
</deftable>

<example title="Example: &lt;health:HttpStatusHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:HttpStatusHealthCheck>
    &lt;ping-host>localhost&lt;/ping-host>
    &lt;ping-port>8080&lt;/ping-port>
    &lt;url>/custom-test-1.jsp&lt;/url>
    &lt;url>/custom-test-2.jsp&lt;/url>
    &lt;socket-timeout>2s&lt;/socket-timeout>
    &lt;regexp>^2|^3&lt;/regexp>
  &lt;/health:HttpStatusHealthCheck>

&lt;/cluster>
</example>

<p>In some clustered configurations it may be simpler to use the 
<code>&lt;server-default> &lt;ping-url></code> element rather than specifying 
the host and port in the health check itself.  <code>&lt;ping-url></code> will 
dynamically construct a URL using the current server host.  To enabled this, 
configure HttpStatusHealthCheck with no <code>&lt;url></code> elements and add 
<code>&lt;ping-url></code>to <code>&lt;server></code> or 
<code>&lt;server-default></code>.</p> 

<example title="Example: &lt;health:HttpStatusHealthCheck> using ping-url">
&lt;!-- resin.xml -->
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;

  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;ping-url>/ping-test.jsp&lt;ping-url>
    &lt;/server-default&gt;
    ...
  &lt;/cluster>
&lt;/resin>

&lt;!-- health.xml -->
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:HttpStatusHealthCheck ee:Named="serverHttpPingCheck">
    &lt;socket-timeout>5s&lt;/socket-timeout>
    &lt;regexp>200&lt;/regexp>
  &lt;/health:HttpStatusHealthCheck>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfCron>" name="health:IfCron">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfCron"/>

<description>
<p>Qualify an action to execute if the current time is in an active range configured by 
cron-style times.  This can be used both to schedule regular actions or to 
prevent restarts or other actions during critical times.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enable-at</td>
    <td>The cron enable times</td>
    <td><a javadoc="com.caucho.config.types.CronType">CronType</a></td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>disable-at-at</td>
    <td>The cron diable times</td>
    <td><a javadoc="com.caucho.config.types.CronType">CronType</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfCron> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfCron>
      &lt;enable-at>0 0 * * *&lt;/enable-at>
      &lt;disable-at>5 0 * * *&lt;/disable-at>
    &lt;/health:IfCron>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfExpr>" name="health:IfExpr">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfExpr"/>

<description>
<p>Qualifies an action to execute based on the evaluation of an JSP EL 
expression. Expression can include references to system properties, config 
properties, and JMX mbean attributes.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>test</td>
    <td>the JSP-EL expression value</td>
    <td><a javadoc="com.caucho.el.Expr">Expr</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfExpr> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfExpr>
      &lt;test>${mbean('java.lang:type=Threading').ThreadCount > 100}&lt;/test>
    &lt;/health:IfExpr>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfHealthCritical>" name="health:IfHealthCritical">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfHealthCritical"/>

<description>
<p>Qualifies an action to match if health status is CRITICAL.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>health-check</td>
    <td>The target health check</td>
    <td><a javadoc="com.caucho.health.check.HealthCheck">HealthCheck</a></td>
    <td>N/A (Overall Resin health will be used if absent)</td>
  </tr>
  <tr>
    <td>time</td>
    <td>The minimum amount of time since the status started</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfHealthCritical> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfHealthEvent>" name="health:IfHealthEvent">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfHealthEvent"/>

<description>
<p>Causes an action to fire in response to a matching health event.  This is 
usually used in combination with <a config-tag="AnomalyAnalyzer"/> with a 
&lt;health-event> attribute.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>regexp</td>
    <td>A regular expression the event must match.</td>
    <td>java.util.regex.Pattern</td>
    <td>required</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfHealthEvent> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:JmxMeter>
    &lt;name>JVM|Thread|JVM Blocked Count&lt;/name>
    &lt;objectName>resin:type=JvmThreads&lt;/objectName>
    &lt;attribute>BlockedCount&lt;/attribute>
  &lt;/health:JmxMeter>

  &lt;health:AnomalyAnalyzer>
    &lt;meter>JVM|Thread|JVM Blocked Count&lt;/meter>
    &lt;health-event>caucho.thread.anomaly.jvm-blocked&lt;/health-event>
  &lt;/health:AnomalyAnalyzer>

  &lt;health:DumpThreads>
    &lt;health:IfHealthEvent regexp="caucho.thread"/>
    &lt;health:IfNotRecent time="15m"/>
  &lt;/health:DumpThreads>
  
&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfHealthFatal>" name="health:IfHealthFatal">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfHealthFatal"/>

<description>
<p>Qualifies an action to match if health status is FATAL.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>health-check</td>
    <td>The target health check</td>
    <td><a javadoc="com.caucho.health.check.HealthCheck">HealthCheck</a></td>
    <td>N/A (Overall Resin health will be used if absent)</td>
  </tr>
  <tr>
    <td>time</td>
    <td>The minimum amount of time since the status started</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfHealthFatal> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfHealthFatal health-check="${memoryTenuredHealthCheck}"/>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfHealthOk>" name="health:IfHealthOk">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfHealthOk"/>

<description>
<p>Qualifies an action to match if health status is OK.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>health-check</td>
    <td>The target health check</td>
    <td><a javadoc="com.caucho.health.check.HealthCheck">HealthCheck</a></td>
    <td>N/A (Overall Resin health will be used if absent)</td>
  </tr>
  <tr>
    <td>time</td>
    <td>The minimum amount of time since the status started</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfHealthOk> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:Not>
      &lt;health:IfHealthOk health-check="${memoryTenuredHealthCheck}"/>
    &lt;/health:Not>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfHealthUnknown>" name="health:IfHealthUnknown">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfHealthUnknown"/>

<description>
<p>Qualifies an action to match if health status is UNKNOWN.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>health-check</td>
    <td>The target health check</td>
    <td><a javadoc="com.caucho.health.check.HealthCheck">HealthCheck</a></td>
    <td>N/A (Overall Resin health will be used if absent)</td>
  </tr>
  <tr>
    <td>time</td>
    <td>The minimum amount of time since the status started</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfHealthUnknown> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfHealthUnknown health-check="${memoryTenuredHealthCheck}"/>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfHealthWarning>" name="health:IfHealthWarning">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfHealthWarning"/>

<description>
<p>Qualifies an action to match if health status is WARNING.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>health-check</td>
    <td>The target health check</td>
    <td><a javadoc="com.caucho.health.check.HealthCheck">HealthCheck</a></td>
    <td>N/A (Overall Resin health will be used if absent)</td>
  </tr>
  <tr>
    <td>time</td>
    <td>The minimum amount of time since the status started</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfHealthWarning> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfHealthWarning health-check="${memoryTenuredHealthCheck}"/>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfMessage>" name="health:IfMessage">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfMessage"/>

<description>
<p>Qualifies an action to match the health result message to a regular expression.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>health-check</td>
    <td>The target health check</td>
    <td><a javadoc="com.caucho.health.check.HealthCheck">HealthCheck</a></td>
    <td>N/A (Overall Resin health will be used if absent)</td>
  </tr>
  <tr>
    <td>regexp</td>
    <td>The health message match regular expression</td>
    <td>java.util.regex.Pattern</td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfMessage> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfHealthCritical/>
    &lt;health:IfMessage health-check="${httpStatusCheck}" regexp="Not Found"/>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfNotRecent>" name="health:IfNotRecent">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfNotRecent"/>

<description>
<p>Qualifies an action to match at most an amount of time after the last execution.
This is usefull to prevent unecessary frequent execution of an action.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>time</td>
    <td>The time before the action can execute again.</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfNotRecent> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:HttpStatusHealthCheck ee:Named="httpStatusCheck">
    &lt;url>http://localhost:8080/test-ping.jsp&lt;/url>
  &lt;/health:HttpStatusHealthCheck>
  
  &lt;health:DumpHeap>
    &lt;health:IfHealthCritical healthCheck="${httpStatusCheck}"/>
    &lt;health:IfNotRecent time='5m'/>
  &lt;/health:DumpHeap>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfRecovered>" name="health:IfRecovered">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfRecovered"/>

<description>
<p>Qualifies an action to match upon recovery.  Recovery is defined as the 
state change from FATAL, CRITICAL, or WARNING to OK.</p> 
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>health-check</td>
    <td>The target health check</td>
    <td><a javadoc="com.caucho.health.check.HealthCheck">HealthCheck</a></td>
    <td>N/A (Overall Resin health will be used if absent)</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfRecovered> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:SendMail>
    &lt;to>admin@yourdomain&lt;/to>
    &lt;health:IfRecovered health-check="${cpuHealthCheck}"/>
  &lt;/health:SendMail> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfRechecked>" name="health:IfRechecked">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfRechecked"/>

<description>
<p>Qualifies an action to match only after the required number of rechecks 
have been performed.  Since rechecking is not a health check specific 
condition, this predicate simply matches when recheck cycle count matches the 
HealthSystem parameter <var>recheck-max</var>.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfRechecked> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfHealthFatal/>
    &lt;health:IfRechecked/>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:IfUptime>" name="health:IfUptime">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.IfUptime"/>

<description>
<p>Qualifies an action to match an amount of time after startup.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>limit</td>
    <td>The time after startup (at least)</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:IfUptime> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfUptime limit="12h"/>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:JmxDeltaMeter>" name="health:JmxDeltaMeter">

<parents>cluster</parents>
<javadoc class="com.caucho.health.meter.JmxDeltaMeter"/>

<description>
<p>Creates a meter that graphs the difference between the current and previous 
values of a numeric JMX MBean attribute.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>name</td>
    <td>The name of the meter to display in /resin-admin (see <a href="#Meter names">meter names</a>)</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>objectName</td>
    <td>The JMX MBean name</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>attribute</td>
    <td>The MBean attribute to sample</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:JmxDeltaMeter> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:JmxDeltaMeter>
    &lt;name>JVM|Compilation|Compilation Time&lt;/name>
    &lt;object-name>java.lang:type=Compilation&lt;/object-name>
    &lt;attribute>TotalCompilationTime&lt;/attribute>
  &lt;/health:JmxDeltaMeter>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:JmxMeter>" name="health:JmxMeter">

<parents>cluster</parents>
<javadoc class="com.caucho.health.meter.JmxMeter"/>

<description>
<p>Creates a meter that graphs the current value of a numeric JMX MBean 
attribute.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>name</td>
    <td>The name of the meter to display in /resin-admin (see <a href="#Meter names">meter names</a>)</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>objectName</td>
    <td>The JMX MBean name</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>attribute</td>
    <td>The MBean attribute to sample</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:JmxMeter> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:JmxMeter>
    &lt;name>OS|Memory|Physical Memory Free&lt;/name>
    &lt;object-name>java.lang:type=OperatingSystem&lt;/object-name>
    &lt;attribute>FreePhysicalMemorySize&lt;/attribute>
  &lt;/health:JmxMeter>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:JvmDeadlockHealthCheck>" name="health:JvmDeadlockHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.JvmDeadlockHealthCheck"/>

<description>
<p>Monitors for deadlocked threads, as determined by the JVM.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
</attributes>

<deftable title="&lt;health:JvmDeadlockHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>FATAL</td>
    <td>If deadlocked threads are detected.</td>
  </tr>
</deftable>

<example title="Example: &lt;health:JvmDeadlockHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:JvmDeadlockHealthCheck/>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:LicenseHealthCheck>" name="health:LicenseHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.LicenseHealthCheck"/>

<description>
<p>Checks for expiring Resin Pro license.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
  <tr>
    <td>warning-period</td>
    <td>License check warning period</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>30D</td>
  </tr>
</attributes>

<deftable title="&lt;health:LicenseHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>WARNING</td>
    <td>If license expires in less than warning-period.</td>
  </tr>
</deftable>

<example title="Example: &lt;health:LicenseHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:LicenseHealthCheck>
    &lt;warning-period>30D&lt;/warning-period>
  &lt;/health:LicenseHealthCheck>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:MemoryPermGenHealthCheck>" name="health:MemoryPermGenHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.MemoryPermGenHealthCheck"/>

<description>
<p>Monitors the amount of free memory in the JVM PermGen memory pool.  Requests 
a garbage collection if memory falls too low.</p>

<p>Note: This check does not apply to all JVM vendor implementations, and will 
report <b>UNKNOWN</b> if there is no PermGen pool.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
  <tr>
    <td>memory-free-min</td>
    <td>The critical minimum amount of free memory.</td>
    <td><a javadoc="com.caucho.config.types.Bytes">Bytes</a></td>
    <td>1m</td>
  </tr>
  <tr>
    <td>free-warning</td>
    <td>The warning threshold percentage.</td>
    <td>double (percentage 0.0 - 100.0)</td>
    <td>0.01</td>
  </tr>
  <tr>
    <td>objectName</td>
    <td>Explicitly set the MBean name to query for memory stats.  When left 
    unset the health check will search available MBeans for the appropriate 
    memory stats MBean.</td>
    <td>javax.management.ObjectName</td>
    <td>N/A</td>
  </tr>
</attributes>

<deftable title="&lt;health:MemoryPermGenHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>UNKNOWN</td>
    <td>If there is no PermGen pool (JVM vendor dependent) or the appropriate MBean could not be determined.</td>
  </tr>
  <tr>
    <td>WARNING</td>
    <td>If free memory is below <var>free-warning</var> percentage after a GC.</td>
  </tr>
  <tr>
    <td>CRITICAL</td>
    <td>If free memory is below <var>memory-free-min</var> after a GC.</td>
  </tr>
</deftable>

<example title="Example: &lt;health:MemoryPermGenHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:MemoryPermGenHealthCheck>
    &lt;memory-free-min>1m&lt;/memory-free-min>
    &lt;free-warning>0.01&lt;/free-warning>
  &lt;/health:MemoryPermGenHealthCheck>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:MemoryTenuredHealthCheck>" name="health:MemoryTenuredHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.MemoryTenuredHealthCheck"/>

<description>
<p>Monitors the amount of free memory in the JVM Tenured memory pool.  Requests 
a garbage collection if memory falls too low.  This check will monitor 
heap memory on JVMs where there is no tenured pool.</p>

<p>Note: <var>memory-free-min</var> will default to the value of 
<code>&lt;server> &lt;memory-free-min></code> if present in resin.xml.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
  <tr>
    <td>memory-free-min</td>
    <td>The critical minimum amount of free memory.</td>
    <td><a javadoc="com.caucho.config.types.Bytes">Bytes</a></td>
    <td>1m</td>
  </tr>
  <tr>
    <td>free-warning</td>
    <td>The warning threshold percentage.</td>
    <td>double (percentage 0.0 - 100.0)</td>
    <td>0.01</td>
  </tr>
  <tr>
    <td>objectName</td>
    <td>Explicitly set the MBean name to query for memory stats.  When left 
    unset the health check will search available MBeans for the appropriate 
    memory stats MBean.</td>
    <td>javax.management.ObjectName</td>
    <td>N/A</td>
  </tr>
</attributes>

<deftable title="&lt;health:MemoryTenuredHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>UNKNOWN</td>
    <td>If there is no PermGen pool (JVM vendor dependent) or the appropriate MBean could not be determined.</td>
  </tr>
  <tr>
    <td>WARNING</td>
    <td>If free memory is below <var>free-warning</var> percentage after a GC.</td>
  </tr>
  <tr>
    <td>CRITICAL</td>
    <td>If free memory is below <var>memory-free-min</var> after a GC.</td>
  </tr>
</deftable>

<example title="Example: &lt;health:MemoryTenuredHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:MemoryTenuredHealthCheck>
    &lt;memory-free-min>1m&lt;/memory-free-min>
    &lt;free-warning>0.01&lt;/free-warning>
  &lt;/health:MemoryTenuredHealthCheck>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:Nand>" name="health:Nand">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.Nand"/>

<description>
<p>Qualifies an action to match if all of the child predicates fail.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:Nand> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:Nand>
      &lt;health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
      &lt;health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/>      
    &lt;/health:Nand>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:Nor>" name="health:Nor">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.Nor"/>

<description>
<p>Qualifies an action to match if none of the child predicates match.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:Nor> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:Nor>
      &lt;health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
      &lt;health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/>      
    &lt;/health:Nor>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:Not>" name="health:Not">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.Not"/>

<description>
<p>Qualifies an action to match if the child predicate is false.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:Not> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
    &lt;health:Not>
      &lt;health:IfCron>
        &lt;enable-at>0 7 * * *&lt;/enable-at>
        &lt;disable-at>0 11 * * *&lt;/disable-at>
      &lt;/health:IfCron>
    &lt;/health:Not>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:OnAbnormalStop>" name="health:OnAbnormalStop">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.OnAbnormalStop"/>

<description>
<p>Qualifies an action to match only when Resin is stopping with an non-OK 
exit code.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>normal-exit-code</td>
    <td>Add an OK exit code; one that will not trigger this condition.</td>
    <td><a javadoc="com.caucho.env.shutdown.ExitCode"/></td>
    <td>[OK,MODIFIED,WATCHDOG_EXIT]</td>
  </tr>
</attributes>

<example title="Example: &lt;health:OnAbnormalStop> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:PdfReport snapshot='true'>
    &lt;health:OnAbnormalStop/>
  &lt;/health:PdfReport 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:OnRestart>" name="health:OnRestart">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.OnRestart"/>

<description>
<p>Qualifies an action to match only when Resin is restarted by the watchdog.  
This generally only occurs during an error condition.  <a href="#health:OnStart">
OnStart</a> will fire during this event also.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:OnRestart> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:SendMail>
    &lt;to>admin@yourdomain.com&lt;/to>
    &lt;health:OnRestart/>
  &lt;/health:SendMail> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:OnStart>" name="health:OnStart">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.OnStart"/>

<description>
<p>Qualifies an action to match only when Resin is starting.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:OnStart> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:SendMail>
    &lt;to>admin@yourdomain.com&lt;/to>
    &lt;health:OnStart/>
  &lt;/health:SendMail> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:OnStop>" name="health:OnStop">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.OnStop"/>

<description>
<p>Qualifies an action to match only when Resin is stopping.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:OnStop> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:SendMail>
    &lt;to>admin@yourdomain.com&lt;/to>
    &lt;health:OnStop/>
  &lt;/health:SendMail> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:Or>" name="health:Or">

<parents>cluster</parents>
<javadoc class="com.caucho.health.predicate.Or"/>

<description>
<p>Qualifies an action to match if any of the child predicates match.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:Or> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:Restart>
    &lt;health:Or>
      &lt;health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
      &lt;health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/>      
    &lt;/health:Or>
  &lt;/health:Restart> 

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:PdfReport>" name="health:PdfReport">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.PdfReport"/>

<description>
<p>Health action to generate a PDF report from a PHP script.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>path</td>
    <td>Path to a PDF generating .php file</td>
    <td>String</td>
    <td>${resin.home}/doc/admin/pdf-gen.php</td>
  </tr>
  <tr>
    <td>report</td>
    <td>Report type key</td>
    <td>String</td>
    <td>Summary</td>
  </tr>
  <tr>
    <td>period</td>
    <td>Report look back period of time</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>7D</td>
  </tr>
  <tr>
    <td>log-path</td>
    <td>PDF output directory</td>
    <td>String</td>
    <td>${resin.logDirectory}</td>
  </tr>
  <tr>
    <td>mail</td>
    <td>A <a config-tag="mail">&lt;mail></a> resource to use, see example</td>
    <td>javax.mail.Session</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>mail-to</td>
    <td>A "TO:" address; a mail recipient</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>mail-from</td>
    <td>The "FROM:" address</td>
    <td>String</td>
    <td>resin@localhost</td>
  </tr>
</attributes>

<example title="Example: &lt;health:PdfReport> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:PdfReport>
    &lt;path>${resin.home}/doc/admin/pdf-gen.php&lt;/path>
    &lt;report>Summary&lt;/report>
    &lt;period>7D&lt;/report>
    &lt;health:IfCron value="0 0 * * 0"/>
  &lt;/health:PdfReport>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:Restart>" name="health:Restart">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.Restart"/>

<description>
<p>Restart Resin.  Resin will exit with the reason HEALTH.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td colspan="4">None</td>
  </tr>
</attributes>

<example title="Example: &lt;health:Restart> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:Restart/>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:ScoreboardReport>" name="health:ScoreboardReport">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.ScoreboardReport"/>

<description>
<p>Produces a concise thread activity report for groups of related threads.</p>
<p>Note: A scoreboard report can also be produced using the  
<var>scoreboard</var> command line.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>log</td>
    <td>Output to server log in addition to pdf report</td>
    <td>Boolean</td>
    <td>false</td>
  </tr>
  <tr>
    <td>type</td>
    <td>Scoreboard report type</td>
    <td>String</td>
    <td>resin</td>
  </tr>
  <tr>
    <td>greedy</td>
    <td>If false threads can be categoried into more than one group</td>
    <td>Boolean</td>
    <td>true</td>
  </tr>
</attributes>

<example title="Example: &lt;health:ScoreboardReport> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:ScoreboardReport>
    &lt;health:OnAbnormalStop/>
  &lt;/health:ScoreboardReport>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:SetJmxAttribute>" name="health:SetJmxAttribute">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.SetJmxAttribute"/>

<description>
<p>Sets a JMX attribute to a value.</p>
<p>Note: Setting a JMX attribute can also be performed on-demand using the 
<var>jmx-set</var> command line.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>objectName</td>
    <td>The JMX MBean name</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>attribute</td>
    <td>The attribute name</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>value</td>
    <td>New attribute value that will be converted to the appropriate type.</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:SetJmxAttribute> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:SetJmxAttribute>
    &lt;objectName>java.lang:type=ClassLoading&lt;/objectName>
    &lt;attribute>Verbose&lt;/attribute>
    &lt;value>true&lt;/value>
    &lt;health:OnStart/>
  &lt;/health:SetJmxAttribute>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:SendMail>" name="health:SendMail">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.SendMail"/>

<description>
<p>Send an email containing a summary of the current Resin health status.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>to</td>
    <td>A "TO:" address; a mail recipient</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>from</td>
    <td>The "FROM:" address</td>
    <td>String</td>
    <td>resin@localhost</td>
  </tr>
  <tr>
    <td>mail</td>
    <td>A <a config-tag="mail">&lt;mail></a> resource to use, see example</td>
    <td>javax.mail.Session</td>
    <td>N/A</td>
  </tr>
</attributes>

<p>Without the <var>mail</var> parameter, the default behaviour for sending 
mail is to contact an SMTP server at host 127.0.0.1 (the localhost) on port 25. 
System properties can be used to configure a different SMTP server.</p>

<example title="resin.xml - smtp server configuration">
  &lt;system-property mail.smtp.host="127.0.0.1"/&gt;
  &lt;system-property mail.smtp.port="25"/&gt;
</example>

<example title="Example: &lt;health:SendMail> in health.xml using system properties">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:SendMail>
    &lt;to>admin@yourdomain.com&lt;/to>
    &lt;to>another_admin@yourdomain.com&lt;/to>
    &lt;from>resin@yourdomain.com&lt;/from>
  &lt;health:SendMail>

&lt;/cluster>
</example>

<p>Much more advanced SMTP options can be set by configuring a 
<a config-tag="mail">&lt;mail></a> resource to use for sending health alerts.</p>

<example title="Example: &lt;health:SendMail> in health.xml referencing a &lt;mail> resource">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;mail name="healthMailer">
    &lt;smtp-host>mail.yourdomain.com&lt;/smtp-host>
    &lt;smtp-port>25&lt;/smtp-port>
    &lt;from>resin@yourdomain.com&lt;/from>
  &lt;/mail>
  
  &lt;health:SendMail mail="${healthMailer}">
    &lt;to>admin@yourdomain.com&lt;/to>
  &lt;health:SendMail>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:SetJmxAttribute>" name="health:SetJmxAttribute">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.SetJmxAttribute"/>

<description>
<p>Sets a JMX attribute to a value.</p>
<p>Note: Setting a JMX attribute can also be performed on-demand using the 
<var>jmx-set</var> command line.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>objectName</td>
    <td>The JMX MBean name</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>attribute</td>
    <td>The attribute name</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
  <tr>
    <td>value</td>
    <td>New attribute value that will be converted to the appropriate type.</td>
    <td>String</td>
    <td>N/A</td>
  </tr>
</attributes>

<example title="Example: &lt;health:SetJmxAttribute> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:SetJmxAttribute>
    &lt;objectName>java.lang:type=ClassLoading&lt;/objectName>
    &lt;attribute>Verbose&lt;/attribute>
    &lt;value>true&lt;/value>
    &lt;health:OnStart/>
  &lt;/health:SetJmxAttribute>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:Snapshot>" name="health:Snapshot">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.Snapshot"/>

<description>
<p>A specific sequence of health actions: thread dump, heap dump, jmx dump, 
and pdf report.  This is intended to generate a permanent representation, or 
"snapshot" of the system at a point in time that includes all the 
information necessary to debug server issues.  It is usually intended to run 
in response to a unexpected issue.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>log</td>
    <td>Output to server log in addition to pdf report</td>
    <td>Boolean</td>
    <td>false</td>
  </tr>
  <tr>
    <td>path</td>
    <td>Path to a PDF generating .php file</td>
    <td>String</td>
    <td>${resin.home}/doc/admin/pdf-gen.php</td>
  </tr>
  <tr>
    <td>report</td>
    <td>Report type key</td>
    <td>String</td>
    <td>Summary</td>
  </tr>
  <tr>
    <td>period</td>
    <td>Report look back period of time</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>7D</td>
  </tr>
</attributes>

<example title="Example: &lt;health:Snapshot> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:Snapshot>
    &lt;health:OnAbnormalStop/>
  &lt;/health:Snapshot>
  
&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:StartProfiler>" name="health:StartProfiler">

<parents>cluster</parents>
<javadoc class="com.caucho.health.action.StartProfiler"/>

<description>
<p>Starts a profiler session.  Results are logged to the internal database 
and the Resin log file at INFO level.</p>
<p>Note: Starting the profiler can also be performed on-demand using the 
<var>profile</var> command line, and from /resin-admin.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>active-time</td>
    <td>The amount of time to run the profiler</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>5s</td>
  </tr>
  <tr>
    <td>sampling-rate</td>
    <td>The sampling rate</td>
    <td><a javadoc="com.caucho.config.types.Period">Period</a></td>
    <td>10ms</td>
  </tr>
  <tr>
    <td>depth</td>
    <td>The stack trace depth (use smaller number (8) for smaller impact, larger for more information.)</td>
    <td>int</td>
    <td>16</td>
  </tr>
</attributes>

<example title="Example: &lt;health:StartProfiler> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  &lt;health:ActionSequence>
    &lt;health:FailSafeRestart timeout="10m"/>
    &lt;health:DumpThreads/>
    &lt;health:DumpHeap/>
    &lt;health:StartProfiler active-time="5m"/>
    &lt;health:Restart/>
    
    &lt;health:IfHealthCritical time="5m"/>
  &lt;/health:ActionSequence>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;health:TransactionHealthCheck>" name="health:TransactionHealthCheck">

<parents>cluster</parents>
<javadoc class="com.caucho.health.check.TransactionHealthCheck"/>

<description>
<p>Monitors the Resin transaction manager for commit failures.</p>
</description>

<attributes>
  <tr>
    <th>Attribute</th>
    <th>Description</th>
    <th>Type</th>
    <th>Default</th>
  </tr>
  <tr>
    <td>enabled</td>
    <td>Check is enabled or disabled</td>
    <td>boolean</td>
    <td>true</td>
  </tr>
</attributes>

<deftable title="&lt;health:TransactionHealthCheck> Conditions">
  <tr>
    <th>HealthStatus</th>
    <th>condition</th>
  </tr>
  <tr>
    <td>WARNING</td>
    <td>If there were commit failures since the last check.</td>
  </tr>
</deftable>


<example title="Example: &lt;health:TransactionHealthCheck> in health.xml">
&lt;cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  &lt;health:TransactionHealthCheck/>

&lt;/cluster>
</example>

</defun>

<defun title="&lt;home-cluster>" name="idle-time">
<parents>home-cluster</parents>

<description>
<p>The &lt;home-cluster> specifies the default --cluster value for
dynamic servers. When Resin starts and elastic server, it looks for
a &lt;home-cluster> if the --cluster option is missing. The home cluster
will be cluster that the Resin server tries to join.</p>
</description>

<schema>
element home-cluster {
  string
}
</schema>

</defun>

<defun title="&lt;host>" name="host" version="Resin 4.0">
<parents>cluster</parents>

<description>
<p>&lt;host> configures a virtual host.  Virtual hosts must be
configured explicitly.</p>

<p>It is recommended that any &lt;host&gt; using a regexp include
a &lt;host-name&gt; to set the canonical name for the host.</p>

</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr><td>id</td>
    <td>primary host name</td>
    <td>none</td></tr>
<tr><td>regexp</td>
    <td>Regular expression based host matching</td>
    <td>none</td></tr>
<tr><td>host-name</td>
    <td>Canonical host name</td>
    <td>none</td></tr>
<tr><td>host-alias</td>
    <td>Aliases matching the same host</td>
    <td>none</td></tr>
<tr><td>secure-host-name</td>
    <td>Host to use for a redirect to SSL</td>
    <td>none</td></tr>
<tr><td>root-directory</td>
    <td>Root directory for host files</td>
    <td>parent directory</td></tr>
<tr><td>startup-mode</td>
    <td>'automatic', 'lazy', or 'manual', see <a config-tag="startup-mode"/></td>
    <td>automatic</td></tr>
</attributes>

<example title="Example: explicit host">
&lt;host host-name="www.foo.com"&gt;
  &lt;host-alias&gt;foo.com&lt;/host-alias&gt;
  &lt;host-alias&gt;web.foo.com&lt;/host-alias&gt;

  &lt;root-directory&gt;/opt/www/www.foo.com&lt;/root-directory&gt;

  &lt;web-app id="/" root-directory="webapps/ROOT"&gt;
    
  &lt;/web-app&gt;
  ...
&lt;/host&gt;
</example>

<example title="Example: regexp host">
&lt;host regexp="([^.]+)\.foo\.com"&gt;
  &lt;host-name&gt;${host.regexp[1]}.foo.com&lt;/host-name&gt;

  &lt;root-directory&gt;/var/resin/hosts/www.${host.regexp[1]}.com&lt;/root-directory&gt;

  ...
&lt;/host&gt;
</example>

</defun>

<defun title="&lt;host-alias>" name="host-alias">
<parents>host</parents>

<description>
<p>&lt;host-alias> defines a URL alias for matching HTTP requests.
Any number of &lt;host-alias> can be used for each alias.</p>

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

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

</description>

<schema>
element host-alias {
  string
}
</schema>

<example title="Example: host-alias in the resin.xml">
&lt;resin xmlns="http://caucho.com">
&lt;cluster id="">

  &lt;host id="www.foo.com" root-directory="/var/resin/foo.com">
    &lt;host-alias>foo.com&lt;/host-alias>

    &lt;web-app id=""/>
  &lt;/host>

&lt;/cluster>
&lt;/resin>
</example>

<example title="Example: host-alias in a /var/resin/hosts/foo/host.xml">
&lt;host xmlns="http://caucho.com">

  &lt;host-name>www.foo.com&lt;/host-name>
  &lt;host-alias>foo.com&lt;/host-alias>

  &lt;web-app id="" root-directory="htdocs"/>

&lt;/host>
</example>

</defun>

<defun title="&lt;host-alias-regexp>" name="host-alias-regexp">
<parents>host</parents>

<description>
<p>&lt;host-alias-regexp> defines a regular expression for matching
URLs for a given virtual host.</p>
</description>

<schema>
element host-alias-regexp {
  string
}
</schema>

<example title="Example: host-alias-regexp in the resin.xml">
&lt;resin xmlns="http://caucho.com">
&lt;cluster id="">

  &lt;host id="www.foo.com" root-directory="/var/resin/foo.com">
    &lt;host-alias-regexp>.*foo.com&lt;/host-alias-regexp>

    &lt;web-app id=""/>
  &lt;/host>

&lt;/cluster>
&lt;/resin>
</example>

</defun>
<defun title="&lt;host-default>" version="Resin 3.0" name="host-default">
<parents>cluster</parents>

<description>
<p>Defaults for a virtual host.</p>

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

</defun>

<defun title="&lt;host-deploy>" version="Resin 3.0.4" name="host-deploy">
<parents>cluster</parents>

<description>
<p>&lt;host-deploy> configures an automatic deployment directory
for virtual hosts.</p>

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

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-directory</td>
  <td>path to the archive directory</td>
  <td>path</td>
</tr>
<tr>
  <td>path</td>
  <td>path to the deploy directory</td>
  <td>required</td>
</tr>
<tr>
  <td>expand-cleanup-fileset</td>
  <td>an ant-style fileset defining which directories to cleanup when
an archive is redeployed</td>
  <td></td>
</tr>
<tr>
  <td>expand-directory</td>
  <td>path to the expansion directory</td>
  <td>path</td>
</tr>
<tr>
  <td>host-default</td>
  <td>defaults for the expanded host</td>
  <td></td>
</tr>
<tr>
  <td>host-name</td>
  <td>the default hostname, based on the directory</td>
  <td>${name}</td>
</tr>
</attributes>

<schema>
element host-deploy {
  archive-directory?
  &amp; expand-cleanup-fileset?
  &amp; expand-directory?
  &amp; host-default?
  &amp; host-name?
  &amp; path?
}
</schema>

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

<example title="&lt;host-deploy>">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">
    &lt;root-directory>/var/resin&lt;/root-directory>

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

        &lt;web-app-deploy path="webapps"/>
      &lt;/host-default>
    &lt;/host-deploy>
  &lt;/cluster>
&lt;/resin>
</example>
</examples>

</defun>

<defun title="&lt;host-name>" name="host-name">
<parents>host</parents>

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

<schema>
element host-name {
  string
}
</schema>

</defun>

<defun title="&lt;http>" name="http" version="Resin 3.0">
<parents>server</parents>

<description>
<p>&lt;http> configures a HTTP or HTTPS port listening for HTTP requests.</p>

<p>When configuring multiple JVMs, each &lt;http&gt; will have a
unique &lt;server-id&gt; which allows the -server command-line to select
which ports the server should listen to.</p>

<note>The <var>virtual-host</var> attribute overrides the browser's
Host directive, specifying the explicit host and port for
<code>request.getServerName()</code> and <code>getServerPort()</code>.
It is not used in most virtual host configurations.
Only IP-based virtual hosts which wish to ignore the browser's Host
will use @virtual-host.</note>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr><td>address/host</td>
    <td>IP address of the interface to listen to</td>
    <td>*</td></tr>
<tr><td>port</td>
    <td>port to listen to</td>
    <td>required</td></tr>
<tr><td>accept-listen-backlog</td>
    <td>configures operating system TCP listen queue size for the port</td>
    <td>4000</td></tr>
<tr><td>accept-thread-idle-timeout</td>
    <td>configures minimum spare accept-thread idle timeout</td>
    <td>120s</td></tr>
<tr><td>accept-thread-min</td>
    <td>configures the minimum number of threads listening for new connections </td>
    <td>1</td></tr>
<tr><td>accept-thread-max</td>
    <td>configures the maximum number of threads listening for new connections</td>
    <td>unbound</td></tr>
<tr><td>keepalive-connection-time-max</td>
    <td>configures an absolute max time for keepalive connections</td>
    <td>600s</td></tr>
<tr><td>keepalive-max</td>
    <td>configures the maximum number of sockets which can be used directly for keepalive connections</td>
    <td></td>
    </tr>
<tr><td>keepalive-select-enable</td>
    <td>enables the select manager for keepalives</td>
    <td>true</td></tr>
<tr><td>keepalive-select-thread-timeout</td>
    <td>configures a short timeout allowing the select manager to wait for a keepalive before detaching the thread</td>
    <td>1s</td></tr>
<tr><td>keepalive-timeout</td>
    <td>configures how long a keepalive connection should wait for a new request before closing</td>
    <td>120s</td></tr>
<tr><td>suspend-reaper-timeout</td>
    <td>configures check interval for suspended (async)connections</td>
    <td>60s</td></tr>
<tr><td>suspend-time-max</td>
    <td>configures timeout for suspended (async) connections</td>
    <td>600s</td></tr>
<tr><td>socket-timeout</td>
    <td>configures timeout for accepted socket's write and read operations</td>
    <td>120s</td></tr>
<tr><td>throttle-concurrent-max</td>
    <td>configures maximum concurrent requests (Resin Pro)</td>
    <td>unlimited</td></tr>
<tr><td>tcp-no-delay</td>
    <td>sets the NO_DELAY socket parameter</td>
    <td>true</td></tr>
<tr><td>socket-listen-backlog</td>
    <td>The socket factory's listen backlog for receiving sockets</td>
    <td>100</td></tr>
<tr><td>virtual-host</td>
    <td>forces all requests to this &lt;http&gt; to use the named virtual host</td>
    <td>none</td></tr>
<tr><td>openssl</td>
    <td>configures the port to use OpenSSL</td>
    <td>none</td></tr>
<tr><td>jsse-ssl</td>
    <td>configures the port to use JSSE for SSL</td>
    <td>none</td></tr>
</attributes>

<schema>
element http {
  (id | server-id)
  &amp; (address | host )?
  &amp; port?
  &amp; accept-listen-backlog?
  &amp; accept-thread-idle-timeout?
  &amp; accept-thread-min?
  &amp; accept-thread-max?
  &amp; connection-max?
  &amp; keepalive-connection-time-max?
  &amp; keepalive-max?
  &amp; keepalive-select-enable?
  &amp; keepalive-select-thread-timeout?
  &amp; keepalive-timeout?
  &amp; secure?
  &amp; socket-timeout?
  &amp; suspend-reaper-timeout?
  &amp; suspend-time-max?
  &amp; tcp-no-delay?
  &amp; throttle-concurrent-max?
  &amp; virtual-host?
  &amp; (openssl | jsse-ssl)?
}
</schema>

</defun>

<defun title="&lt;idle-time>" name="idle-time">
<parents>web-app</parents>

<description>
<p>The &lt;idle-time> specifies the timeout for lazy-idle web-apps.
In some configurations, web-apps are created only on demand and are
closed when no requests access the web-app.  The idle-time configures
when those web-apps should be freed.</p>

<p>For example, the resin-doc web-app uses idle-time for its
child web-apps because there are a large number of sub-web-apps for
the individual tutorials.</p>
</description>

<schema>
element idle-time {
  r_period-Type
}
</schema>

</defun>


<defun title="&lt;ignore-client-disconnect>" version="Resin 3.1" name="ignore-client-disconnect">
<parents>cluster</parents>
<default>true</default>

<description>
<p>ignore-client-disconnect configures whether Resin should ignore
disconnection exceptions from the client, or if it should send those
exceptions to the application.</p>
</description>

<schema>
element ignore-client-disconnect {
  r_boolean-Type
}
</schema>

</defun>

<defun title="&lt;invocation-cache-size>" version="Resin 3.1" name="invocation-cache-size">
<parents>cluster</parents>
<default>8192</default>

<description>
<p>Configures the number of entries in the invocation cache.
The invocation cache is used to store pre-calculated servlet and filter
chains from the URLs.  It's also used as the basis for proxy caching.</p>
</description>

<schema>
element invocation-cache-size {
  r_int-Type
}
</schema>

</defun>

<defun title="&lt;invocation-cache-max-url-length>" version="Resin 3.1" name="invocation-cache-max-url-length">
<parents>cluster</parents>
<default>256</default>

<description>
<p>Configures the longest entry cacheable in the invocation cache.
It is used to avoid certain types of denial-of-service attacks.</p>
</description>

<schema>
element invocation-cache-max-url-length {
  r_int-Type
}
</schema>

</defun>
<defun title="&lt;javac>" name="javac" occur="?">
<parents>resin, cluster, host, web-app</parents>
<default>internal</default>
  <!-- com.caucho.java.JavacConfig -->

<description>
<p>&lt;javac> configures the Java compiler for automatically compiled
files.</p>

<p>The javac configuration is used for JSP, PHP, EJB and compiling-loader
configuration. Thus you can deploy JSPs to Resin and it will use the
compiler to generate classes at runtime. In other words, you do not need
to precompile your JSPs, Java files, et al. to deploy them on Resin.</p>

<p>
The internal compiler (recommended) requires tools.jar from the JDK
installation, so a JDK must be used (not a JRE).  Sometimes the internal
compiler causes errors, creating exceptions or simply hanging and taking
up a thread. The solution is to change the compiler to use an external
compiler.
</p>

<p>
The javac compiler is included with the JDK. It performs the same function
as the internal compiler, however it is executed as an external process
and is less prone to the problems described for the internal compiler.
In resin.xml with the javac configuration option:
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>args</td>
  <td>extra arguments to pass to the compiler</td>
  <td></td>
</tr>
<tr>
  <td>compiler</td>
  <td>the compiler name: eclipse, internal, or a command-line</td>
  <td></td>
</tr>
<tr>
  <td>encoding</td>
  <td>the character encoding to use</td>
  <td>utf-8</td>
</tr>
<tr>
  <td>max-batch</td>
  <td>the maximum number of source files to batch into one compilation</td>
  <td>64</td>
</tr>
</attributes>

<schema>
element javac {
  args*
  &amp; compiler
  &amp; encoding?
  &amp; max-batch?
}
</schema>

<example title="Internal compiler">
&lt;resin xmlns="http://caucho.com/ns/resin">

 &lt;javac compiler="internal" args=""/&gt;

&lt;/resin>
</example>

<example title="javac JDK compiler">
&lt;resin xmlns="http://caucho.com/ns/resin">

 &lt;javac compiler="javac" args=""/&gt;

  ...

&lt;/resin>
</example>

</defun>

<defun title="&lt;jndi-link>" name="jndi-link" occur="*" version="Resin 1.2">
<parents>resin, cluster, host, web-app</parents>
  <!-- com.caucho.naming.LinkProxy -->

<description>
<p>&lt;jndi-link> creates a symbolic link from one jndi name to another,
or links to a foreign JNDI context.</p>

<p>Resin's JNDI can link to foreign JNDI contexts.  For example,
third-party EJB servers will often expose their EJB beans through a JNDI
context.  jndi-link will create the appropriate InitialContextFactory,
configure it, and lookup the foreign JNDI objects.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr><td>factory</td>
    <td>Class name of the JNDI InitialContextFactory.  Since Resin 1.2</td>
    <td>optional</td></tr>
<tr><td>foreign-name</td>
    <td>The target name of the symbolic link, or the sub-context of the foreign JNDI context.  Since Resin 1.2</td>
    <td>none</td></tr>
<tr><td>init-param</td>
    <td>Configuration parameters for the JNDI environment passed to InitialContextFactory.  Since Resin 1.2</td>
    <td>none</td></tr>
<tr><td>jndi-name</td>
    <td>The JNDI name to use for the link.  Resin 3.0</td>
    <td>required</td></tr>
</attributes>

<schema>
element jndi-link {
  jndi-name
  &amp; factory?
  &amp; foreign-name?
  &amp; init-param*
}
</schema>

<example title="Example: A JNDI symbolic link for a DataSource">
&lt;web-app xmlns="http://caucho.com/ns/resin"dd&gt;
  &lt;database jndi-name="jdbc/oracle"&gt;
    ...
  &lt;/database&gt;

  &lt;jndi-link jndi-name="java:comp/env/jdbc/gryffindor"&gt;
    &lt;foreign-name&gt;java:comp/env/jdbc/oracle&lt;/foreign-name&gt;
  &lt;/jndi-link&gt;

  &lt;jndi-link jndi-name="java:comp/env/jdbc/slytherin"&gt;
    &lt;foreign-name&gt;java:comp/env/jdbc/oracle&lt;/foreign-name&gt;
  &lt;/jndi-link&gt;
&lt;/web-app&gt;
</example>

<example title="Example: A JNDI foreign context for all EJB">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;jndi-link jndi-name='java:comp/env/ejb'&gt;
    &lt;factory&gt;com.caucho.ejb.hessian.HessianContextFactory&lt;/factory&gt;
    &lt;init-param java.naming.provider.url='http://ejb.hogwarts.com:80/hessian'/&gt;
  &lt;/jndi-link&gt;
&lt;/web-app&gt;
</example>

<example title="Example: A JNDI foreign context for selected EJB">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;jndi-link jndi-name='java:comp/env/remote-ejb'&gt;
    &lt;factory&gt;com.caucho.ejb.hessian.HessianContextFactory&lt;/factory&gt;
    &lt;init-param java.naming.provider.url='http://ejb.hogwarts.com:80/hessian'/&gt;
  &lt;/jndi-link&gt;

  &lt;jndi-link jndi-name="java:comp/env/ejb/Foo"&gt;
    &lt;foreign-name&gt;java:comp/env/remote-ejb/Foo&lt;/foreign-name&gt;
  &lt;/jndi-link&gt;

  &lt;jndi-link jndi-name="java:comp/env/ejb/Bar"&gt;
    &lt;foreign-name&gt;java:comp/env/local-ejb/Bar&lt;/foreign-name&gt;
  &lt;/jndi-link&gt;
&lt;/web-app&gt;
</example>

</defun>

<defun title="&lt;jpa-persistence>" name="jpa-persistence" occur="*" version="Resin 3.1">
<parents>resin, cluster, host, web-app</parents>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>create-database-schema</td>
  <td>If true, Amber will automatically create the database schema</td>
  <td>false</td>
</tr>
<tr>
  <td>cache-size</td>
  <td>Size of the entity cache</td>
  <td>32k</td>
</tr>
<tr>
  <td>data-source</td>
  <td>database used for JTA</td>
  <td></td>
</tr>
<tr>
  <td>jdbc-isolation</td>
  <td>JDBC isolation level used for connections</td>
  <td></td>
</tr>
<tr>
  <td>read-data-source</td>
  <td>Data source to be used for read-only queries</td>
  <td>data-source</td>
</tr>
<tr>
  <td>validate-database-schema</td>
  <td>enables validation of the database tables on startup</td>
  <td>false</td>
</tr>
<tr>
  <td>xa-data-source</td>
  <td>database to use in transactions</td>
  <td>data-source</td>
</tr>
</attributes>

<schema>
element jpa-persistence {
  create-database-schema?
  &amp; cache-size?
  &amp; cache-timeout?
  &amp; data-source?
  &amp; jdbc-isolation?
  &amp; persistence-unit*
  &amp; persistence-unit-default*
  &amp; read-data-source?
  &amp; validate-database-schema?
  &amp; xa-data-source?
}

element persistence-unit {
  name
  &amp; jta-data-source?
  &amp; non-jta-data-source?
  &amp; provider?
  &amp; transaction-type?
  &amp; properties?
}

element persistence-unit-default {
  &amp; jta-data-source?
  &amp; non-jta-data-source?
  &amp; provider?
  &amp; transaction-type?
  &amp; properties?
}

element properties {
  element property {
     name
     &amp; value
  }*
}
</schema>

</defun>

<defun title="&lt;jpa-persistence-unit>" name="jpa-persistence-unit" occur="*" version="Resin 3.1">
<parents>resin, cluster, host, web-app</parents>

<description>
<p>Replacement for jpa-persistence.</p>
</description>
</defun>

<defun title="&lt;jsp>" name="jsp" type="defun">
<parents>web-app</parents>

<description>
<p>Configures JSP behavior.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>auto-compile</td>
  <td>Automatically compile changed JSP files</td>
  <td>true</td>
</tr>
<tr>
  <td>deferred-syntax-allowed-as-literal</td>
  <td>enables the #{...} syntax as text contents</td>
  <td>true</td>
</tr>
<tr>
  <td>dependency-check-interval</td>
  <td>How often to check the jsp for changes, -1 disables</td>
  <td>inherited</td>
</tr>
<tr>
  <td>el-ignored</td>
  <td>Ignore EL expressions in JSP text</td>
  <td>false</td>
</tr>
<tr>
  <td>fast-jstl</td>
  <td>Optimize JSTL code generation</td>
  <td>true</td>
</tr>
<tr>
  <td>ignore-el-exception</td>
  <td>Ignore exceptions generated in EL expressions.  For debugging,
set to false</td>
  <td>true</td>
</tr>
<tr>
  <td>is-xml</td>
  <td>Default JSP pages to use XML syntax</td>
  <td>false</td>
</tr>
<tr>
  <td>page-encoding</td>
  <td>Sets the default page encoding</td>
  <td>ISO-8859-1</td>
</tr>
<tr>
  <td>precompile</td>
  <td>Try to load precompiled JSP pages</td>
  <td>true</td>
</tr>
<tr>
  <td>print-null-as-blank</td>
  <td>If true, expressions evaluating to null are not printed</td>
  <td>false</td>
</tr>
<tr>
  <td>recompile-on-error</td>
  <td>Recompile the JSP file when an Error occurs in loading</td>
  <td>false</td>
</tr>
<tr>
  <td>recycle-tags</td>
  <td>Reuse tag instances when possible for performance</td>
  <td>true</td>
</tr>
<tr>
  <td>require-source</td>
  <td>Return 404 when JSP source is deleted</td>
  <td>false</td>
</tr>
<tr>
  <td>scriping-invalid</td>
  <td>Disables all Java scripting and expression in JSP pages</td>
  <td>false</td>
</tr>
<tr>
  <td>session</td>
  <td>Creates sessions for each JSP page</td>
  <td>true</td>
</tr>
<tr>
  <td>static-page-generates-class</td>
  <td>If true, JSPs with no active content still generate a .class</td>
  <td>true</td>
</tr>
<tr>
  <td>tld-dir</td>
  <td>restricts the directory to scan for .tld files, improving startup performance</td>
  <td>WEB-INF</td>
</tr>
<tr>
  <td>tld-file-set</td>
  <td>adds an ant-style pattern for .tld scanning</td>
  <td>WEB-INF</td>
</tr>
<tr>
  <td>trim-directive-whitespace</td>
  <td>if true, trims whitespace around JSP directives</td>
  <td>false</td>
</tr>
<tr>
  <td>validate-taglib-schema</td>
  <td>if true, validate .tld files against the .tld schema.  Set to false to
handle invalid .tld files</td>
  <td>true</td>
</tr>
<tr>
  <td>velocity-enabled</td>
  <td>if true, velocity-style tags are allowed</td>
  <td>false</td>
</tr>
<tr>
  <td>character-encoding</td>
  <td>Sets JSP response character encoding; overrides character encoding defined at web-app level</td>
  <td></td>
</tr>
</attributes>

<schema>
element jsp {
  auto-compile
  &amp; deferred-syntax-allowed-as-literal?
  &amp; dependency-check-interval?
  &amp; el-ignored?
  &amp; fast-jstl?
  &amp; ide-hack?
  &amp; ignore-el-exception?
  &amp; is-xml?
  &amp; page-encoding?
  &amp; precompile?
  &amp; print-null-as-blank?
  &amp; recompile-on-error?
  &amp; recycle-tags?
  &amp; require-source?
  &amp; scripting-invalid?
  &amp; session?
  &amp; static-page-generates-class?
  &amp; tld-dir?
  &amp; tld-file-set?
  &amp; trim-directive-whitespaces?
  &amp; validate-taglib-schema?
  &amp; velocity-enabled?
}
</schema>

</defun>

<defun title="&lt;jsp-config>" name="jsp-config" version="Servlet">

<description>
<p>&lt;jsp-config> configure standard settings for JSP files.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>url-pattern</td>
  <td>selects the URLs which this jsp-config applies to</td>
  <td></td>
</tr>
<tr>
  <td>el-ignored</td>
  <td>If true, EL expressions are ignored</td>
  <td>false</td>
</tr>
<tr>
  <td>page-encoding</td>
  <td>Defines the default page encoding for the JSP file</td>
  <td>ISO-8859-1</td>
</tr>
<tr>
  <td>scripting-invalid</td>
  <td>If true, Java scripting is forbidded in the JSP page</td>
  <td>false</td>
</tr>
<tr>
  <td>trim-directive-whitespaces</td>
  <td>If true, extra whitespace is trimmed around JSP directives</td>
  <td>false</td>
</tr>
<tr>
  <td>is-xml</td>
  <td>If true, for XML syntax for JSP pages</td>
  <td>false</td>
</tr>
<tr>
  <td>include-prelude</td>
  <td>Includes JSP fragments before the JSP page as headers</td>
  <td></td>
</tr>
<tr>
  <td>include-coda</td>
  <td>Includes JSP fragments before the JSP page as footers</td>
  <td></td>
</tr>
</attributes>

<schema>
element jsp-config {
  taglib*,
  jsp-property-group*
}

element jsp-property-group {
  url-pattern*,
  deferred-syntax-allowed-as-literal?,
  el-ignored?,
  page-encoding?
  scripting-invalid?
  trim-directive-whitespaces?
  is-xml?
  include-prelude*
  include-coda*
}
</schema>

</defun>

<defun title="&lt;jvm-arg>" name="jvm-arg" version="Resin 3.1">
<parents>server</parents>

<description>
<p>&lt;jvm-arg> configures JVM arguments to be passed to Resin on
the command line, typically -X memory parameters and -D defines.</p>
</description>

<example title="standard jvm-args">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="web-tier">
    &lt;server-default>
      &lt;jvm-arg>-Xmx512m&lt;/jvm-arg>
      &lt;jvm-arg>-Xss1m&lt;/jvm-arg>
      &lt;jvm-arg>-verbosegc&lt;/jvm-arg>
    &lt;/server-default>

    &lt;server id="app-a" address="192.168.2.10"/>

    ...
  &lt;/cluster>
&lt;/resin>
</example>
</defun>

<defun title="&lt;jvm-classpath>" name="jvm-classpath" version="Resin 3.1.6">
<parents>server</parents>

<description>
<p>&lt;jvm-classpath> adds a classpath entry when starting the JVM.</p>
</description>

<example title="adding a classpath">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;jvm-classpath&gt;/tmp/test-classpath&lt;/jvm-classpath&gt;
    &lt;/server-default&gt;

    &lt;server id="app-a" address="192.168.2.10"/&gt;

    ...
  &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>
<defun title="&lt;keepalive-max>" name="keepalive-max" version="Resin 3.1">
<parents>server</parents>
<default>100</default>
<description>
<p>&lt;keepalive-max> configures the maximum number of sockets
which can be used directly for <g>keepalive</g> connections.
In Resin Professional, the <g>select manager</g> allows for
a much larger number of keepalive sockets, since it can detach
threads from connections.  Without the select manager, each
connection is associated with a thread.</p>
<p>A value of -1 disables keepalives.</p>
<p>Keepalives are an important TCP technique used with HTTP and
Resin's load-balancing to avoid the heavy network cost of creating
a new socket.  Since an initial HTTP request is usually immediately
followed by extra requests to load files like images and stylesheets,
it's generally more efficient to keep the socket open for a short time
instead of creating a new one.  The socket keepalive is even more
important for Resin's load balancing, to avoid creating extra sockets
between the web-tier and the app-tier and to make distributed sessions
more efficient.</p>
<p>Higher values of &lt;keepalive-max> improve network efficiency
but increase the number of threads waiting for new client data.</p>
</description>
<example title="keepalive-thread-max in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;http port="80"/>

      &lt;thread-max>512&lt;/thread-max>

      &lt;keepalive-max>100&lt;/keepalive-max>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>
</defun>

<defun title="&lt;keepalive-select-enable>" name="keepalive-select-enable" version="Resin 3.1">
<parents>server</parents>
<default>true</default>

<description>
<p>&lt;keepalive-select-enable> enables the select manager for
keepalives.  The select manager is a Resin Professional feature allowing
more keepalives by detaching threads from sockets.</p>

<p>Normally, this should be left enabled.</p>
</description>

</defun>

<defun title="&lt;keepalive-select-thread-timeout>" name="keepalive-select-thread-timeout" version="Resin 3.1">
<parents>server</parents>
<default>1s</default>

<description>
<p>&lt;keepalive-select-thread-timeout> is a short timeout allowing
the select manager to wait for a keepalive before detaching the
thread.  This value would not normally be changed.</p>
</description>

</defun>

<defun title="&lt;keepalive-timeout>" name="keepalive-timeout" version="Resin 3.1">
<parents>server</parents>
<default>15s</default>

<description>
<p>&lt;keepalive-timeout> configures how long a keepalive
connection should wait for a new request before closing.  </p>

<p>Keepalives are used both for HTTP connections and for load-balancing and
clustering connections.  HTTP connections generally have a single HTML page,
followed by a number of image requests.  By using keepalives, all the requests
can use a single socket.  The &lt;keepalive-timeout> should be long
enough to catch all the HTTP burst requests, but can close after the
burst is complete.  A value of 5s or 15s is generally sufficient.</p>

<p>The load-balancing and clustering keepalives have a different
timeout behavior.  Since load-balancing sockets are reused for multiple
clients, they can have longer timeouts.</p>
</description>

<example title="keepalive-thread-max in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;http port="80"/>

      &lt;thread-max>512&lt;/thread-max>

      &lt;keepalive-max>100&lt;/keepalive-max>
      &lt;keepalive-timeout>15s&lt;/keepalive-timeout>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;lazy-servlet-validate>" name="lazy-servlet-validate">
<default>false</default>

<description>
<p>&lt;lazy-servlet-validate> defers validation of servlet classes
until the servlet is used.  Some servlet libraries are bundled with
web.xml files which include servlets with no available classes.
Since Resin will normally send an error in this
situation, &lt;lazy-servlet-validate> lets you turn the validation off.</p>
</description>

<schema>
element lazy-servlet-validate {
  r_boolean-Type
}
</schema>

</defun>

<defun title="&lt;library-loader>" name="library-loader" occur="*" version="Resin 3.0">
<parents>class-loader</parents>

<description>
<p>&lt;library-loader> configures a jar library,
<var>WEB-INF/lib</var>-style class loader.</p>

<p>The library-loader will add jar files in its path to the current
classpath.  Jar files are recognized wihen they have a filename extension
of <code>.jar</code> or <code>.zip</code>.</p>

<p>See <a javadoc="com.caucho.loader.DirectoryLoader.html">DirectoryLoader</a>.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>fileset</td>
  <td>An ant-style fileset</td>
  <td></td>
</tr>
<tr>
  <td>path</td>
  <td>Filesystem path for the class loader.  Since Resin 3.0</td>
  <td>required</td>
</tr>
</attributes>

<schema>
element library-loader {
  fileset
  | path
}

element fileset {
  dir
  &amp; exclude*
  &amp; include*
}
</schema>

</defun>

<defun title="&lt;listener>" name="listener" version="Servlet">

<description>
<p>&lt;listener> configures servlet event listeners.  The listeners
are registered based on interfaces they implement.  The listener
instances are fully <a href="admin/config-candi.xtp">Resin-IoC</a> aware,
including dependency injection, observing events, and supporting aspects.</p>

<deftable title="listener interfaces">
<tr>
  <th>Interface</th>
  <th>Description</th>
</tr>
<tr>
  <td><a javadoc="javax.servlet.ServletContextListener"/></td>
  <td>Called when the web-app starts and stops</td>
</tr>
<tr>
  <td><a javadoc="javax.servlet.ServletContextAttributeListener"/></td>
  <td>Called when the web-app attributes change</td>
</tr>
<tr>
  <td><a javadoc="javax.servlet.ServletRequestListener"/></td>
  <td>Called when the request starts and stops</td>
</tr>
<tr>
  <td><a javadoc="javax.servlet.ServletRequestAttributeListener"/></td>
  <td>Called when request attributes change</td>
</tr>
<tr>
  <td><a javadoc="javax.servlet.http.HttpSessionListener"/></td>
  <td>Called when HTTP sessions start or stop</td>
</tr>
<tr>
  <td><a javadoc="javax.servlet.http.HttpSessionAttributeListener"/></td>
  <td>Called when HTTP sessions attributes change</td>
</tr>
<tr>
  <td><a javadoc="javax.servlet.http.HttpSessionActivationListener"/></td>
  <td>Called when HTTP sessions passivate or activate</td>
</tr>
</deftable>


</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>listener-class</td>
  <td>classname of the listener implementation</td>
</tr>
<tr>
  <td>init</td>
  <td>IoC initialization of the listener</td>
</tr>
</attributes>

<schema>
element listener {
  listener-class,
  init?
}
</schema>

</defun>
<defun title="&lt;load-balance-connect-timeout>" name="load-balance-connect-timeout" version="Resin 3.1">
<parents>server</parents>
<default>5s</default>

<description>
<p>&lt;load-balance-connect-timeout> configures the maximum time
a client connection to a cluster-port should
take.  The <a href="admin/clustering-overview.xtp">load balance</a> and
<a href="deploy-ref.xtp#session-config">persistent sessions</a> use load-balance-connect-timeout
to connect to backend or peer servers in the cluster.</p>

<p>Lower values detect failed servers more quickly, but a too-low value
can timeout too quickly for a live server with some network congestion.</p>
</description>

<example title="load-balance-connect-timeout">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server-default>
          &lt;load-balance-connect-timeout>2s&lt;/load-balance-connect-timeout>
        &lt;/server-default>

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>
</defun>

<defun title="&lt;load-balance-recover-time>" name="load-balance-recover-time" version="Resin 3.1">
<parents>server</parents>
<default>15s</default>

<description>
<p>&lt;load-balance-recover-time> is the maximum time
the <a href="admin/clustering-overview.xtp">load balancer</a>
will consider the server dead after a failure before retrying
the connection.</p>

<p>Resin uses the load-balance-recover-time to avoid wasting time trying to
connect to an unavailable app-tier server.</p>

<p>Lower values let the load balancer use a restarted <g>app-tier</g> server
faster, but lower values also increase the overhead of trying to
contact unavailable servers.</p>
</description>

<example title="load-balance-recover-time">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server-default>
          &lt;load-balance-recover-time>10s&lt;/load-balance-recover-time>
        &lt;/server-default>

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>
</defun>

<defun title="&lt;load-balance-idle-time>" name="load-balance-idle-time" version="Resin 3.1">
<parents>server</parents>
<default>keepalive-timeout - 1s</default>

<description>
<p>&lt;load-balance-idle-time> is the maximum time the
<a href="admin/clustering-overview.xtp">load balancer</a> and <a
href="deploy-ref.xtp#session-config">distributed sessions</a> will leave
an idle socket before closing it.</p>

<p>The default value is normally sufficient, since it tracks the keepalive
of the cluster port.</p>

<p>load-balance-idle-time must be less than the <var>keepalive</var>
value of the target <a config-tag="cluster-port">cluster-port</a>.</p>

<p>The load balancer and distributed sessions reuse sockets to the
cluster peer and <g>app-tier</g> servers to improve TCP performance.
The load-balance-idle-time limits the amount of time those sockets can
remain idle.</p>

<p>Higher values may improve the socket pooling, but may also increase
the chance of connecting to a closed server.</p>
</description>
</defun>

<defun title="&lt;load-balance-warmup-time>" name="load-balance-warmup-time" version="Resin 3.1">
<parents>server</parents>
<default>60s</default>

<description>
<p>The time the <a href="admin/clustering-overview.xtp">load balancer</a>
uses to throttle connections to an <g>app-tier</g> server that's just
starting up.</p>

<p>Java web-applications often start slowly while they initialize caches.
So a newly-started application will often be slower and consume more
resources than a long-running application.  The warmup-time increases
Resin's reliability by limiting the number of requests to a new
app-tier server until the server has warmed up.</p>

<p>Larger values give the application a longer time to warm up.</p>
</description>

<example title="load-balance-warmup-time">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server-default>
          &lt;load-balance-warmup-time>60s&lt;/load-balance-warmup-time>
        &lt;/server-default>

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;load-balance-weight>" name="load-balance-weight" version="Resin 3.1">
<parents>server</parents>
<default>100</default>
<description>
<p>load-balance-weight assigns a load-balance weight to a backend server.
Servers with higher values get more requests.  Servers with lower
values get fewer requests.</p>
<p>In some cases, some <g>app-tier</g> servers may be more powerful than
others.  load-balance-weight lets the load-balancer assign more connections
to the more powerful machines.</p>
<p>Test and profiling servers can also use load-balance-weight to receive a
small number of connections for profiling purposes.</p>
<p>Larger values tell the load-balancer to assign more requests to
the app-tier server.</p>
</description>
<example title="load-balance-weight">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.10" port="6800"/&gt;

        &lt;server id="test" address="192.168.0.100" port="6800"&gt;
            &lt;load-balance-weight>1&lt;/load-balance-weight>
        &lt;/server>

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>
</defun>

<defun title="&lt;login-config>" name="login-config" version="Servlet 2.2">
<parents>web-app</parents>
<default>no authentication</default>

<description>
<p>Configures the login method for authentication, one of BASIC,
DIGEST or FORM.</p>

<p>See also: <a href="admin/security-overview.xtp">Resin security</a> for an
overview.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>auth-method</td>
  <td>Authentication method, either <var>BASIC</var> for HTTP Basic Authentication, <var>FORM</var> for form based authentication, or <var>DIGEST</var> for HTTP <a href="admin/security-overview.xtp">Digest Authentication</a>.</td>
</tr>
<tr>
  <td>authenticator</td>
  <td>Specifies the authenticator to use to lookup users and passwords.</td>
</tr>
<tr>
  <td>class</td>
  <td>Defines a custom class which extends <a href="http://caucho.com/resin-javadoc/com/caucho/server/security/AbstractLogin.html">com.caucho.server.security.AbstractLogin</a></td>
</tr>
<tr>
  <td>form-login-config</td>
  <td>Configuration for form login.</td>
</tr>
<tr>
  <td>init</td>
  <td>Initialization for the custom login class</td>
</tr>
<tr>
  <td>realm-name</td>
  <td>The realm name to use in HTTP authentication</td>
</tr>
</attributes>

<p>HTTP Authentication is defined in the RFC <a href="http://www.faqs.org/rfcs/rfc2617.html">HTTP Authentication: Basic and
Digest</a>.</p> 

<p>HTTP digest authentication is discussed in <a href="admin/security-overview.xtp">Digest Passwords</a>.</p>

<schema>
element login-config {
  class?
  &amp; auth-method?
  &amp; authenticator?
  &amp; form-login-config?
  &amp; init?
  &amp; realm-name?
</schema>

</defun>

<defun title="&lt;log-handler>" version="Resin 4.0" name="log-handler">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
   
<description>
<p>Configure a log handler for the JDK java.util.logging.* API.
java.util.logging has two steps: configure a set of log handlers,
and configure the levels for each logger.  The &lt;log-handler> creates
a destination for logs, sets a minimum logging level for the handler,
and attaches the handler to a logging name.</p>

<p>In addition to configuring custom handlers, &lt;log-handler> has the
most common configuration build-in: logging to a rotating file.  Most of the
configuration attributes are used for the rotating file and are shared
with the other logging configuration.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-format</td>
  <td>the format for the archive filename when a rollover occurs,
        see <a config-tag="rollover">Rollovers</a>.
    </td>
  <td>see below</td>
</tr>
<tr>
  <td>class</td>
  <td>configures a custom Handler class</td>
  <td></td>
</tr>
<tr>
  <td>format</td>
  <td>An EL expression string to format the current output line.</td>
  <td></td>
</tr>
<tr>
  <td>formatter</td>
  <td>Configures a custom java.util.logging.Formatter to format
the output.</td>
  <td></td>
</tr>
<tr>
  <td>level</td>
  <td>The <a config-tag="Log-Levels">log level</a> for the handler.  Typically,
the handler's level will be finer than the logger's level</td>
  <td>info</td>
</tr>
<tr>
  <td>mbean-name</td>
  <td>an mbean name, see <a config-tag="mbean">MBean control</a>.</td>
  <td>no mbean name, no mbean registration</td>
</tr>
<tr>
  <td>name</td>
  <td>A hierarchical name, typically aligned with the Java packaging names.
The handler will be registered with the Logger with the matching name.</td>
  <td>match all names</td>
</tr>
<tr>
  <td>path</td>
  <td>Output path for the log messages, see 
       <a config-tag="path">"Log Paths"</a>
    </td>
  <td>required</td>
</tr>
<tr>
  <td>path-format</td>
  <td>Selects a format for generating path names.  The syntax is the same as for archive-format</td>
  <td>optional</td>
</tr>
<tr>
  <td>timestamp</td>
  <td>a timestamp <a config-tag="timestamp">format string</a> 
        to use at the beginning of each log line.
    </td>
  <td>"[%Y/%m/%d %H:%M:%S.%s] "</td>
</tr>
<tr>
  <td>rollover-count</td>
  <td>maximum number of rollover files before the oldest ones get overwritten.
        See <a config-tag="rollover">Rollovers</a>. 
    </td>
  <td>none</td>
</tr>
<tr>
  <td>rollover-cron</td>
  <td>cron-style specification on rollover times.</td>
  <td>none</td>
</tr>
<tr>
  <td>rollover-period</td>
  <td>how often to rollover the log.  Specify in days (15D), weeks (2W), 
        months (1M), or hours (1h). See <a config-tag="rollover">Rollovers</a>. 
    </td>
  <td>none</td>
</tr>
<tr>
  <td>rollover-size</td>
  <td>maximum size of the file before a rollover occurs, in bytes (50000), 
        kb (128kb), or megabytes (10mb).  
        See <a config-tag="rollover">Rollovers</a>.
    </td>
  <td>1mb</td>
</tr>
</attributes>

<schema>
element log-handler {
  archive-format?
  &amp; class?
  &amp; filter?
  &amp; format?
  &amp; formatter?
  &amp; level?
  &amp; mbean-name?
  &amp; name
  &amp; path?
  &amp; path-format?
  &amp; rollover-count?
  &amp; rollover-period?
  &amp; rollover-size?
  &amp; timestamp?
  &amp; use-parent-handlers?
}
</schema>

<p>The following example is a standard log handler writing to a rollover
file.  Because the handler's level is "all", the &lt;logger> configuration
will set the actual logging level.</p>

<example title="Example: logging to a rollover file">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;log-handler name="" level="all"
       timestamp="[%Y/%m/%d %H:%M:%S.%s] {%{thread}} "/>

  &lt;logger name="com.caucho" level="info"/>

&lt;/web-app>
</example>

</defun>

<defun title="&lt;logger>" name="logger" occur="*">
<parents>resin, cluster, host, web-app</parents>

<p>&lt;log> configures JDK 1.4 java.util.logger Logger level.</p>

<p>The <a href="admin/logging.xtp">log configuration</a> describes
log in detail.</p>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>level</td>
  <td>the java.util.logging level: finest, finer, fine, config, info, warning, severe</td>
  <td>info</td>
</tr>
<tr>
  <td>name</td>
  <td>the java.util.logging name, typically a classname</td>
  <td>required</td>
</tr>
<tr>
  <td>use-parent-handlers</td>
  <td>if true, parent handlers are also invoked</td>
  <td>true</td>
</tr>
</attributes>

<schema>
element logger {
  name
  &amp; level?
  &amp; use-parent-handlers?
}
</schema>

<example title="Example: compilation logging">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;log name="" level="all" path="log/debug.log"/>
  &lt;logger name="com.caucho.java" level="fine"/>

  &lt;cluster id="app-tier">
    ...
  &lt;/cluster>
&lt;/resin>
</example>

<example title="Example: logging to a JMS queue">
&lt;web-app xmlns="http://caucho.com/ns/resin"
    xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:MemoryQueue ee:Named="myQueue"/>

  &lt;logger name="qa.test">
    &lt;resin:JmsLogHandler level="warning">
      &lt;target>${myQueue}&lt;/target>

      &lt;resin:TimestampLogFormatter/>
    &lt;/resin:JmsLogHandler>
  &lt;/logger>

&lt;/web-app>
</example>
</defun>

<defun name="log format string" title="Log format string">

<description>
<p>The <var>format</var> for log tags is used to specify
a format string for each log message.  <code>format</code>
recognizes EL-expressions. The EL variable <var>log</var> is a <a
javadoc="com.caucho.log.ELFormatter.ELFormatterLogRecord"/>
 object.</p>
</description>

<example title="log format string">

&lt;log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
     format=" ${log.level} ${log.loggerName} ${log.message}"/&gt;

</example>

<deftable title="log EL variable 'log' is a LogRecord">
<tr>
  <th>Accessor</th>
  <th>Value</th>
</tr>
<tr>
  <td>${log.level}</td>
  <td>The level of the log record</td>
</tr>
<tr>
  <td>${log.name}</td>
  <td>The source loggers name</td>
</tr>
<tr>
  <td>${log.shortName}</td>
  <td>A shorter version of the source loggers name, "Foo" instead of "com.hogwarts.Foo"</td>
</tr>
<tr>
  <td>${log.message}</td>
  <td>The message, with no formatting or localization</td>
</tr>
<tr>
  <td>${log.millis}</td>
  <td>event time in milliseconds since 1970</td>
</tr>
<tr>
  <td>${log.sourceClassName}</td>
  <td>Get the name of the class that issued the logging request (may not be available at runtime)</td>
</tr>
<tr>
  <td>${log.sourceMethodName}</td>
  <td>Get the name of the method that issued the logging request (may not be available at runtime)</td>
</tr>
<tr>
  <td>${log.threadID}</td>
  <td>Get an <var>int</var> identifier of the thread where the logging request originated</td>
</tr>
<tr>
  <td>${log.thrown}</td>
  <td>Get any <code>java.lang.Throwable</code> associated with the logging request</td>
</tr>
</deftable>

<p>You can also use the <a href="admin/config-el.xtp">Environment EL variables</a> in your format string:</p>

<example title="log format string using an Environment EL variable.">
&lt;host ...&gt;

  &lt;web-app&gt;
    &lt;log name='' level='all' path='log/debug.log' timestamp="[%H:%M:%S.%s]"
         format=" [<b>${app.contextPath}</b>] ${log.message}"/&gt;

    ...
  &lt;/web-app&gt;

  ...

&lt;/host&gt;
</example>
<results>
[14:55:10.189] [/foo] `null' returning JNDI java:
       model for EnvironmentClassLoader[web-app:http://localhost:8080/foo]
[14:55:10.189] [/foo] JNDI lookup `java:comp/env/caucho/auth'
       exception javax.naming.NameNotFoundException: java:comp/env/caucho/auth
[14:55:10.199] [/foo] Application[http://localhost:8080/foo] starting

</results>

<p>The <a href="config-el.xtp#fmt.sprintf">fmt.sprintf()</a> function can
space pad the values and make the results look a little nicer:</p>

<example title="fmt.sprintf() in log format string">
&lt;log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
     format=" ${fmt.sprintf('%-7s %45s %s',log.level,log.loggerName,log.message)}"/&gt;
</example>

<results>
[14:28:08.137] INFO com.caucho.vfs.QJniServerSocket Loaded Socket JNI library.
[14:28:08.137] INFO com.caucho.server.port.Port http listening to *:8080
[14:28:08.137] INFO com.caucho.server.resin.ServletServer ServletServer[] starting
[14:28:08.307] INFO com.caucho.server.port.Port hmux listening to localhost:6802
[14:28:08.437] INFO com.caucho.server.host.Host Host[] starting 
</results>


<p><a href="config-el.xtp#fmt.sprintf">fmt.sprintf()</a> and <a href="config-el.xtp#fmt.timestamp">fmt.timestamp()</a> can be used to produce CSV files:</p>

<example title="CSV log files">
&lt;log name='' level='all' path='log/debug.csv' timestamp=""
     format="${fmt.sprintf('%vs,%d,%d,%vs,%vs',fmt.timestamp('%Y-%m-%d %H:%M:%S.%s'), 
               log.threadID, log.level.intLevel(), log.loggerName, log.message)}"/&gt;
</example>

<results>
"2003-11-17 14:46:14.529",10,800,"com.caucho.vfs.QJniServerSocket",
            "Loaded Socket JNI library."
"2003-11-17 14:46:14.549",10,800,"com.caucho.server.port.Port",
            "http listening to *:8080"
"2003-11-17 14:46:14.549",10,800,"com.caucho.server.resin.ServletServer",
            "ServletServer[] starting"
"2003-11-17 14:46:14.719",10,800,"com.caucho.server.port.Port",
            "hmux listening to localhost:6802"
"2003-11-17 14:46:14.850",10,800,"com.caucho.server.host.Host",
            "Host[] starting"
"2003-11-17 14:46:15.100",10,800,"com.caucho.server.webapp.Application",
            "Application[http://localhost:8080/freelistbm] starting"
</results>

</defun> <!-- Format-String -->

<defun title="&lt;mail>" name="mail" occur="*" version="Resin 3.0">
<parents>resin, cluster, host, web-app</parents>

<description>
<p>&lt;mail> configures a javax.mail.Session object and makes
it available in Resin-IoC/WebBeans.  Mail properties can be
configured using the properties attribute.  Some of the most common
properties can be configured directly on the &lt;mail> tag.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>authenticator</td>
  <td>sets a custom javamail authenticator, either with EL or a
  custom resin:type bean</td>
  <td></td>
</tr>
<tr>
  <td>debug</td>
  <td>sets the mail.debug flag</td>
  <td></td>
</tr>
<tr>
  <td>from</td>
  <td>sets the mail.from property</td>
  <td></td>
</tr>
<tr>
  <td>host</td>
  <td>sets the mail.host property</td>
  <td></td>
</tr>
<tr>
  <td>imap-host</td>
  <td>sets the mail.imap.host property</td>
  <td></td>
</tr>
<tr>
  <td>imap-port</td>
  <td>sets the mail.imap.port property</td>
  <td></td>
</tr>
<tr>
  <td>imap-user</td>
  <td>sets the mail.imap.user property</td>
  <td></td>
</tr>
<tr>
  <td>init</td>
  <td>IoC configuration for other properties</td>
  <td></td>
</tr>
<tr>
  <td>jndi-name</td>
  <td>JNDI name to store the mail Session</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td>Resin-IoC/WebBeans @Named value</td>
  <td></td>
</tr>
<tr>
  <td>password</td>
  <td>sets the password for authentication</td>
  <td></td>
</tr>
<tr>
  <td>pop3-host</td>
  <td>sets the mail.pop3.host property</td>
  <td></td>
</tr>
<tr>
  <td>pop3-port</td>
  <td>sets the mail.pop3.port property</td>
  <td></td>
</tr>
<tr>
  <td>pop3-user</td>
  <td>sets the mail.pop3.user property</td>
  <td></td>
</tr>
<tr>
  <td>properties</td>
  <td>general mail properties in property file format</td>
  <td></td>
</tr>
<tr>
  <td>smtp-host</td>
  <td>sets the mail.smtp.host property</td>
  <td></td>
</tr>
<tr>
  <td>smtp-port</td>
  <td>sets the mail.smtp.port property</td>
  <td></td>
</tr>
<tr>
  <td>smtp-user</td>
  <td>sets the mail.smtp.user property</td>
  <td></td>
</tr>
<tr>
  <td>store-protocol</td>
  <td>sets the mail.store.protocol property</td>
  <td></td>
</tr>
<tr>
  <td>transport-protocol</td>
  <td>sets the mail.transport.protocol property</td>
  <td></td>
</tr>
<tr>
  <td>user</td>
  <td>sets the mail.user property</td>
  <td></td>
</tr>
</attributes>

<schema>
element mail {
  authenticator?
  &amp; debug?
  &amp; from?
  &amp; host?
  &amp; imap-host?
  &amp; imap-port?
  &amp; imap-user?
  &amp; init?
  &amp; jndi-name?
  &amp; name?
  &amp; pop3-host?
  &amp; pop3-port?
  &amp; pop3-user?
  &amp; smtp-host?
  &amp; smtp-port?
  &amp; smtp-user?
  &amp; store-protocol?
  &amp; transport-protocol?
  &amp; user?
}
</schema>

<example title="Example: mail">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;mail jndi-name="java:comp/env/mail">
    &lt;from>noreply@foo.com&lt;/from>
    &lt;smtp-host>localhost&lt;/smtp-host>
    &lt;smtp-port>25&lt;/smtp-port>

    &lt;properties>
      mail.smtp.starttls.enable=true
    &lt;/properties>
  &lt;/mail>
&lt;/web-app>
</example>

</defun>

<defun title="&lt;max-active-time>" name="max-active-time" version="Resin 3.1">
<parents>database</parents>
<default>6h</default>

<description>
<p>&lt;max-active-time> configures the maximum time a connection
can be active before Resin will automatically close it.  Normally,
the max-active-time should not be configured, since Resin will
also automatically close a connection at the end of a request.</p>

<p>Sites should generally leave max-active-time at the default.</p>
</description>

</defun>

<defun title="&lt;max-close-statements>" name="max-close-statements" version="Resin 3.1">
<parents>database</parents>
<default>256</default>

<description>
<p>&lt;max-close-statements> configures how many open statements Resin
should save to for the connection close.  Since the JDBC
<code>Connection.close()</code> call automatically closes any open
statements, Resin's database pool needs to keep track of any open
statements to close them in case the application has forgotten.  The
&lt;max-close-statements> is primarily needed for older database drivers
implementing the <code>java.sql.Driver</code> interface.</p>
</description>
</defun>

<defun title="&lt;max-connections>" name="max-connections" version="Resin 3.1">
<parents>database</parents>
<default>1024</default>

<description>
<p>&lt;max-connections> configures the maximum number of
open connections allowed for Resin's database pool.  Sites
can use &lt;max-connections> to throttle the number of database
connections for an overloaded server.  When <code>max-connections</code>
is reached and an application calls <code>getConnection</code>, Resin will
wait <a config-tag="connection-wait-time">connection-wait-time</a> or until
a connection is freed before allocating a new connection.</p>
</description>
</defun>

<defun title="&lt;max-create-connections>" name="max-create-connections" version="Resin 3.1">
<parents>database</parents>
<default>5</default>

<description>
<p>&lt;max-create-connections> configures the maximum number of
simultaneous connection creations.  Since connection creation is slow
and database access can be spiky, Resin's pool limits the number
of new connections to the database at any time.  Once a connection
has succeeded, a new connection can proceed.</p>
</description>
</defun>

<defun title="&lt;max-idle-time>" name="max-idle-time" version="Resin 3.1">
<parents>database</parents>
<default>60s</default>

<description>
<p>&lt;max-idle-time> configures the maximum time a connection
can remain idle before Resin automatically closes it.  Since idle databases
tie up resources, Resin will slowly close idle connections that are no
longer needed.</p>

<p>Higher values of &lt;max-idle-time> will connections to remain in the
idle pool for a longer time.  Lower values will close idle connections
more quickly.</p>
</description>
</defun>

<defun title="&lt;max-overflow-connections>" name="max-overflow-connections" version="Resin 3.1">
<parents>database</parents>
<default>1024</default>

<description>
<p>&lt;max-overflow-connections> extends &lt;connection-max> temporarily
in case of overflow.  After the &lt;connection-wait-time> expires, Resin can
create an overflow connection to handle unforseen load spikes.</p>
</description>
</defun>

<defun title="&lt;max-pool-time>" name="max-pool-time" version="Resin 3.1">
<parents>database</parents>
<default>24h</default>

<description>
<p>&lt;max-pool-time> configures the maximum time the connection
can remain open.  A connection could theoretically remain open, switching
between active and idle, for an indefinite time.  The &lt;max-pool-time>
allows a site to limit to total time of that connection.</p>

<p>Most sites will leave &lt;max-pool-time> at the default.</p>
</description>
</defun>

<defun title="&lt;max-uri-length>" version="Resin 4.0.2" name="max-uri-length">
<parents>cluster</parents>
<default>1024</default>

<description>
<p>Sets limit on longest URIs that can be served by Resin.</p>
</description>

<schema>
element max-uri-length {
  r_int-Type
}
</schema>

</defun>

<defun title="&lt;memory-free-min>" name="memory-free-min" version="Resin 3.1">
<parents>server</parents>
<default>1m</default>

<description>
<p>&lt;memory-free-min> improves server reliability by detecting
low-memory situations caused by memory leaks and forcing a
clean server restart.  Since Resin's <g>watchdog</g> service
reliably restarts the server, a website can improve stability by forcing
a restart before memory becomes a major problem.  The memory-free-min
restart will also log a warning, notifying the developers that
a potential memory leak needs to be resolved.</p>

<p>When free heap memory gets very low, the garbage collector can
run continually trying to free up extra memory.  This continual
garbage collection can send the CPU time to 100%, cause the site to
become completely unresponsive, and yet take a long time before finally
failing to an out of memory error (forcing an unclean restart).  To avoid this
situation, Resin will detect the low-memory condition and gracefully
restart the server when free memory becomes too low.</p>

<p>The ultimate solution to any memory leak issues is to get a
memory profiler, find the leaking memory and fix it.  &lt;memory-free-min>
is just a temporary bandage to keep the site running reliably until
the memory leak can be found and fixed.</p>
</description>

<example title="memory-free-min resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;thread-max>512&lt;/thread-max>

      &lt;memory-free-min>1m&lt;/memory-free-min>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;mime-mapping>" name="mime-mapping" version="Servlet 2.2">
<parents>web-app</parents>
<description>
<p>Maps url patterns to mime-types.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>extension</td>
  <td>url extension</td>
</tr>
<tr>
  <td>mime-type</td>
  <td>the mime-type</td>
</tr>
</attributes>

<schema>
element mime-mapping {
  extension,
  mime-type
}
</schema>

<example title="Example: WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;mime-mapping&gt;
    &lt;extension&gt;.foo&lt;/extension&gt;
    &lt;mime-type&gt;text/html&lt;/mime-type&gt;
  &lt;/mime-mapping&gt;

  &lt;!-- resin shortcut syntax --&gt;
  &lt;mime-mapping extension='.bar'
                mime-type='text/html'/&gt;

&lt;/web-app&gt;
</example>

<p>Resin has a long list of default mime types in <var>$RESIN_HOME/conf/app-default.xml</var></p>
</defun>

<defun title="&lt;multipart-form>" name="multipart-form" version="Resin 1.2">
<parents>web-app</parents>

<description>
<p>Enables multipart-mime for forms and file uploads.  multipart-mime
is disabled by default.</p>

<p>For an uploaded file with a form name of <var>foo</var>, the parameter
value contains the path name to a temporary file containing the uploaded
file.  <var>foo.filename</var> contains the uploaded filename, and
<var>foo.content-type</var> contains the content-type of the uploaded file.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>upload-max</td>
  <td>maximum size of an upload request (in kb).</td>
  <td>no limit</td>
</tr>
</attributes>

<p>If the upload is larger than the limit or if multipart-form processing
is disabled, Resin will not parse the request and will set an error message
in the "<var>caucho.multipart.form.error</var>" request attribute.
The "<var>caucho.multipart.form.error.size</var>" will contain the attempted upload size.
</p>

<p>Requests can set the maximum by setting the request attribute
"<var>caucho.multipart.form.upload-max</var>" with an Integer or Long value.</p>

<p>By default, multipart-form is disabled.</p>

<schema>
element multipart-form {
  enable?
  &amp; upload-max?
}
</schema>

</defun>

<defun title="&lt;path-mapping>" name="path-mapping">
<parents>web-app</parents>

<description>
<p>Maps url patterns to real paths.  If using a server like
IIS, you may need to match the server's path aliases.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>url-pattern</td>
  <td>A pattern matching the url: <var>/foo/*</var>, <var>/foo</var>, or <var>*.foo</var></td>
</tr>
<tr>
  <td><a config-tag="url-regexp"/></td>
  <td>A regular expression matching the portion of the url that follows the <g>context path</g></td>
</tr>
<tr>
  <td>real-path</td>
  <td>The prefix of the real path.  When used with <var>url-regexp</var>, allows substitution variables like <var>$1</var>.</td>
</tr>
</attributes>

<schema>
element path-mapping {
  (url-pattern | url-regexp)

  &amp; real-path
}
</schema>

<example title="Example: resin-web.xml aliasing paths">
&lt;web-app xmlns="http://caucho.com/ns/resin">

&lt;path-mapping url-pattern='/resin/*'
              real-path='e:\resin'/&gt;

&lt;path-mapping url-regexp='/~([^/]*)'
              real-path='e:\home\$1'/&gt;

&lt;/web-app&gt;
</example>
</defun>


<defun title="&lt;password>" name="password" version="Resin 3.1">
<parents>database</parents>

<description>
<p>&lt;password> configures the database connection password.
Sites requiring additional security for their passwords can use
the &lt;mypkg:MyDecryptor/> syntax
to configure a password decoder.</p>
</description>
</defun>

<!--
<defun title="&lt;persistent-store>" version="Resin 3.0.8">
<parents>cluster</parents>

<p>Defines the cluster-aware persistent store used for
sharing distributed sessions.  The allowed types are "cluster"
and "file".  The "file" type is only recommended in single-server
configurations.</p>

<p>The &lt;persistent-store&gt; configuration is in the &lt;server&gt; level
because it needs to share update information across the
active cluster and the &lt;cluster&gt; definition is at the &lt;server&gt; level.
Sessions activate the persistent store with the &lt;use-persistent-store&gt;
tag of the &lt;session-config&gt;.</p>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>init</td>
  <td>initialization parameters for the persistent-store</td>
  <td></td>
</tr>
<tr>
  <td>type</td>
  <td>cluster, jdbc, or file</td>
  <td>required</td>
</tr>
</attributes>

<def title="&lt;persistent-store> schema">
element persistent-store {
  type
  &amp; init?
}
</def>
</defun>
-->

<defun title="&lt;ping>" occur="*" version="Resin 3.0" name="ping">
<parents>cluster</parents>

<description>
<p>Starts a thread that periodically makes a request to the server, and
restarts Resin if it fails.  This facility is used to increase server
reliability - if there is a problem with the server (perhaps from a deadlock or
an exhaustion of resources), the server is restarted.</p>

<p>A failure occurs if a request to the url returns an HTTP status that is
not 200.</p>

<p>Since the local process is restarted, it does not make sense to specify a
url that does not get serviced by the instance of Resin that has the ping
configuration.  Most configurations use url's that specify 'localhost' as
the host.</p>

<p>This pinging only catches some problems because it's running in the
same process as Resin itself.  If the entire JDK freezes, this
thread will freeze as well.  Assuming the JDK doesn't freeze, the
PingThread will catch errors like deadlocks.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>url</td>
  <td>A url to ping.</td>
  <td>required</td>
</tr>
<tr>
  <td>sleep-time</td>
  <td>Time to wait between pings.  The first ping is always 15m after the server starts, this is for subsequent pings.</td>
  <td>15m</td>
</tr>
<tr>
  <td>try-count</td>
  <td>If a ping fails, number of times to retry before giving up and restarting</td>
  <td>required</td>
</tr>
<tr>
  <td>freeze-timeout</td>
  <td>Time with no response to detect a frozen jvm.</td>
  <td>15m</td>
</tr>
<tr>
  <td>retry-time</td>
  <td>time between retries</td>
  <td>1s</td>
</tr>
<tr>
  <td>socket-timeout</td>
  <td>time to wait for server to start responding to the tcp connection before giving up</td>
  <td>10s</td>
</tr>
</attributes>

<example title="Example: resin.xml - simple usage of server ping">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;ping url="http://localhost/"/&gt;
        ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

<example title="Example: resin.xml - configured usage of server ping">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core"&gt;
    ...
    &lt;cluster id="app-tier"&gt;
        &lt;ping&gt;
            &lt;url&gt;http://localhost:8080/index.jsp&lt;/url&gt;
            &lt;url&gt;http://localhost:8080/webapp/index.jsp&lt;/url&gt;
            &lt;url&gt;http://virtualhost/index.jsp&lt;/url&gt;
            &lt;url&gt;http://localhost:443/index.jsp&lt;/url&gt;

            &lt;sleep-time&gt;5m&lt;/sleep-time&gt;
            &lt;try-count&gt;5&lt;/try-count&gt;
    
            &lt;!-- a very busy server --&gt;
            &lt;socket-timeout&gt;30s&lt;/socket-timeout&gt;
        &lt;/ping&gt;
      ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

<p>
The class that corresponds to &lt;ping&gt; is 
<a javadoc="com.caucho.admin.PingThread">PingThread</a>.  
</p>

<s2 title="Mail notification when ping fails">

<p>A refinement of the ping facility sends an email when the server is
restarted.</p>

<example title="resin.xml - mail notification when ping fails">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin"&gt;
  ...
  &lt;cluster id="web-tier"&gt;
    &lt;ping resin:type="com.caucho.server.admin.PingMailer"&gt;
      &lt;url&gt;http://localhost:8080/index.jsp&lt;/url&gt;
      &lt;url&gt;http://localhost:8080/webapp/index.jsp&lt;/url&gt;

      &lt;mail-to&gt;fred@hogwarts.com&lt;/mail-to&gt;
      &lt;mail-from&gt;resin@hogwarts.com&lt;/mail-from&gt;
      &lt;mail-subject&gt;Resin ping has failed for server ${'${'}server.name}&lt;/mail-subject&gt;
    &lt;/ping&gt;
    ...
  &lt;/server&gt;
&lt;/resin&gt;
</example>

<p>
The default behaviour for sending mail is to contact a SMTP server at host 127.0.0.1 (the localhost) on port 25.
System properties are used to configure a different SMTP server.
</p>

<example title="resin.xml - smtp server configuration">
  &lt;system-property mail.smtp.host="127.0.0.1"/&gt;
  &lt;system-property mail.smtp.port="25"/&gt;
</example>

</s2>

</defun>

<defun title="&lt;ping>" name="ping" version="Resin 3.1">
<parents>database</parents>
<default>false</default>

<description>
<p>&lt;ping> enables connection validation.  When &lt;ping> is enabled,
Resin will test the connection with <a config-tag="ping-query">&lt;ping-query></a>
or <a config-tag="ping-table">&lt;ping-table></a> before returning a connection
to the user.  If the connection fails the test, Resin will close it and
return a new connection.</p>

<p>For efficiency, Resin will only validate the connection if it
has been idle for longer than <a config-tag="ping-interval">&lt;ping-interval></a>.
</p>
</description>
</defun>

<defun title="&lt;ping-table>" name="ping-table" version="Resin 3.1">
<parents>database</parents>

<description>
<p>&lt;ping-table> configures the database table Resin should
use to verify if a connection is still valid when returned from the pool.
</p>
</description>

</defun>

<defun title="&lt;ping-query>" name="ping-query" version="Resin 3.1">
<parents>database</parents>

<description>
<p>&lt;ping-query> specifies the query to use for validating if a
database connection is still valid when returned from the idle pool.</p>
</description>

</defun>

<defun title="&lt;ping-interval>" name="ping-interval" version="Resin 3.1">
<parents>database</parents>
<default>1s</default>

<description>
<p>&lt;ping-interval> configures when Resin should validate an
idle connection.  Connections which have been idle for less than
&lt;ping-interval> are assumed to be still valid without validation.
Connections idle for longer than &lt;ping-interval> are validated.
</p>

<p>Sites can force a validation by setting &lt;ping-interval> to 0.</p>
</description>
</defun>

<defun title="&lt;port>" name="port" version="Resin 3.1">
<parents>server</parents>
<default>6800</default>
<description>
<p>The server &lt;port> defines the TCP port for Resin
cluster communication and load balancing.  Most server instances
will use a common port like 6800, while machines with multiple
servers may use multiple ports like 6800 and 6801.</p>
</description>
<example title="multiple servers on a machine ">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="app-tier"&gt;
    &lt;server id="app-a" address="192.168.1.11" port="6800"/>
    &lt;server id="app-b" address="192.168.1.11" port="6801"/>

    &lt;server id="app-b" address="192.168.2.12" port="6800"/>
    &lt;server id="app-c" address="192.168.2.12" port="6801"/>

    ...
  &lt;/cluster>
&lt;/resin>
</example>
</defun>

<defun title="&lt;port-default>" name="port-default" version="Resin 3.2.1">
<parents>server</parents>
<description>
<p>Defines default port parameters for all &lt;http>, &lt;protocol>, and
&lt;cluster-port>.</p>
</description>
</defun>

<defun title="&lt;prepared-statement-cache-size>" name="prepared-statement-cache-size" version="Resin 3.1">
<parents>database</parents>
<default>0</default>

<description>
<p>&lt;prepared-statement-cache-size> configures how many prepared
statements Resin should cache for each connection.  Caching prepared
statement can improve performance for some database drivers by avoiding
repeated parsing of the query SQL.</p>
</description>
</defun>

<defun title="&lt;protocol>" name="protocol">
<parents>servlet, servlet-mapping</parents>

<description>
<p>&lt;protocol> configures a remoting
protocol for a Java bean.  The bean is configured with the &lt;servlet>
and &lt;servlet-mapping> tags, since it will process HTTP URL requests.</p>

<p>Protocol drivers extend the <a
javadoc="com.caucho.remote.server.AbstractProtocolServletFactory"/>
interface and can register a URI alias to simplify configuration.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>class</td>
  <td>Classname of the protocol driver implementing ProtocolServletFactory</td>
</tr>
<tr>
  <td>init</td>
  <td>Optional IoC initialization for the protocol driver</td>
</tr>
<tr>
  <td>uri</td>
  <td>Protocol configuration shortcut</td>
</tr>
</attributes>

<deftable title="Current drivers">
<tr>
  <th>URI scheme</th>
  <th>Description</th>
</tr>
<tr>
  <td>burlap:</td>
  <td>The burlap XML protocol</td>
</tr>
<tr>
  <td>cxf:</td>
  <td>The CXF SOAP implementation</td>
</tr>
<tr>
  <td>hessian:</td>
  <td>The Hessian protocol</td>
</tr>
<tr>
  <td>xfire:</td>
  <td>The XFire SOAP implementation</td>
</tr>
</deftable>

<schema>
element protocol {
  (class | uri)
  &amp; init?
}
</schema>

<!-- XXX uri
<example title="Example: Hessian service in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;servlet-mapping url-pattern="/hello">
                    servlet-class="example.MyHello">
    &lt;protocol uri="hessian:"/>
  &lt;/servlet-mapping>

&lt;/web-app>
</example>
-->

</defun>

<defun title="&lt;redeploy-check-interval>" name="redeploy-check-interval">
<parents>web-app</parents>
<default>60s</default>

<description>
<p>&lt;redeploy-check-interval> specifies how often Resin should
check if a .war file has been updated or added to a
&lt;web-app-deploy> directory.</p>
</description>

<schema>
element redeploy-check-interval {
  r_period-Type
}
</schema>

</defun>

<defun title="&lt;redeploy-mode>" name="redeploy-mode">
<parents>web-app</parents>
<default>automatic</default>

<description>
<p>&lt;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.</p>
</description>

<attributes>
<tr>
  <th>Mode</th>
  <th>Description</th>
</tr>
<tr>
  <td>automatic</td>
  <td>checks for redeployment and auto-redeploy if modified </td>
</tr>
<tr>
  <td>manual</td>
  <td>does not check for redeployment.  Only checks if manual (JMX) </td>
</tr>
</attributes>

<schema>
element redeploy-mode {
  automatic | manual
}
</schema>

</defun>

<defun title="&lt;rewrite-real-path>" name="rewrite-real-path" version="Resin 3.1">
<parents>cluster, host, web-app</parents>

<description>
<p>&lt;rewrite-real-path> lets you rewrite the URL to physical path
mapping, to allow aliasing or for filesystem organization.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>real-path</td>
  <td>specifies the URL to real-path mapping</td>
</tr>
<tr>
  <td>regexp</td>
  <td>a regular expression matching a URL</td>
</tr>
<tr>
  <td>replacement</td>
  <td>specifies a replacement pattern for URL to URL rewriting</td>
</tr>
<tr>
  <td>rewrite</td>
  <td>rewrites a URL to another URL as a preprocessing-step</td>
</tr>
<tr>
  <td>target</td>
  <td>specifies the target for URL to real-path mapping</td>
</tr>
</attributes>

<schema>
element rewrite-real-path {
  element rewrite {
    regexp
    &amp; replacement
  }*

  &amp; element rewrite {
    regexp
    &amp; target
  }*
}
</schema>

<example title="Example: aliasing /foo to /bar">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;rewrite-real-path>
    &lt;real-path regexp="^/foo" target="/bar"/>
  &lt;/rewrite-real-path>

&lt;/web-app>
</example>

</defun>

<defun title="&lt;rewrite-vary-as-private>" name="rewrite-vary-as-private">

<description>
<p>Because not all browsers understand the Vary header, Resin can rewrite
Vary to a Cache-Control: private.  This rewriting will cache the page
with the Vary in Resin's proxy cache, and also cache the page in the browser.
Any other proxy caches, however, will not be able to cache the page.</p>

<p>The underlying issue is a limitation of browsers such as IE.  When IE
sees a Vary header it doesn't understand, it marks the page as uncacheable.
Since IE only understands "Vary: User-Agent", this would mean IE would
refuse to cache gzipped pages or "Vary: Cookie" pages.</p>

<p>With the &lt;rewrite-vary-as-private> tag, IE will cache the page
since it's rewritten as "Cache-Control: private" with no Vary at all.
Resin will continue to cache the page as normal.</p>
</description>

</defun>


<defun title="&lt;root-directory>" version="Resin 3.0" name="root-directory">
<parents>resin, cluster, host, web-app</parents>

<description>
<p>&lt;root-directory> specifies the base directory
for the contexts. All EL-style directory paths are relative to
the root-directory.</p>
</description>

<schema>
element root-directory {
  r_path-Type
}
</schema>

<example title="Example: cluster root-directory">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;root-directory&gt;/var/resin/app-tier&lt;/root-directory&gt;

        &lt;server id="a" ...&gt;

        &lt;host host-name="www.foo.com"&gt;
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;reference>" name="reference" occur="*" version="Resin 3.0">
<parents>resin, cluster, host, web-app</parents>
  <!-- com.caucho.config.types.ReferenceConfig -->

<description>
<p>&lt;reference> configures a JNDI ObjectFactory.  Some legacy
resources are configured using an ObjectFactory syntax.  The &lt;reference>
tag provides a compatible way to configure those objects.  More modern
resources should use &lt;bean> or &lt;component> for IoC configuration.</p>

<p>JNDI ObjectFactories are used to create objects from JNDI references.
The &lt;reference&gt; tag configures the ObjectFactory and stores it in JNDI.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>jndi-name</td>
  <td>JNDI name for the reference.  Since Resin 3.0</td>
  <td>required</td>
</tr>
<tr>
  <td>factory</td>
  <td>Class name of the ObjectFactory. Resin 3.0</td>
  <td>required</td>
</tr>
<tr>
  <td>init</td>
  <td>Bean-style initialization for the factory</td>
  <td>none</td>
</tr>
</attributes>

<schema>
element reference {
  factory 
  &amp; jndi-name
  &amp; init-param*
}
</schema>

<example title="Example: Hessian client reference">
&lt;web-app xmlns="http://caucho.com/ns/resin">

&lt;reference&gt;
  &lt;jndi-name&gt;hessian/hello&lt;/jndi-name&gt;
  &lt;factory&gt;com.caucho.hessian.client.HessianProxyFactory&lt;/factory&gt;
  &lt;init url="http://localhost:8080/ejb/hello"/&gt;
        type="test.HelloHome"/&gt;
&lt;/reference&gt;

&lt;/web-app>
</example>

</defun>

<defun title="&lt;remote-client>" name="remote-client">
<parents>cluster, host, web-app</parents>

<description>
<p>&lt;remote-client> configures a proxy to a web-service.
It uses a Java interface and a URI to select the web-service.</p>

<p>The URI is defined as: <var>protocol:url=location</var>, where
location is typically a HTTP URL.</p>

<ul>
<li>See <a href="http://wiki4.caucho.com/Does_Resin_4_Support_Remoting%3F">Resin remoting</a> for more
information, including how to write an adapter for Resin remoting.</li>

</ul>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>class</td>
  <td>Class name of the protocol implementation</td>
  <td>required (or <var>uri</var>)</td>
</tr>
<tr>
  <td>init</td>
  <td>IoC initialization for the protocol implementation</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td><a href="admin/config-candi.xtp#@Named">@Named</a> binding for Resin-IoC</td>
  <td></td>
</tr>
<tr>
  <td>jndi-name</td>
  <td>JNDI binding name</td>
  <td></td>
</tr>
<tr>
  <td>uri</td>
  <td>Shortcut alias name for the protocol class</td>
  <td></td>
</tr>
</attributes>

<deftable title="remote-client protocols">

<tr>
  <th>URI</th>
  <th>Description</th>
</tr>
<tr>
  <td><var>cxf</var>:url=http://foo.com/hello/cxf</td>
  <td>Defines a cxf service.  See <a href="http://wiki.caucho.com/CXF">http://wiki.caucho.com/CXF</a> for more information.</td>
</tr>
<tr>
  <td><var>burlap</var>:url=http://foo.com/hello/burlap</td>
  <td>Defines a burlap service at http://foo.com/hello/burlap</td>
</tr>
<tr>
  <td><var>hessian</var>:url=http://foo.com/hello/hessian</td>
  <td>Defines a hessian service at http://foo.com/hello/hessian</td>
</tr>
<tr>
  <td><var>xfire</var>:url=http://foo.com/hello/cxf</td>
  <td>Defines a xfire client.  See <a href="http://wiki.caucho.com/XFire">http://wiki.caucho.com/XFire</a> for more information.</td>
</tr>
</deftable>

<def title="remote-client">
element remote-client {
  (class|uri)
  &amp; name?
  &amp; jndi-name?
  &amp; interface
}
</def>

</defun> <!-- remote-client -->

<defun title="&lt;resin>" version="Resin 3.0" name="resin">
      
<description>
<p>&lt;resin> is the top-level configuration tag for
the resin.xml file.  The &lt;resin&gt;
tag needs to specify the Resin namespace, to allow for validation
of the configuration file.</p>

<p>The environment of the top-level &lt;resin&gt; is the global classpath.
This environment can be important for &lt;log&gt; configuration
for threads which run with using only the global class loader.
Because the &lt;resin&gt; environment does not have a dynamic class loader,
dynamically loaded classes, like custom jars
in resin/lib are not available.</p>
</description>

<schema>
element resin {
  <var>env resources</var>
  &amp; cluster*
  &amp; cluster-default*
  &amp; environment-system-properties?
  &amp; management?
  &amp; min-free-memory?
  &amp; root-directory?
  &amp; security-manager?
  &amp; security-provider?
  &amp; watchdog-manager?
}
</schema>


<example title="Example: minimal resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  &lt;root-directory>/var/resin&lt;/root-directory>

  &lt;cluster id="web-tier"&gt;
    &lt;server id="">
      &lt;http address="*" port="8080"/&gt;
    &lt;/server>

    &lt;resin:import path="app-default.xml"/&gt;

    &lt;host id="">
      &lt;web-app id="" root-directory="/var/resin/htdocs"/&gt;
    &lt;/host&gt;
  &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;resin-system-auth-key>" version="Resin 4.0.8" name="resin-system-auth-key">
<parents>resin</parents>

<description>
<p>&lt;resin-system-auth-key> specifies authorization token for Resin's Security service.</p>
</description>

<schema>
element resin-system-auth-key {
  String
}
</schema>

</defun>

<defun title="&lt;resin:AdminAuthenticator>" name="resin:AdminAuthenticator">
<javadoc class="com.caucho.security.AdminAuthenticator"/>

<description>
  <p>
    Authenticator used by Resin for administration purposes such as
    the /resin-admin application.  Also used by the watchdog and clustering
    code to authenticate servers, so changing principals or passwords 
    in this authenticator requires a shutdown and restart of the watchdog
    and Resin instances.
  </p>

  <p>
    Uses the same syntax as XmlAuthenticator.
  </p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>user</td>
  <td>Specifies a user authentication record. There maybe zero, one or more records.</td>
  <td>None</td>
</tr>
<tr>
  <td>password-digest</td>
  <td>
    Specifies the digest algorithm and format used to secure the password (see following 
    section in this document for details).
  </td>
  <td>md5-base64</td>
</tr>
<tr>
  <td>path</td>
  <td>Specifies the path to an XML file containing users and passwords.</td>
  <td>None</td>
</tr>
<tr>
  <td>logout-on-session-timeout</td>
  <td>If true, the user will be logged out when the session times out.</td>
  <td>true</td>
</tr>
</attributes>

</defun>

<defun title="&lt;resin:Allow>" name="resin:Allow">
<parents>web-app</parents>
<javadoc class="com.caucho.security.Allow"/>

<description>
<p>The &lt;resin:Allow> tag is used to secure a particular URL
pattern. Because it is affirmative, it must always include a nested
condition expressing an authorization constraint. All access attempts
that do not satisfy the authorization rule are denied access. This tag
is the most common type of top level authorization tag.</p> 
</description>

<!-- XXX: What are the defaults for this? -->
<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>url-pattern</td>
  <td>URL pattern describing the resource to be secured.</td>
</tr>
<tr>
  <td>http-method</td>
  <td>HTTP methods that the restriction applies to.</td>
</tr>
</attributes>

<example title="Protecting all pages for logged-in users">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:Allow url-pattern="/*">
    &lt;resin:IfUserInRole role="user"/>
  &lt;/resin:Allow>
  ...
&lt;/web-app&gt;
</example>
</defun>

<defun title="&lt;resin:And>" name="resin:And">
<javadoc class="com.caucho.rewrite.And"/>
<description>
<p>Matches if all children match.</p>
</description>

<example title="Matching both of two query parameters">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp="" target="/match">
    &lt;resin:And>
      &lt;resin:IfQueryParam name="foo" regexp="foo"/>
      &lt;resin:IfQueryParam name="bar" regexp="bar"/>
    &lt;/resin:And>
  &lt;/resin:Redirect>
  
&lt;/web-app>
</example>


</defun>

<defun title="&lt;resin:BasicLogin>" name="resin:BasicLogin">
<parents>web-app</parents>
<javadoc class="com.caucho.security.BasicLogin"/>
<description>
<p>
As the name implies, HTTP basic authentication is the simplest mechanism
for gathering login data for web applications. When a web page is secured
through HTTP basic authentication, the brower renders a simple dialog
box for the user to enter login information. This information is then
sent to the server in clear-text using well-defined HTTP headers. This
authentication mechanism can be convenient for quick protection of
internal pages or administration when writing a form isn't necessary. If
you use basic authentication for applications outside the fire-wall,
it is highly recommended that you secure the transport layer using <a
href="admin/security-ssl.xtp">SSL</a>. The &lt;resin:BasicLogin> tag is
used to configure basic authentication.
</p>
</description>

<example title="WEB-INF/resin-web.xml resin:BasicLogin">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:BasicLogin/>

  &lt;resin:Allow url-pattern="/foo/*">
     &lt;resin:IfUserInRole role="user"/>
  &lt;/resin:Allow>

  &lt;resin:XmlAuthenticator>
     ...
  &lt;/resin:XmlAuthenticator>
  
&lt;/web-app>  
</example>
</defun>

<defun title="&lt;resin:ByteStreamCache>" name="resin:ByteStreamCache">
<javadoc class="com.caucho.distcache.ByteStreamCache"/>
<description>
<p>
Distributed cache of InputStream/OutputStream byte streams across a cluster pod.
</p>
</description>
</defun>

<defun title="&lt;resin:choose>" name="resin:choose" version="Resin 3.0.7">

<description>
<p>resin:choose implements an if, elsif, else.</p>

<p>The &lt;resin:choose> schema is context-dependent.  A &lt;resin:choose>
in a &lt;web-app> will have &lt;web-app> content, while a &lt;resin:choose>
in a &lt;host> will have &lt;host> content.</p>

</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>resin:when</td>
  <td>A configuration section executed when matching a test condition</td>
</tr>
<tr>
  <td>resin:otherwise</td>
  <td>A fallback section executed when the tests fail</td>
</tr>
</attributes>

<schema>
element resin:choose {
  resin:when*,
  resin:otherwise
}

element resin:when {
  attribute test { string },

  <var>context-dependent content</var>
}

element resin:otherwise {
  <var>context-dependent content</var>
}
</schema>

<example title="Example: resin:choose usage pattern">
&lt;resin:choose&gt;
  &lt;resin:when test="${expr1}"&gt;
    ...
  &lt;/resin:when&gt;

  &lt;resin:when test="${expr2}"&gt;
    ...
  &lt;/resin:when&gt;

  &lt;resin:otherwise&gt;
    ...
  &lt;/resin:otherwise&gt;
&lt;resin:choose&gt;
</example>
</defun>

<defun title="&lt;resin:ClusterCache>" name="resin:ClusterCache">
<javadoc class="com.caucho.distcache.ClusterCache"/>
<description>
<p>Distributed caching is a useful technique to reduce
database load and increase application performance. Resin provides a
javax.cache.Cache (JSR-107 JCache) based distributed caching API. Distributed
caching in Resin uses the underlying infrastructure
used to support load balancing, clustering and session/state
replication.</p>
</description>

<deftable title="ClusterCache attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Type</th>
  <th>Default</th>
</tr>
<tr>
  <td>name</td>
  <td>a name is mandatory and must be unique among open caches</td>
  <td>String</td>
  <td>(required)</td>
</tr>
<tr>
  <td>manager-name</td>
  <td>the manager-name and the name forms the unique name for the cache within
      Resin</td>
  <td>String</td>
  <td></td>
</tr>
<tr>
  <td>cache-loader</td>
  <td>upon a cache miss, the cache will call the cache-loader to populate the
      value</td>
  <td>javax.cache.CacheLoader</td>
  <td></td>
</tr>
<tr>
  <td>cache-writer</td>
  <td>upon a write, the cache will call the cache-writer to save the value to
      a backing database</td>
  <td>javax.cache.CacheWriter</td>
  <td></td>
</tr>
<tr>
  <td>cache-reader-writer</td>
  <td>sets both the cache-reader and cache-writer</td>
  <td>an object that implements both javax.cache.CacheLoader and
      javax.cache.CacheWriter</td>
  <td></td>
</tr>
<tr>
  <td>serializer</td>
  <td>assign the serializer used for serializing values values</td>
  <td>com.caucho.distcache.CacheSerializer</td>
  <td></td>
</tr>
<tr>
  <td>accessed-expire-timeout</td>
  <td>the maximum idle time for an item, which is typically used for temporary
      data like sessions. For example, session data might be removed if idle
      over 30 minutes. Cached data would have infinite idle time because it
      doesn't depend on how often it's accessed.</td>
  <td>Period</td>
  <td>-1</td>
</tr>
<tr>
  <td>accessed-expire-timeout-window</td>
  <td>idle check window, used to minimize traffic when updating access times</td>
  <td>Period</td>
  <td>accessed-expire-timeout / 4</td>
</tr>
<tr>
  <td>modified-expire-timeout</td>
  <td>the maximum valid time for an item. Items stored in the cache for longer
      than the expire time are no longer valid and will return null from a
      get</td>
  <td>Period</td>
  <td>(infinity)</td>
</tr>
<tr>
  <td>lease-expire-timeout</td>
  <td>the lease timeout is the time a server can use the local version if it
      owns it, before a timeout</td>
  <td>Period</td>
  <td>5m</td>
</tr>
<tr>
  <td>local-expire-timeout</td>
  <td>the local read timeout is how long a local copy of a cache item can be
      reused before checking with the master copy. A read-only item could be
      infinite (-1). A slow changing item like a list of bulletin-board comments
      could be 10s. Even a relatively quickly changing item can be 10ms or
      100ms.</td>
  <td>Period</td>
  <td>250ms</td>
</tr>
<tr>
  <td>scope-model</td>
  <td>persistence of the cache</td>
  <td>TRANSIENT or LOCAL or CLUSTER	</td>
  <td>CLUSTER</td>
</tr>
</deftable>

<deftable title="Period format">
<tr>
  <td>ms</td>
  <td>milliseconds</td>
</tr>
<tr>
  <td>s</td>
  <td>seconds</td>
</tr>
<tr>
  <td>m</td>
  <td>minutes</td>
</tr>
<tr>
  <td>h</td>
  <td>hours</td>
</tr>
<tr>
  <td>D</td>
  <td>days</td>
</tr>
<tr>
  <td>W</td>
  <td>weeks</td>
</tr>
<tr>
  <td>M</td>
  <td>months</td>
</tr>
<tr>
  <td>Y</td>
  <td>years</td>
</tr>
</deftable>

<example title="resin-web.xml: Configuring Resin Distributed Cache">
&lt;web-app xmlns="http://caucho.com/ns/resin"
          xmlns:distcache="urn:java:com.caucho.distcache"&gt;
          
  &lt;distcache:ClusterCache ee:Named="myCacheEE"&gt;
    &lt;name&gt;myCache&lt;/name&gt;
  &lt;/distcache:ClusterCache>&gt;

&lt;/web-app&gt;
</example>

<p>
You may then inject the cache through CDI and use it in your application
via the JCache API:
</p>

<example title="Using Resin Distributed Cache">
import javax.cache.*;
import javax.inject.*;

public class MyService
{
  @Inject @Named("myCacheEE")
  private Cache&lt;String,String&gt; _cache;
  
  public void test()
  {
    _cache.putIfAbsent("foo", "bar");
  }
}

</example>

</defun>

<defun title="&lt;resin:ClusterQueue>" name="resin:ClusterQueue">
<javadoc class="com.caucho.jms.ClusterQueue"/>
<description>
<p>
  Clustered queue.
</p>
</description>
</defun>


<defun title="&lt;resin:ClusterSingleSignon>" name="resin:ClusterSingleSignon">
<javadoc class="com.caucho.security.ClusterSingleSignon"/>
<description>
<p>

  Cluster-based single signon.
</p>
</description>
</defun>

<defun title="&lt;resin:DatabaseAuthenticator>" name="resin:DatabaseAuthenticator">
<parents>cluster, host, web-app</parents>
<javadoc class="com.caucho.security.DatabaseAuthenticator"/>
<description>
<p>
The DatabaseAuthenticator asks a back-end relational database for the
password matching a user's name. It uses the DataSource specified by
the <var>data-source</var> attribute. <var>data-source</var> refers to
an existing <a href="admin/database.xtp">configured</a> DataSource.  </p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>data-source</td>
  <!-- XXX: What is a global database pool? The ones defined in resin.xml? -->
  <td>
    The pooled JDBC data source. Looks in the application attributes first, then in the
    global database pools.
  </td>
  <td>None</td>
</tr>
<tr>
  <td>password-query</td>
  <td>
    An SQL query to get the user's password given the user name. The default query is shown 
    in the code example below.
  </td>
  <td>See below</td>
</tr>
<!-- XXX: This needs to be clarified further -->
<tr>
  <td>cookie-auth-query</td>
  <td>An SQL query to authenticate the user by a persistent cookie.</td>
  <td>None</td>
</tr>
<!-- XXX: This needs to be clarified further -->
<tr>
  <td>cookie-auth-update</td>
  <td>A SQL update to match a persistent cookie to a user.</td>
  <td>None</td>
</tr>
<!-- XXX: What happens when there are multiple roles? Should they be comma-separated? -->
<tr>
  <td>role-query</td>
  <td>
    A SQL query to determine the user's role. By default, all users are in role "user", 
    but no others.
  </td>
  <td>None</td>
</tr>
<tr>
  <td>password-digest</td>
  <td>
    Specifies the digest algorithm and format used to secure the password (see following 
    section in this document for details).
  </td>
  <td>md5-base64</td>
</tr>
<tr>
  <td>logout-on-session-timeout</td>
  <td>If true, the user will be logged out when the session times out.</td>
  <td>true</td>
</tr>
</attributes>

<example title="WEB-INF/resin-web.xml for DatabaseAuthenticator">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"&gt;
  &lt;-- Authentication mechanism -->
  &lt;resin:BasicLogin/&gt;

  &lt;-- Role-based authorization -->
  &lt;resin:Allow url-pattern="/foo/*">
     &lt;resin:IfUserInRole role="user"/&gt;
  &lt;/resin:Allow>
  
  &lt;-- The authenticator -->
  &lt;resin:DatabaseAuthenticator'&gt;
    &lt;resin:data-source&gt;test&lt;/resin:data-source&gt;   
    &lt;resin:password-query&gt;
      SELECT password FROM login WHERE username=?
    &lt;/resin:password-query&gt;
    &lt;resin:cookie-auth-query&gt;
      SELECT username FROM LOGIN WHERE cookie=?
    &lt;/resin:cookie-auth-query&gt;    
    &lt;resin:cookie-auth-update&gt;
      UPDATE LOGIN SET cookie=? WHERE username=?
    &lt;/resin:cookie-auth-update&gt;
    &lt;resin:role-query&gt;
      SELECT role FROM LOGIN WHERE username=?
    &lt;/resin:role-query&gt;
  &lt;/resin:DatabaseAuthenticator&gt;
&lt;/web-app&gt;
</example>
</defun>

<defun title="&lt;resin:Deny>" name="resin:Deny">
<javadoc class="com.caucho.security.Deny"/>

<description>
<p>The &lt;resin:Deny> tag is the opposite of the top level
&lt;resin:Allow>. It restricts access to a particular URL pattern based
on any nested conditions. Access attempts that match the condition
are denied access. If no conditions are specified, all access to a URL
pattern is restricted.</p>
</description>

<!-- XXX: What are the defaults for this? -->
<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>url-pattern</td>
  <td>URL pattern describing the resource to be secured.</td>
</tr>
<tr>
  <td>http-method</td>
  <td>HTTP methods that the restriction applies to.</td>
</tr>
</attributes>

<example title="Security-constraint to protect static files">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"&gt;
  ...
  &lt;!-- protect all .properties files --&gt;
  &lt;resin:Deny url-pattern="*.properties"/>

  &lt;!-- protect the config/ subdirectory --&gt;
  &lt;resin:Deny url-pattern="/config/*"/>
  ...
&lt;/web-app&gt;
</example>
</defun>

<defun title="&lt;resin:DigestLogin>" name="resin:DigestLogin">
<parents>web-app</parents>
<javadoc class="com.caucho.security.DigestLogin"/>

<description>
<p>
The HTTP protocol includes a method to indicate to the client that
it should digest the password before sending it to the server. This
is basically a more secure variant of HTTP basic authentication. The
browser submits a digest to Resin instead of submitting a clear-text
password. HTTP digest authentication protects the password in
transmission.
</p>

<p>
When using the HTTP digest, Resin will respond to the browser when
a secure URL is accessed and ask it to calculate a digest. The steps
involved are:
</p>
<ul>
  <li>Resin provides the client a realm and some other information.</li>
  <li>
    The client obtains a user-name and password (usually through a dialog
    box with a web browser).
  </li>
  <li>
    The client calculates a digest using the user-name, realm, password,
    and other information supplied by Resin.
  </li>
  <li>The client submits the digest to Resin.</li>
  <li>Resin does the same digest calculation as the client did.</li>
  <li>
    Resin compares the submitted digest and the digest it calculated. If
    they match, the user is authenticated.
  </li>
</ul>
<p>
The advantage of this method is that the clear-text password is protected
in transmission, it cannot be determined from the digest that is submitted
by the client to the server.  The &lt;resin:DigestLogin> tag is used
to configure digest login.
</p>
</description>

<example title="Using HTTP Digest Authentication">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:DigestLogin/>
  ...
&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:Dispatch>" name="resin:Dispatch">
<javadoc class="com.caucho.rewrite.Dispatch"/>
<description>
<p>Normal servlet dispatching with optional <em>target</em> rewriting.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>regexp</td>
  <td>The regular expression of the URL to match.</td>
</tr>
<tr>
  <td>target</td>
  <td>The target to which to dispatch the request.</td>
</tr>
</attributes>

<example title="Dispatching static resources directly">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:Dispatch regexp="\.(jpg|html|txt|gif|png|js|css)$"/>
  &lt;resin:Dispatch regexp="^" target="/controller"/>

&lt;/web-app>
</example>

</defun>

<defun title="&lt;resin:ElasticCloudService>"
       name="resin:ElasticCloudService">
<javadoc class="com.caucho.admin.ElasticCloudService"/>
<description>
<p>Enables dynamic servers. When dynamic servers are enable, a new
Resin server can join a cluster by contacting the hub triad without needing
an explicit server configuration in the resin.properties or resin.xml.
</p>
</description>
</defun>

<defun title="&lt;resin:FastCgiPort>" name="resin:FastCgiPort">
<javadoc class="com.caucho.protocols.FastCgiPort"/>
<description>
<p>
  FastCGI requests, e.g. from nginx.
</p>
</description>
</defun>

<defun title="&lt;resin:FastCgiProxy>" name="resin:FastCgiProxy">
<javadoc class="com.caucho.rewrite.FastCgiProxy"/>
<description>
<p>
  Proxies the request to a backend server using FastCGI as a proxy protocol.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>regexp</td>
  <td>The regular expression of the URL to match.</td>
</tr>
<tr>
  <td>address</td>
  <td>An address of a FastCGI server (multiple allowed).</td>
</tr>
</attributes>

<example title="Proxying requests to local FastCGI processes">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

   &lt;resin:FastCgiProxy regexp="\.rb$">
     &lt;address>127.0.0.1:12345&lt;/address>
     &lt;address>127.0.0.1:67890&lt;/address>
   &lt;/resin:FastCgiProxy>

&lt;/web-app>
</example>

</defun>

<defun title="&lt;resin:FileQueue>" name="resin:FileQueue">
<javadoc class="com.caucho.jms.FileQueue"/>
<description>
<p>
  Filesystem based queue.
</p>
</description>
</defun>

<defun title="&lt;resin:FileTopic>" name="resin:FileTopic">
<javadoc class="com.caucho.jms.FileTopic"/>
<description>
<p>
  Filesystem based topic.
</p>
</description>
</defun>

<defun title="&lt;resin:Forbidden>" name="resin:Forbidden">
<javadoc class="com.caucho.rewrite.Forbidden"/>
<description>
<p>
  Send a HTTP forbidden response.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>regexp</td>
  <td>The regular expression of the URL to match.</td>
</tr>
</attributes>

<example title="Forbidding access based for unsecured connections">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Forbidden regexp="/foo">
    &lt;resin:Not>
      &lt;resin:IfSecure/>
    &lt;/resin:Not>
  &lt;/resin:Forbidden>
  
&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:FormLogin>" name="resin:FormLogin">
<javadoc class="com.caucho.security.FormLogin"/>

<description>
<p> Form-based login is the most common way collecting login
information. Using this login mechanism, you can plug-in a custom
login page with a form storing login information (usually two input
text fields for user-name and password). This custom login page can
then be used with the Resin security framework. This allows for a much
more seamless login mechanism integrated closely with your application,
especially in terms of look and feel.  </p>
<p>
When a URL is secured via form based login, the custom login form page is
used to collect authentication information. If authentication succeeds,
the user is redirected to the originally requested page. Otherwise,
the user is forwarded to an error page (that can also be configured).
</p>

<!-- XXX is this really a separate reference? -->
<p>
A login page can be anything that renders a valid login form such
as HTML, Servlet, JSP or JSF. A valid login form must have the
action <var>j_security_check</var>. It must also have the parameters
<var>j_username</var> and <var>j_password</var> holding the username
and password. Optionally, it can also have <var>j_uri</var> and
<var>j_use_cookie_auth</var>.  <var>j_uri</var> gives the next page to
display when login succeeds. If the form-uri-priority is set to true,
the user will be forwarded to the <var>j_uri</var> page regardless of
what the originally requested page was. If the attribute is set to false
(the default), the <var>j_uri</var> page is only used when the originally
requested page was the login page itself. <var>j_use_cookie_auth</var>
allows Resin to send a persistent cookie to the client to make subsequent
logins automatic. When <var>j_use_cookie_auth</var> is set, Resin will
store a persistent cookie on the client's machine after authentication
succeeds. On all subsequent access, Resin detects the persistent
cookie and automatically logs the user in instead of prompting for
authentication. This essentially lets you implement "remember me"
functionality common in many web-sites. By default, the authentication
only lasts for a single session and no persistent login cookie is sent
to the client.
</p>

<p>The following table outlines all the login parameters recognized by Resin:</p>
<deftable title="j_security_check Parameters">
<tr>
  <th>Parameter</th>
  <th>Meaning</th>
</tr>
<tr>
  <td>j_username</td>
  <td>The user name.</td>
</tr>
<tr>
  <td>j_password</td>
  <td>The password.</td>
</tr>
<tr>
  <td>j_uri</td>
  <td>Resin extension for the successful display page (optional).</td>
</tr>
<tr>
  <td>j_use_cookie_auth</td>
  <td>Resin extension to allow cookie login (optional).</td>
</tr>
</deftable>


</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>form-login-page</td>
  <td>The page to be used to prompt the user login.</td>
  <td>none</td>
</tr>
<tr>
  <td>form-error-page</td>
  <td>The error page for unsuccessful login.</td>
  <td>none</td>
</tr>
<tr>
  <td>internal-forward</td>
  <td>Use an internal redirect on success or a <code>sendRedirect</code>.</td>
  <td>false</td>
</tr>
<tr>
  <td>form-uri-priority</td>
  <td>If true, the login form's j_uri will override the originally requested URI.</td>
  <td>false</td>
</tr>
</attributes>

<example title="WEB-INF/resin-web.xml resin:FormLogin">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:FormLogin form-login-page="/login.html"
                      form-error-page="/login_failure.html"/>
  ...
&lt;/web-app>
</example>

<example title="j_security_check form">
&lt;form action='j_security_check' method='POST'&gt;
&lt;table&gt;
&lt;tr&gt;&lt;td&gt;User:&lt;td&gt;&lt;input name='j_username'&gt;
&lt;tr&gt;&lt;td&gt;Password:&lt;td&gt;&lt;input name='j_password'&gt;
&lt;tr&gt;&lt;td colspan=2&gt;hint: the password is 'quidditch'
&lt;tr&gt;&lt;td&gt;&lt;input type=submit&gt;
&lt;/table&gt;
&lt;/form&gt;
</example>
</defun>

<defun title="&lt;resin:Forward>" name="resin:Forward">
<javadoc class="com.caucho.rewrite.Forward"/>
<description>
<p>
  Forwards to the new URL using RequestDispatcher.forward with the <em>target</em> URL.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>regexp</td>
  <td>The regular expression of the URL to match.</td>
</tr>
<tr>
  <td>target</td>
  <td>The target URL to which to forward the request.</td>
</tr>
<tr>
  <td>absolute&#x2011;target</td>
  <td>The absolute target URL to which to forward the request. The absolute target is based on the host root, not relative to the webapp.</td>
</tr>
</attributes>


<example title="Forwarding requests across web-apps">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:Forward regexp='^/foo' target='/bar/'/>

&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:GlobalCache>" name="resin:GlobalCache">
<javadoc class="com.caucho.distcache.GlobalCache"/>
<description>
<p>

  JCache-style distributed object cache across the entire Resin system.
</p>
</description>
</defun>

<defun title="&lt;resin:HttpProxy>" name="resin:HttpProxy">
<javadoc class="com.caucho.rewrite.HttpProxy"/>
<description>
<p>
  Proxies the request to a backend server using HTTP as a proxy protocol.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default Value</th>
</tr>
<tr>
  <td>regexp</td>
  <td>The regular expression of the URL to match.</td>
  <td>none</td>
</tr>
<tr>
  <td>address</td>
  <td>address:port of an HTTP server</td>
  <td>none</td>
</tr>
<tr>
  <td>addresses</td>
  <td>address:port of HTTP servers (space separated)</td>
  <td>none</td>
</tr>
<tr>
  <td>backend</td>
  <td>a &lt;backend> with address and optional timeouts (see below)</td>
  <td>none</td>
</tr>
<tr>
  <td>strategy</td>
  <td>round-robin or adaptive</td>
  <td>adaptive</td>
</tr>
<tr>
  <td>connect-timeout</td>
  <td>the maximum time a proxy connection to a backend should take</td>
  <td>5s</td>
</tr>
<tr>
  <td>socket-timeout</td>
  <td>the maximum time a the proxy will wait for a read or write to a backend</td>
  <td>30s</td>
</tr>
<tr>
  <td>idle-time</td>
  <td>the maximum time the proxy will leave an idle socket before closing it (must be less than the keepalive value of the target backend)</td>
  <td>10s</td>
</tr>
<tr>
  <td>warmup-time</td>
  <td>time the proxy uses to throttle connections to a backend server that's just starting up</td>
  <td>60s</td>
</tr>
<tr>
  <td>recover-time</td>
  <td>the maximum time the proxy will consider the backend dead after a failure before retrying</td>
  <td>15s</td>
</tr>
</attributes>

<deftable title="&lt;backend> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default Value</th>
</tr>
<tr>
  <td>address</td>
  <td>address:port of an HTTP server</td>
  <td>none</td>
</tr>
<tr>
  <td>connect-timeout</td>
  <td>the maximum time a proxy connection to the backend should take</td>
  <td>5s</td>
</tr>
<tr>
  <td>socket-timeout</td>
  <td>the maximum time a the proxy will wait for a read or write to the backend</td>
  <td>30s</td>
</tr>
<tr>
  <td>idle-time</td>
  <td>the maximum time the proxy will leave an idle socket before closing it (must be less than the keepalive value of the target backend)</td>
  <td>10s</td>
</tr>
<tr>
  <td>warmup-time</td>
  <td>time the proxy uses to throttle connections to the backend server that's just starting up</td>
  <td>60s</td>
</tr>
<tr>
  <td>recover-time</td>
  <td>the maximum time the proxy will consider the backend dead after a failure before retrying</td>
  <td>15s</td>
</tr>
<tr>
  <td>weight</td>
  <td>assigns a load-balance weight to a backend server. Servers with higher values get more requests. Servers with lower values get fewer requests</td>
  <td>100</td>
</tr>
</deftable>

<example title="Proxying requests to local HTTP servers">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

   &lt;resin:HttpProxy regexp="\.cgi$">
     &lt;strategy>adaptive&lt;/strategy>
     &lt;backend address="127.0.0.1:12345" weight="100">
     &lt;backend address="127.0.0.1:65432" weight="200">
   &lt;/resin:HttpProxy>

&lt;/web-app>
</example>

</defun>

<defun title="&lt;resin:if>" name="resin:if" version="Resin 3.0.7">

<description>
<p>resin:if executes part of the configuration file conditionally.  resin:if
can be particularly useful in combination with Java command-line properties
like -Dfoo=bar to enable development mode or testing configuration.
</p>

<p>The resin:if schema is context-dependent.  For example, resin:if in
a &lt;web-app> will have web-app content while resin:if in a &lt;host>
will have host content.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>test</td>
  <td>the test to perform</td>
  <td>required</td>
</tr>
</attributes>

<schema>
element resin:if {
  attribute test { string }

  <var>context-dependent content</var>
}
</schema>

<example title="Example: enable debugging for -Ddevelopment">
&lt;resin xmlns="http://caucho.com/ns/resin"
        xmlns:core="http://caucho.com/ns/resin/core">

  &lt;resin:if test="${system['development']}"&gt;
    &lt;logger name="com.foo" level="finer"/>
  &lt;/resin:if&gt;

  ...
&lt;/resin>
</example>

</defun> <!-- resin:if -->

<defun title="&lt;resin:IfAuthType>" name="resin:IfAuthType">
<javadoc class="com.caucho.rewrite.IfAuthType"/>
<description>
<p>
  Checks for the authentication type, request.getAuthType().
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>none, basic, client_cert, digest, or form</td>
  <td>none</td>
</tr>
</attributes>

<example title="Redirecting based on authentication type">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp='^/user-area' target='/secret'>
    &lt;resin:IfAuthType value="BASIC"/>
  &lt;/resin:Redirect>

  &lt;resin:Redirect regexp='^/user-area' target='/login'/>

  &lt;resin:XmlAuthenticator password-digest='none'>
    &lt;user name="Aladdin" password="open sesame" group="user"/>
  &lt;/resin:XmlAuthenticator>

  &lt;resin:BasicLogin realm-name="foobar"/>

&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:IfCookie>" name="resin:IfCookie">
<javadoc class="com.caucho.rewrite.IfCookie"/>
<description>
<p>
  Checks for the presence of a named HTTP cookie from request.getCookies().
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>  
<tr>
  <td>name</td>
  <td>The name of the cookie to match.</td>
</tr>
<tr>
  <td>regexp</td>
  <td>A regular expression to match the value of the cookie.</td>
</tr>
<tr>
  <td>value</td>
  <td>A regular expression to match the value of the cookie. (synonym for regexp)</td>
</tr>
</attributes>

<example title="Redirecting if a cookie is set">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp='^/welcome' target='/user-area'>
    &lt;resin:IfCookie name="session"/>
  &lt;/resin:Redirect>

&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:IfCron>" name="resin:IfCron">
<javadoc class="com.caucho.rewrite.IfCron"/>
<description>
<p>
Matches if the current time is in an active range configured by cron-style times.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>  
<tr>
  <td>enable-at</td>
  <td>A <a config-tag="cron">cron expression</a> representing the start time(s) at which the predicate matches.</td>
</tr>
<tr>
  <td>disable-at</td>
  <td>A <a config-tag="cron">cron expression</a> representing the end time(s) after which the predicate does not match.</td>
</tr>
</attributes>

<example title="Redirecting based on time">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp='^/live-support' target='/hours'>
    &lt;resin:IfCron>
      &lt;resin:enable-at>0 17 * * *&lt;/resin:enable-at>
      &lt;resin:disable-at>0 8 * * *&lt;/resin:disable-at>
    &lt;/resin:IfCron>
  &lt;/resin:Redirect>

&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:IfFileExists>" name="resin:IfFileExists">
<javadoc class="com.caucho.rewrite.IfFileExists"/>
<description>
<p>
  Matches if the URL corresponds to an actual file. Has no attributes.
</p>
</description>

<example title="Dispatch only if the URL represents an existant file">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:Dispatch>
    &lt;resin:IfFileExists/>
  &lt;/resin:Dispatch>

  &lt;resin:Redirect regexp="^" target='/does-not-exist'/>
&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:IfHeader>" name="resin:IfHeader">
<javadoc class="com.caucho.rewrite.IfHeader"/>
<description>
<p>
  Tests for a HTTP header and value match.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>  
<tr>
  <td>name</td>
  <td>The name of the header to match.</td>
</tr>
<tr>
  <td>regexp</td>
  <td>A regular expression to match the value of the header.</td>
</tr>
<tr>
  <td>value</td>
  <td>A regular expression to match the value of the header. (synonym for regexp)</td>
</tr>
</attributes>

<example title="Redirect based on referrer">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp='^/foo' target='/foo-for-example-customers'>
    &lt;resin:IfHeader name="Referer" value="example.com"/>
  &lt;/resin:Redirect>

  &lt;resin:Redirect regexp='^/foo' target='/everyone-else'/>
&lt;/web-app>

</example>

</defun>

<defun title="&lt;resin:IfLocale>" name="resin:IfLocale">
<javadoc class="com.caucho.rewrite.IfLocale"/>
<description>
<p>
  Tests for a Locale match from the HTTP request (Accept-Language header).
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>  
<tr>
  <td>value</td>
  <td>A regular expression to match locale.</td>
</tr>
</attributes>

<example title="Redirecting based on locale">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp='^/your-lang' target='/francais'>
    &lt;resin:IfLocale value="fr"/>
  &lt;/resin:Redirect>

  &lt;resin:Redirect regexp='^/your-lang' target='/default'/>
&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:IfLocalPort>" name="resin:IfLocalPort">
<javadoc class="com.caucho.rewrite.IfLocalPort"/>
<description>
<p>
  Compares the local port of the request, request.getLocalPort().
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>  
<tr>
  <td>value</td>
  <td>The port to match.</td>
</tr>
</attributes>

<example title="Redirecting based on local port">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

    &lt;resin:Redirect regexp='^/foo' target='/match-5555'>
      &lt;resin:IfLocalPort value="5555"/>
    &lt;/resin:Redirect>

    &lt;resin:Redirect regexp='^/foo' target='/match-6666'>
      &lt;resin:IfLocalPort value="6666"/>
    &lt;/resin:Redirect>

    &lt;resin:Redirect regexp='^/foo' target='/no-match'/>

&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:IfMBeanEnabled>" name="resin:IfMBeanEnabled">
<javadoc class="com.caucho.rewrite.IfMBeanEnabled"/>
<description>
<p>
  Matches if a MBean is enabled().
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>  
<tr>
  <td>name</td>
  <td>The MBean name.</td>
  <td>required</td>
</tr>
<tr>
  <td>enabled</td>
  <td>Sets the default enable/disable value.</td>
  <td>true</td>
</tr>
</attributes>

<p>The mbean name will be something like:</p>

<example title="MBean name for maintenance">
  resin:type=IfMBeanEnabled,name=my-name,Host=www.example.com,WebApp=/
</example>  

<p>The following example redirects URLs to a maintenance page if an
mbean is enabled.</p>

<example title="Redirecting based on an MBean">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

    &lt;resin:Redirect regexp='^/foo' target='/scheduled-maintenance.jsp'>
      &lt;resin:IfMBeanEnabled name="maintenance" enabled="false"/>
    &lt;/resin:Redirect>

&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:IfMethod>" name="resin:IfMethod">
<javadoc class="com.caucho.rewrite.IfMethod"/>
<description>
<p>
  Compares the HTTP method, request.getMethod().
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>  
<tr>
  <td>value</td>
  <td>The HTTP method to match.</td>
</tr>
<tr>
  <td>method</td>
  <td>The HTTP method to match (synonym of value).</td>
</tr>
</attributes>

<example title="Redirecting based on HTTP method">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

    &lt;resin:Redirect regexp='^/foo' target='/foo/post'>
      &lt;resin:IfMethod value="POST"/>
    &lt;/resin:Redirect>

&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:IfNetwork>" name="resin:IfNetwork">
<javadoc class="com.caucho.rewrite.IfNetwork"/>
<parents>resin:Allow,resin:Deny</parents>

<description>
<p>The &lt;resin:IfNetwork> tag allows or denies requests based on the
IP address of the client. IP-constraint is very useful for protecting
administration resources to an internal network. It can also be useful
for denying service to known problem IPs.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>  
<tr>
  <td>value</td>
  <td>An IP address to match (multiple allowed).</td>
  <td>N/A</td>
</tr>
<tr>
  <td>cache-size</td>
  <td>The size of the IP address LRU cache used for performance.</td>
  <td>256</td>
</tr>
</attributes>

<examples>
<p>The <code>/24</code> in the IP <code>192.168.17.0/24</code>
means that the first 24 bits of the IP are matched - any IP address
that begins with <code>192.168.17.</code> will match. The usage of
<var>/bits</var> is optional.</p>

<example title="Admin Pages Allowed Only from 192.168.17.0/24">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:Allow url-pattern="/admin/*">
    &lt;resin:IfNetwork value="192.168.17.0/24"/>
  &lt;/resin:Allow>
  ...
&lt;/web-app>
</example>

<p>The following example shows
how the tag can be used to construct an IP block list:</p>

<example title="Block-out Known Trouble-Makers">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:Deny>
    &lt;resin:IfNetwork>
       &lt;resin:value>205.11.12.3&lt;/resin:value>
       &lt;resin:value>213.43.62.45&lt;/resin:value>
       &lt;resin:value>123.4.45.6&lt;/resin:value>
       &lt;resin:value>233.15.25.35&lt;/resin:value>
       &lt;resin:value>233.14.87.12&lt;/resin:value>
    &lt;/resin:IfNetwork>
  &lt;/resin:Deny>
  ...
&lt;/web-app&gt;
</example>
<p>Be careful with deny - some ISP's (like AOL) use proxies and the IP
of many different users may appear to be the same IP to your server.</p>

<p>If only <var>deny</var> is used, then all IPs are allowed if they
do not match a <code>deny</code>. If only <var>allow</var> is used,
then an IP is denied unless it matches an <code>allow</code>. If both
are used, then the IP must match both an <code>allow</code> and a
<code>deny</code></p>
</examples>

</defun>

<defun title="&lt;resin:IfQueryParam>" name="resin:IfQueryParam">
<javadoc class="com.caucho.rewrite.IfQueryParam"/>
<description>
<p>
  Tests for a HTTP query parameger, request.getParameter().
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>  
<tr>
  <td>name</td>
  <td>The name of the query parameter to match.</td>
</tr>
<tr>
  <td>regexp</td>
  <td>A regular expression to match the value of the query parameter.</td>
</tr>
<tr>
  <td>value</td>
  <td>A regular expression to match the value of the query parameter. (synonym for regexp)</td>
</tr>
</attributes>

<example title="Redirecting based on query parameter">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
    &lt;resin:Redirect regexp='^/foo' target='/login'>
      &lt;resin:IfQueryParam name="area" value="login"/>
    &lt;/resin:Redirect>

&lt;/web-app>
</example>

</defun>

<defun title="&lt;resin:IfRemoteUser>" name="resin:IfRemoteUser">
<javadoc class="com.caucho.rewrite.IfRemoteUser"/>
<description>
<p>Tests against the remote user, request.getRemoteUser().</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>  
<tr>
  <td>value</td>
  <td>The user to match.</td>
</tr>
</attributes>

<example title="Forbidding a path based on remote user">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Forbidden regexp="/harry">
    &lt;resin:Not>
      &lt;resin:IfRemoteUser value="harry"/>
    &lt;/resin:Not>
  &lt;/resin:Forbidden>

  &lt;resin:XmlAuthenticator>
    &lt;user>harry:H83FykjQaBwvqjGRyIRUHQ==:user&lt;/user>
  &lt;/resin:XmlAuthenticator>

  &lt;resin:BasicLogin realm-name='global'/>

&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:IfSecure>" name="resin:IfSecure">
<parents>resin:Allow,resin:Deny</parents>
<javadoc class="com.caucho.rewrite.IfSecure"/>
<description>
<p>The &lt;resin:IfSecure>
tag restricts access to secure transports, usually SSL.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>  
<tr>
  <td>value</td>
  <td>A boolean value against which HttpServletRequest.isSecure is matched.</td>
  <td>true</td>
</tr>
</attributes>

<examples>
<p>In the following example, all pages in the web application are
enforced to be accessible via SSL only.</p>

<example title="WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"
  ...	 
  &lt;resin:Allow>
    &lt;resin:IfSecure/>
  &lt;/resin:Allow>
  ...  
&lt;/web-app&gt;
</example>

<p>The default behaviour is for Resin to rewrite any URL that starts
with "http:" by replacing the "http:" part with "https:", and then
send a redirect to the browser because this configuration.</p> 

<p>If the default rewriting of the host is not appropriate, you
can set the <a config-tag="secure-host-name"/> for the host:</p>

<example title="WEB-INF/resin-web.xml">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="app-tier">
  ...  
  &lt;host id="..."&gt;
    &lt;secure-host-name&gt;https://hogwarts.com&lt;/secure-host-name&gt;
    ...
&lt;/resin> 
</example>
</examples>
</defun>

<defun title="&lt;resin:IfUserInRole>" name="resin:IfUserInRole">
<parents>resin:Allow,resin:Deny</parents>
<javadoc class="com.caucho.rewrite.IfUserInRole"/>

<description>
<p>The <a config-tag="resin:IfUserInRole"/> condition enforces
role-based security. It requires that authenticated users have a
specified role.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>  
<tr>
  <td>role</td>
  <td>Roles which are allowed to access the resource.</td>
</tr>
</attributes>

<p>The following is an example of how &lt;resin:IfUserInRole> might be used:</p>
<example title="WEB-INF/resin-web.xml Protecting WebDav for WebDav Users">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:Allow url-pattern="/webdav/*">
    &lt;resin:IfUserInRole role='webdav'/>
  &lt;/resin:Allow>
  ...  
&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:import>" name="resin:import" version="Resin 3.0.7">

<description>
<p>&lt;resin:import> reads configuration from another file or set of
files.  For example, the WEB-INF/web.xml and WEB-INF/resin-web.xml files
are implemented as &lt;resin:import> in the app-default.xml.</p>

<p>The target file is validated by the schema of the including context.
So a resin:import in &lt;web-app-default&gt; will have a target with a
top-level of &lt;web-app&gt;, and a resin:import in &lt;cluster> will have
a top-level tag of &lt;cluster>.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>path</td>
  <td>a path to a file</td>
  <td>either path or fileset is required</td>
</tr>
<tr>
  <td>fileset</td>
  <td>a <a config-tag="fileset">fileset</a> describing all
the files to import.</td>
  <td>either path or fileset is required</td>
</tr>
<tr>
  <td>optional</td>
  <td>if true, no error when file does not exist</td>
  <td>false</td>
</tr>
</attributes>

<schema>
element import {
  (path | fileset)
  &amp; optional?
}

element fileset {
  dir
  &amp; exclude*
  &amp; include*
}
</schema>

<examples>
<p>The following example shows how Resin implements the WEB-INF/web.xml
and WEB-INF/resin-web.xml files.  Both are simply resin:import in a
web-app-default.  When Resin configures the web-app, it will process
the web-app-default program, and call resin:import for the web.xml file.</p>

<example title="Example: import implementation of WEB-INF/web.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  &lt;cluster id="app-tier">

    &lt;web-app-default>
      &lt;resin:import path="WEB-INF/web.xml" optional="true"/>
      &lt;resin:import path="WEB-INF/resin-web.xml" optional="true"/>
    &lt;/web-app-default>

  &lt;/cluster>
&lt;/resin>
</example>

<p>Virtual hosts can use resin:import to add a custom host.xml file.
The host.xml can use any &lt;host> attribute, including &lt;host-name>
and &lt;host-alias> to customize the virtual host configuration.</p>

<example title="Example: adding host.xml in host-deploy">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  &lt;cluster id="app-tier">

    &lt;host-deploy path="/var/resin/hosts">
      &lt;host-default>
        &lt;resin:import path="host.xml" optional="true"/>

        &lt;web-app-deploy path="webapps"/>
      &lt;/host-default>
    &lt;/web-app-default>

  &lt;/cluster>
&lt;/resin>
</example>

<p>Some applications may want to split their configuration into multiple
files using the fileset.  For example, a <a href="admin/config-candi.xtp">Resin-IoC</a>
application might want to define beans in WEB-INF/beans/*.xml and give
the web-app flexibility in which bean files to create.</p>

<example title="Example: Bean IoC fileset in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
          xmlns:core="http://caucho.com/ns/resin/core">

  &lt;resin:import>
    &lt;fileset dir="WEB-INF/beans">
      &lt;include>*.xml&lt;/include>
    &lt;/fileset>
  &lt;/resin:import>

&lt;/web-app>
</example>
</examples>

</defun>

<defun title="&lt;resin:JaasAuthenticator>" name="resin:JaasAuthenticator">
<parents>cluster, host, web-app</parents>
<javadoc class="com.caucho.security.JaasAuthenticator"/>
<description>
<p>
The JaasAuthenticator uses a JAAS LoginModule for authentication. A common
use of the JaasAuthenticator is to serve as an adapter for the large
number of JAAS LoginModule's included in the Sun JDK for authentication
purposes. However, the JAAS authenticator can be used with any valid
JAAS login module.
</p>
<!-- XXX: Need an external reference to the JAAS modules in the JDK -->
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td><a config-tag="jaas-init-param">init-param</a></td>
  <td>Adds a property to the LoginModule.</td>
  <td>None</td>
</tr>
<tr>
  <td>login-module</td>
  <td>The fully qualified class name of the LoginModule implementation.</td>
  <td>Required</td>
</tr>
<tr>
  <td>logout-on-session-timeout</td>
  <td>If true, the user will be logged out when the session times out.</td>
  <td>true</td>
</tr>
<tr>
  <td>password-digest</td>
  <td>
    Specifies the digest algorithm and format used to secure the password (see following 
    section in this document for details).
  </td>
  <td>md5-base64</td>
</tr>
</attributes>

<example title="WEB-INF/resin-web.xml for JaasAuthenticator">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"&gt;
  ...
  &lt;resin:JaasAuthenticator&gt;
    &lt;resin:login-module&gt;com.sun.security.auth.module.Krb5LoginModule&lt;/resin:login-module&gt;
    &lt;resin:init-param&gt;
      &lt;debug&gt;true&lt;/debug&gt;
    &lt;/resin:init-param&gt;
  &lt;/resin:JaasAuthenticator&gt;
  ...
&lt;/web-app&gt;
</example>

</defun>

<defun title="&lt;resin:JmsConnectionFactory>" name="resin:JmsConnectionFactory">
<javadoc class="com.caucho.jms.JmsConnectionFactory"/>
<description>
<p>

  Combined Queue and Topic ConnectionFactory.
</p>
</description>
</defun>

<defun title="&lt;resin:JmxService>" name="resin:JmxService">
<javadoc class="com.caucho.admin.JmsService"/>
<description>
<p>
  Enables cluster-wide JMX administration.
</p>
</description>
</defun>

<defun title="&lt;resin:LdapAuthenticator>" name="resin:LdapAuthenticator">
<parents>cluster, host, web-app</parents>
<javadoc class="com.caucho.security.LdapAuthenticator"/>
<description>
<p> The LdapAuthenticator uses JNDI to connect to an LDAP (or Active
Directory) server for authentication.  </p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>dn-prefix</td>
  <td>String to prepend to query before portion selecting user by name.</td>
  <td>None</td>
</tr>
<tr>
  <td>dn-suffix</td>
  <td>String to append to query after portion selecting user by name.</td>
  <td>None</td>
</tr>
<tr>
  <td><a config-tag="jndi-env">jndi-env</a></td>
  <td>Add a property to the JNDI provider used for connecting to the LDAP server.</td>
  <td>See below</td></tr>
<tr>
  <td>logout-on-session-timeout</td>
  <td>If true, the user will be logged out when the session times out.</td>
  <td>true</td>
</tr>
<tr>
  <td>security-authentication</td>
  <td>Sets the Context.SECURITY_AUTHENTICATION for the LDAP environment.</td>
  <td></td>
</tr>
<tr>
  <td>security-principal</td>
  <td>Sets the Context.SECURITY_PRINCIPAL for the LDAP environment.</td>
  <td></td>
</tr>
<tr>
  <td>security-credentials</td>
  <td>Sets the Context.SECURITY_CREDENTIALS for the LDAP environment.</td>
  <td></td>
</tr>
<tr>
  <td>password-digest</td>
  <td>
    Specifies the digest algorithm and format used to secure the password (see following 
    section in this document for details).
  </td>
  <td>md5-base64</td>
</tr>
<tr>
  <td>user-attribute</td>
  <td>The attribute name to use in the query for matching the user.</td>
  <td>uid</td>
</tr>
<tr>
  <td>password-attribute</td>
  <td>The attribute name to use for obtaining the password.</td>
  <td>userPassword</td>
</tr>
<tr>
  <td>url</td>
  <td>The URL for the server.</td>
  <td>ldap://localhost:389</td>
</tr>
</attributes>

<example title="WEB-INF/resin-web.xml for LdapAuthenticator">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"&gt;
  ...
  &lt;resin:LdapAuthenticator password-digest="none">
    &lt;resin:url&gt;ldap://localhost:389&lt;/resin:url&gt;
    &lt;resin:dn-suffix&gt;dc=hogwarts,dc=com&lt;/resin:dn-suffix&gt;
  &lt;/resin:LdapAuthenticator>
  ...
&lt;/web-app>
</example>

<s2 title="jndi-env">
<p>
<code>jndi-env</code> configures properties of the LDAP provider implementation. Prior 
to 3.1.1, the URL of the server is specified with <code>jndi-env</code> and the
<code>java.naming.provider.url</code> property.
</p>
<p>
The following example shows the usage of the <code>jndi-env</code> configuration property:
</p>
<example title="WEB-INF/resin-web.xml LdapAuthenticator jndi-env">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:LdapAuthenticator password-digest="none">
    &lt;resin:jndi-env java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"/&gt;
    &lt;resin:jndi-env java.naming.provider.url="ldap://localhost:389"/&gt;
    &lt;resin:dn-suffix&gt;dc=hogwarts,dc=com&lt;/dn-suffix&gt;
  &lt;/resin:LdapAuthenticator&gt;
  ...
&lt;web-app>
</example>
</s2>
</defun>

<defun title="&lt;resin:LoadBalance>" name="resin:LoadBalance">
<javadoc class="com.caucho.rewrite.LoadBalance"/>
<pro/>

<description>
<p>
  Load balance to a cluster of backend Resin servers.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>regexp</td>
  <td>The regular expression of the URL to match.</td>
  <td>None (match all)</td>
</tr>
<tr>
  <td>cluster</td>
  <td>The id of the cluster to which to load balance.</td>
  <td>required</td>
</tr>
<tr>
  <td>session-cookie</td>
  <td>change the session cookie to examine for sticky sessions</td>
  <td>JSESSIONID</td>
</tr>
<tr>
  <td>sticky-sessions</td>
  <td>sessions are sticky to the original backend app server</td>
  <td>true</td>
</tr>
<tr>
  <td>strategy</td>
  <td>round-robin or adaptive based on load</td>
  <td>adaptive</td>
</tr>
</attributes>

<example title="Load Balancing to a backend cluster">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">
   
  &lt;cluster id='app-tier'>
    &lt;server id='a' port='6810'/>
    &lt;server id='b' port='6820'/>

    ...
  &lt;/cluster>

  &lt;cluster id='web-tier'>
    &lt;server id='http' port='80'/>

    &lt;host id=''>
    
      &lt;resin:LoadBalance cluster="app-tier"/>
      
    &lt;/host>
  &lt;/cluster>
&lt;/resin>
</example>
</defun>

<defun title="&lt;resin:LogService>" name="resin:LogService">
<javadoc class="com.caucho.admin.LogService"/>
<description>
<p>
  Stores high-priority log messages in a database.
</p>
</description>
</defun>

<defun title="&lt;resin:MemoryQueue>" name="resin:MemoryQueue">
<javadoc class="com.caucho.jms.MemoryQueue"/>
<description>
<p>
  Memory based queue.
</p>
</description>
</defun>

<defun title="&lt;resin:MemorySingleSignon>" name="resin:MemorySingleSignon">
<javadoc class="com.caucho.security.MemorySingleSignon"/>
<description>
<p>
  Memory-based single signon.
</p>
</description>
</defun>


<defun title="&lt;resin:MemoryTopic>" name="resin:MemoryTopic">
<javadoc class="com.caucho.jms.MemoryTopic"/>
<description>
<p>
  Memory based topic.
</p>
</description>
</defun>

<defun title="&lt;resin:message>" name="resin:message" version="Resin 3.0.7">

<description>
<p>Logs a message to the given log file. The content of the element is the
message.</p>
</description>

<schema>
element resin:message {
  string
}
</schema>

<example title="logging in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">

  &lt;resin:message&gt;Starting server ${server.name}&lt;/resin:message&gt;

&lt;/web-app>
</example>

</defun> <!-- resin:message -->

<defun title="&lt;resin:MovedPermanently>" name="resin:MovedPermanently">
<javadoc class="com.caucho.rewrite.MovedPermanently"/>

<description>
<p>
  Send an HTTP redirect to a new URL specified by <em>target</em>.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>regexp</td>
  <td>The regular expression of the URL to match.</td>
</tr>
<tr>
  <td>target</td>
  <td>The target to which to redirect the request.</td>
</tr>
</attributes>

<example title="Flipping elements of a path with a MovedPermanently">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:MovedPermanently regexp='^/([^/]+)/([^/]+)' target='/$2/$1'/>
  
&lt;/web-app>
</example>
</defun> <!-- movedPermanently -->

<defun title="&lt;resin:Not>" name="resin:Not">
<javadoc class="com.caucho.rewrite.Not"/>
<description>
<p>
Matches if the child does not match.
</p>
</description>

<example title="Negative matching of a query parameter">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp="" target="/match">
    &lt;resin:Not>
      &lt;resin:IfQueryParam name="foo" regexp="bar"/>
    &lt;/resin:Not>
  &lt;/resin:Redirect>
  
&lt;/web-app>
</example>

</defun>
<defun title="&lt;resin:NotAnd>" name="resin:NotAnd">
<javadoc class="com.caucho.rewrite.NotAnd"/>
<description>
<p>
  Matches if any child does not match.
</p>
</description>

<example title="Negative matching of at least one of two query parameters">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp="" target="/match">
    &lt;resin:NotAnd>
      &lt;resin:IfQueryParam name="foo" regexp="foo"/>
      &lt;resin:IfQueryParam name="bar" regexp="bar"/>
    &lt;/resin:NotAnd>
  &lt;/resin:Redirect>
  
&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:NotOr>" name="resin:NotOr">
<javadoc class="com.caucho.rewrite.NotOr"/>
<description>
<p>
  Matches if all the children do not match.
</p>
</description>

<example title="Negative matching of two query parameters">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp="" target="/match">
    &lt;resin:NotOr>
      &lt;resin:IfQueryParam name="foo" regexp="foo"/>
      &lt;resin:IfQueryParam name="bar" regexp="bar"/>
    &lt;/resin:NotOr>
  &lt;/resin:Redirect>
  
&lt;/web-app>
</example>


</defun>

<defun title="&lt;resin:Or>" name="resin:Or">
<javadoc class="com.caucho.rewrite.Or"/>
<description>
<p>
  Matches if any children match.
</p>
</description>

<example title="Matching at least one of two query parameters">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  &lt;resin:Redirect regexp="" target="/match">
    &lt;resin:Or>
      &lt;resin:IfQueryParam name="foo" regexp="foo"/>
      &lt;resin:IfQueryParam name="foo" regexp="bar"/>
    &lt;/resin:Or>
  &lt;/resin:Redirect>
  
&lt;/web-app>
</example>

</defun>

<defun title="&lt;resin:otherwise>" name="resin:otherwise" version="Resin 3.0.7">
<parents>resin:choose</parents>
<p>&lt;resin:otherwise> is the catch-all configuration for a &lt;resin:choose>
block when none of the &lt;resin:when> items match.</p>

<schema>
element resin:otherwise {
  <var>context-dependent content</var>
}
</schema>

</defun>

  
<defun title="&lt;resin:PingMailer>" name="resin:PingMailer">
<javadoc class="com.caucho.admin.PingMailer"/>
<description>
<p>
  Mails a notification when a ping check fails.
</p>
</description>
</defun>

<defun title="&lt;resin:PingThread>" name="resin:PingThread">
<javadoc class="com.caucho.admin.PingThread"/>
<description>
<p>
  Checks status of Resin sutomatically.
</p>
</description>
</defun>

<defun title="&lt;resin:ProjectJarRepository>" name="resin:ProjectJarRepository">
<javadoc class="com.caucho.repository.ProjectJarRepository"/>
<description>
<p>
  Maven-style library jar management for webapps.
</p>
</description>
</defun>

<defun title="&lt;resin:PropertiesAuthenticator>" name="resin:PropertiesAuthenticator">
<parents>cluster, host, web-app</parents>
<javadoc class="com.caucho.security.PropertiesAuthenticator"/>

<description>
<p>
The PropertiesAuthenticator allows you to use Java properties to
store authentication information. This is very useful for a variety
of applications such as very small sites, developement, unit testing
or integration testing. You can either specify properties in-line
in XML or via an external properties file.
</p>
</description>

<!-- XXX: Check this attributes table for completeness -->
<attributes>
<tr>
  <th>Attribute</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>path</td>
  <td>Path to the properties file.</td>
  <td>None</td>
</tr>
<tr>
  <td>password-digest</td>
  <td>
    Specifies the digest algorithm and format used to secure the password (see following 
    section in this document for details).
  </td>
  <td>md5-base64</td>
</tr>
</attributes>

<p>
  The following is an example of in-lining properties with the
  authenticator. This is useful for extremely simple web-sites
  maintained by developers as well as testing.
</p>
<example title="WEB-INF/resin-web.xml - in-line Properties">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:PropertiesAuthenticator password-digest="none">
     harry=quidditch,user,admin
     draco=mudblood,disabled,user
  &lt;/resin:PropertiesAuthenticator>
  ...
&lt;/web-app>
</example>

<p>
  Alternatively, external properties files can be used as in
  the example below. This is useful for a simple site where
  authentication may be managed by administrators or non-technical
  users.
</p>
<example title="WEB-INF/resin-web.xml - File Property">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"
  ...
  &lt;resin:PropertiesAuthenticator path="WEB-INF/users.properties"/>
  ...
&lt;/web-app>
</example>
<example title="WEB-INF/users.properties">
harry=/Tj/54ylCloUeMi2YQIVCQ===,user,admin
</example>
<p>
As the example indicates, the properties file includes the user as
property name while the value is the password (that may be hashed
as in the example or may be in plain-text) and any roles that are
assigned to the user separated by commas. The password and role
values are also separated by a comma.
</p>
</defun>

<defun title="&lt;resin:Redirect>" name="resin:Redirect">
<javadoc class="com.caucho.rewrite.Redirect"/>

<description>
<p>
  Send an HTTP redirect to a new URL specified by <em>target</em>.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>regexp</td>
  <td>The regular expression of the URL to match.</td>
</tr>
<tr>
  <td>target</td>
  <td>The target to which to redirect the request.</td>
</tr>
</attributes>

<example title="Flipping elements of a path with a Redirect">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:Redirect regexp='^/([^/]+)/([^/]+)' target='/$2/$1'/>
  
&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:RemoteAdminService>" name="resin:RemoteAdminService">
<javadoc class="com.caucho.admin.RemoteAdminService"/>

<description>
<p>
  Enables administration by remote agents, like an eclipse console.
</p>
</description>
</defun>

<defun title="&lt;resin:ScheduledTask>" name="resin:ScheduledTask">
<javadoc class="com.caucho.resources.ScheduledTask"/>

<description>
<p>&lt;resin:ScheduledTask> schedules a job to be executed at specific
times or after specific delays.  The times can be specified by a <a
config-tag="cron">cron syntax</a> or by a simple delay parameter.
The job can be either a <code>Runnable</code> bean, a method specified
by an EL expression, or a URL.</p>

<p>When specified as an Java Injection bean, the bean task has full
IoC capabilities, including injection, @TransactionAttribute aspects,
interception and @Observes.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>cron</td>
  <td>a cron-style scheduling description</td>
</tr>
<tr>
  <td>delay</td>
  <td>a simple delay-based execution</td>
</tr>
<tr>
  <td>init</td>
  <td>IoC initialization for the bean</td>
</tr>
<tr>
  <td>mbean-name</td>
  <td>optional MBean name for JMX registration</td>
</tr>
<tr>
  <td>method</td>
  <td>EL expression for a method to be invoked as the task</td>
</tr>
<tr>
  <td>name</td>
  <td>optional IoC name for registering the task</td>
</tr>
<tr>
  <td>period</td>
  <td>how often the task should be invoked in simple mode</td>
</tr>
<tr>
  <td>task</td>
  <td>alternate task assignment for predefined beans</td>
</tr>
</attributes>

<examples>
<example title="A runnable task">
&lt;resin:ScheduledTask>
  &lt;cron>* * * * *&lt;/cron>
  &lt;task>
    &lt;example:MyClass xmlns:qa="urn:java:com.example"/>
  &lt;/task>
&lt;/resin:ScheduledTask>
</example>

<example title="Weekly maintenance script">
&lt;resin:ScheduledTask url="/saturday-maintenance.jsp">
  &lt;cron>* * * * 6&lt;/cron>
&lt;/resin:ScheduledTask>
</example>

</examples>

</defun>

<defun title="&lt;resin:SendError>" name="resin:SendError">
<javadoc class="com.caucho.rewrite.SendError"/>
<description>
<p>
  Send a HTTP error response.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>regexp</td>
  <td>The regular expression of the URL to match.</td>
</tr>
<tr>
  <td>code</td>
  <td>The HTTP status to send.</td>
</tr>
<tr>
  <td>message</td>
  <td>A descriptive message to send to the client.</td>
</tr>
</attributes>

<example title="Sending an error code based on request path">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

	&lt;resin:SendError regexp="/upcoming" code="501" message="Not Implemented"/>

&lt;/web-app>
</example>
</defun>

<defun title="&lt;resin:set>" name="resin:set" version="Resin 3.0.7">

<description>
<p>resin:set adds an EL variable to the current context.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>var</td>
  <td>name of the variable to set</td>
  <td>required</td>
</tr>
<tr>
  <td>value</td>
  <td>value</td>
  <td>required</td>
</tr>
</attributes>

<schema>
element set {
  var
  &amp; value
  &amp; default
  &amp; attribute * { string }
}
</schema>

<example title="Example: resin:set in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"
          xmlns:resin="http://caucho.com/ns/resin/core">
  &lt;resin:set var="root" value="/var/resin"/>

  &lt;cluster id="app-tier">
    &lt;root-directory>${root}&lt;/root-directory>

    ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;resin:SetHeader>" name="resin:SetHeader">
<javadoc class="com.caucho.rewrite.SetHeader"/>
<description>
<p>Sets a response header.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>name</td>
  <td>The name of header to set.</td>
</tr>
<tr>
  <td>value</td>
  <td>The value to which the header will be set.</td>
</tr>
<tr>
  <td>regexp</td>
  <td>regular expression matching URLs.</td>
</tr>
</attributes>

<example title="Example: Setting a custom header based on network">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:SetHeader regexp="\.jsp$" name="X-External" value="true">
    &lt;resin:Not>
      &lt;resin:IfNetwork>
        &lt;resin:value>192.168.1.0/24&lt;/resin:value>
      &lt;/resin:IfNetwork>
    &lt;/resin:Not>
  &lt;/resin:SetHeader>

&lt;/web-app>
</example>
</defun>


<defun title="&lt;resin:SetRequestCharacterEncoding>" name="resin:SetRequestCharacterEncoding">
<javadoc class="com.caucho.rewrite.SetRequestCharacterEncoding"/>
<description>
<p>Sets the character encoding of the request parameters.</p>
</description>

<example>
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"&gt;

  &lt;resin:SetRequestCharacterEncoding value="ISO-8859-15"/&gt;

&lt;/web-app&gt;
</example>

</defun>


<defun title="&lt;resin:SetRequestSecure>" name="resin:SetRequestSecure">
<javadoc class="com.caucho.rewrite.SetRequestSecure"/>
<description>
<p>Marks the request as secure.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>regexp</td>
  <td>regular expression matching URLs.</td>
</tr>
</attributes>

<p>If the regular expression is omitted, all URLs will require
secure connections.</p>

<example title="Setting a request as secure based on network">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:SetRequestSecure>
    &lt;resin:IfNetwork>
      &lt;resin:value>192.168.1.0/24&lt;/resin:value>
    &lt;/resin:IfNetwork>
  &lt;/resin:SetRequestSecure>

&lt;/web-app>
</example>

</defun>

<defun title="&lt;resin:SetVary>" name="resin:SetVary">
<javadoc class="com.caucho.rewrite.SetVary"/>
<description>
<p>Sets the Vary header.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>value</td>
  <td>The value to which the Vary header will be set.</td>
</tr>
<tr>
  <td>regexp</td>
  <td>regular expression matching URLs.</td>
</tr>
</attributes>


<example title="Example: Setting the Vary header for JSPs">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  &lt;resin:SetVary regexp="\.jsp" value="Accept"/>

&lt;/web-app>
</example>
</defun>

<!--
<defun title="&lt;resin:StatService>" name="resin:StatService">
<javadoc class="com.caucho.rewrite.StatService"/>
<pro/>

<description>
<p>
  Gathers timed runtime status of Resin for graphing.
</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>enabled</td>
  <td>enable or disable stat collection</td>
  <td>true</td>
</tr>
<tr>
  <td>sample-period</td>
  <td>how often to sample the statistics</td>
  <td>60s</td>
</tr>
</attributes>

</defun>
-->

<defun title="&lt;resin:when>" name="resin:when" version="Resin 3.0.7">
<parents>resin:choose</parents>

<description>
<p>&lt;resin:when> conditionally configures a block within a
&lt;resin:choose> block.  If the <var>test</var> matches, Resin will
use the enclosed configuration.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>test</td>
  <td>the test to perform</td>
</tr>
</attributes>

<schema>
element resin:when {
  attribute test { string },

  <var>context-dependent content</var>
}
</schema>

</defun>

<defun title="&lt;resin:XaLogService>" name="resin:XaLogService">
<javadoc class="com.caucho.admin.XaLogService"/>
<pro/>

<description>
<p>
  Transaction log service.
</p>
</description>
</defun>

<defun title="&lt;resin:XmlAuthenticator>" name="resin:XmlAuthenticator">
<parents>cluster, host, web-app</parents>
<javadoc class="com.caucho.security.XmlAuthenticator"/>

<description>
<p>
In a similar vein to the properties authenticator, the XML
authenticator allows you to store authentication information in XML -
either in-line or in an external file. This authenticator has some of
the same use-cases as the properties file authenticator, in a slight
more human readable form, especially for a non-technical user.  </p>
</description>

<deftable>
<tr>
  <th>Attribute</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>user</td>
  <td>Specifies a user authentication record. There maybe zero, one or more records.</td>
  <td>None</td>
</tr>
<tr>
  <td>password-digest</td>
  <td>
    Specifies the digest algorithm and format used to secure the password (see following 
    section in this document for details).
  </td>
  <td>md5-base64</td>
</tr>
<tr>
  <td>path</td>
  <td>Specifies the path to an XML file containing users and passwords.</td>
  <td>None</td>
</tr>
<tr>
  <td>logout-on-session-timeout</td>
  <td>If true, the user will be logged out when the session times out.</td>
  <td>true</td>
</tr>
</deftable>
<p>The following example uses in-line XML for authentication. When configuring the 
XmlAuthenticator in resin.xml (or resin-web.xml), each <var>user</var> adds a new 
configured user. The user value contains the username, password, and the roles for the 
user.</p>
<example title="XmlAuthenticator in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  &lt;resin:XmlAuthenticator password-digest="none">
    &lt;resin:user name="Harry Potter" password="quidditch" group="user,gryffindor"/>
    &lt;resin:user name="Draco Malfoy" password="pureblood" group="user,slytherin"/>
  &lt;/resin:XmlAuthenticator>
  ...
&lt;/web-app>  
</example>
<p>This example shows how to use an external XML file for authentication:</p>
<example title="WEB-INF/resin-web.xml - File XML">
&lt;web-app xmlns="http://caucho.com/ns/resin">
  ...
  &lt;resin:XmlAuthenticator path="WEB-INF/users.xml"/>
  ...
&lt;/web-app>
</example>
<example title="WEB-INF/users.xml">
&lt;users>
  &lt;user name="harry password="/Tj/54ylCloUeMi2YQIVCQ===" roles="user,admin"/>
&lt;users>
</example>
</defun>

<defun title="&lt;resin:XmlRoleMap>" name="resin:XmlRoleMap">
<javadoc class="com.caucho.security.XmlRoleMap"/>
<description>
<p>
  Role to group permission mapping.
</p>
</description>
</defun>

<defun title="RequestPredicate" name="RequestPredicate">
<javadoc class="com.caucho.rewrite.RequestPredicate"/>

<description>
<p>
  Interface for custom request predicates.
</p>
</description>
</defun>

<defun title="&lt;resource>" name="resource" occur="*" version="Resin 3.0">
<parents>resin, cluster, host, web-app</parents>
  <!-- com.caucho.config.types.Resource -->

<description>
<p>&lt;resource> is an obsolete synonym for &lt;bean> to define custom
singletons.  Applications should use the &lt;bean> syntax instead.</p>
</description>

</defun> 

<defun title="&lt;resource-ref>" name="resource-ref" occur="*" version="Servlet 2.2">
<parents>resin, cluster, host, web-app</parents>
  <!-- com.caucho.config.types.ResourceRef -->

<description>
<p>&lt;resource-ref> declares that the application needs
a resouce configuration.</p>

<p>resource-ref is not directly used by Resin.  It's a servlet configuration
item intended to tell GUI tools which resources need configuration.
Resource configuration in Resin uses the resource, reference,
database, and ejb-server tags.</p>

<p>For backwards compatibility, Resin 2.1-style configuration files
may still use resource-ref to configure resources, but it's recommended to
convert the configuration.</p>
</description>

<schema>
element resource-ref {
  attribute id?,
  description*,
  res-ref-name,
  ref-type,
  res-auth,
  res-sharing-scope?
}
</schema>
</defun>

<defun title="&lt;save-mode>">
<parents>session-config</parents>
<p>&lt;save-mode> configures when Resin should save a persistence
session during a request.  The values are:</p>
<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>

<tr>
  <td>after-request</td>
  <td>Save the session after the request has been served and completed</td>
</tr>
<tr>
  <td>before-headers</td>
  <td>Save the session before sending headers to the browser</td>
</tr>
<tr>
  <td>on-shutdown</td>
  <td>Only save the session when Resin is shutting down</td>
</tr>
</attributes>
<p>In some situations, like redirects, a fast browser can send a request
back to Resin before the session is persisted with the
<var>after-request</var> save-mode.  If the server is configured
without <g>sticky sessions</g>, the load balancer might send the request
to a different server, which may not get the updated session.
In the situation, either the save-mode should be changed to
<var>before-headers</var> or sticky sessions should be enabled.</p>
<p>If the save-mode is <var>before-headers</var>, the application should
take care to make any session changes before sending data to the browser.</p>
<default>after-request</default>
</defun>

<defun title="&lt;save-allocation-stack-trace>" name="save-allocation-stack-trace" version="Resin 3.1">
<parents>database</parents>

<description>
<p>&lt;save-allocation-stack-trace> helps debugging application with
a missing <code>Connection.close()</code> by saving the stack trace
where the <code>Connection.getConnection()</code> was called.  When
Resin detects that the connection has failed to close, it can then
print the allocation stack trace, which is more informative for
tracking down errors.</p>
</description>

</defun>

<defun title="&lt;scheduled-task>" name="scheduled-task">
<parents>web-app</parents>

<description>
<p>The &lt;scheduled-task> is replaced by bean-style <a href="#resin:ScheduledTask">resin:ScheduleTask</a>.</p>
</description>

<example title="ScheduledTask in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:ee="urn:java:ee"
         xmlns:mypkg="urn:java:com.mycom.mypkg">

  &lt;resin:ScheduleTask>
    &lt;cron>* * 23 * *&lt;/cron>
    
    &lt;task>
      &lt;mypkg:MyBean/>
    &lt;/task>
  &lt;/resin:ScheduleTask>
  
&lt;/web-app>
</example>
</defun>

<defun title="&lt;secure>" name="secure">
<parents>web-app</parents>

<description>
<p>The &lt;secure> flag requires that the web-app only be accessed
in a secure/SSL mode.  Equivalent to a &lt;security-constraint>.</p>
</description>

<schema>
element secure {
  r_boolean-Type
}
</schema>

</defun>

<defun title="&lt;secure-host-name>" name="secure-host-name">

<description>
<p>&lt;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 &lt;secure-host-name> configures
the host to redirect to.</p>

<p>See <a href="admin/security.xtp">Resin security</a>.</p>
</description>

<schema>
element secure-host-name {
  string
}
</schema>

</defun>

<defun title="&lt;security-constraint>" name="security-constraint" version="Servlet">
<parents>web-app</parents>

<description>
<p>Specifies protected areas of the web site.  Sites using
authentication as an optional personalization feature will typically
not use any security constraints.  See <a href="admin/security-overview.xtp">Resin
security</a> for an overview.</p>

<p>Security constraints can also be custom classes.</p>

<p>See <a href="admin/security-overview.xtp">Resin security</a> for an overview of
security issues and configuration.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>auth-constraint</td>
  <td>Defines a security condition based on a logged-in user's role</td>
</tr>
<tr>
  <td>constraint</td>
  <td>Defines a custom security condition</td>
</tr>
<tr>
  <td>ip-constraint</td>
  <td>Defines a security condition based the remote IP address</td>
</tr>
<tr>
  <td>role-name</td>
  <td>Defines role-name requirement</td>
</tr>
<tr>
  <td>url-pattern</td>
  <td>URL pattern to match the security constraint</td>
</tr>
<tr>
  <td>user-data-constraint</td>
  <td>Defines SSL or non-SSL requirements</td>
</tr>
<tr>
  <td>web-resource-collection</td>
  <td>URL patterns and HTTP methods defining the constraint</td>
</tr>
</attributes>

<schema>
element security-constraint {
  auth-constraint*
  &amp; constraint*
  &amp; ip-constraint*
  &amp; role-name*
  &amp; user-data-constraint*
  &amp; url-pattern?
  &amp; web-resource-collection*
}
</schema>

<example title="Example: 'user' role required in WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

&lt;security-constraint&gt;
  &lt;web-resource-collection&gt;
    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
  &lt;/web-resource-collection&gt;
  &lt;auth-constraint role-name='user'&gt;
&lt;/security-constraint&gt;

&lt;/web-app>
</example>
</defun>


<defun title="&lt;security-manager>" name="security-manager">
<description>
<p>
&lt;security-manager> enables the use of the security manager for the JVM.
Because the JVM security manager is very slow, we generally do not
recommend enabling it for server applications.  Instead, see the
<a href="admin/starting-resin-watchdog.xtp">watchdog</a> configuration for alternative
methods for securiting the JVM in ISP configurations.
</p>
</description>

<schema>
element security-manager {
  r_boolean-Type
}
</schema>

<example title="Example: enabling security-manager">
&lt;resin xmlns="http://caucho.com/ns/resin">

  ...
  &lt;security-manager/&gt;
  ...
</example>

</defun>

<defun title="&lt;security-provider>" name="security-provider">
<description>
<p>
&lt;security-provider> adds one or more security providers.  Each entry
specifies the name of a security provider class.  The name is used
to instantiate an instance of the
object, which is then passed to 
<a javadoc="java.security.Security#addProvider()">Security.addProvider</a>.
</p>
</description>

<schema>
element security-provider {
  string
}
</schema>

<example title="Example: adding custom security providers">
&lt;resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core"&gt;

  ...

  &lt;security-provider&gt;
    com.sun.net.ssl.internal.ssl.Provider
  &lt;/security-provider&gt;
  &lt;security-provider&gt;
    example.MyProvider
  &lt;/security-provider&gt;

  ...

</example>

</defun> <!-- security-provider -->

<defun title="&lt;server>" version="Resin 3.1" name="server">
<parents>cluster</parents>
<p>&lt;server> configures a JVM instance in the cluster.
Each &lt;server&gt; is uniquely identified by
its <var>id</var> attribute.  The <var>id</var> will match
the -server command line argument.</p>
<p>The server listens to an internal network address,
e.g. 192.168.0.10:6800 for clustering, load balancing,
and administration.</p>
<p>The current server is managed with a
<a href="javadoc|com.caucho.management.server.ServerMXBean">ServerMXBean</a>.
The <g>ObjectName</g> is <var>resin:type=Server</var>.</p>
<p>Peer servers are managed with 
<a href="javadoc|com.caucho.management.server.ServerConnectorMXBean">ServerConnectorMXBean</a>. 
The ObjectName is <var>resin:type=ServerConnector,name=server-id</var>.</p>
<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>

<tr><td>id</td>
    <td>unique server identifier</td>
    <td>required</td></tr>
<tr><td>address</td>
    <td>IP address of the cluster port</td>
    <td>127.0.0.1</td></tr>
<tr><td>port</td>
    <td>The cluster port</td>
    <td>6800</td></tr>
<tr><td>allow-non-reserved-ip</td>
    <td>allows non-private IP address be used for cluster port</td>
    <td>false</td></tr>
</attributes>
<example title="server">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="web-tier"&gt;
        &lt;server id="a" address="192.168.0.10" port="6800"&gt;
          &lt;http port="8080"/&gt;
        &lt;/server&gt;

        &lt;server id="b" address="192.168.0.11" server-port="6800"&gt;
          &lt;http port="8080"/&gt;
        &lt;/server&gt;

        &lt;server id="c" address="192.168.0.12" server-port="6800"&gt;
          &lt;http port="8080"/&gt;
        &lt;/server&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>
<p>Main configuration for the server, configuring ports,
threads and virtual hosts.</p>
<ul>
<li>Common resources for all virtual hosts and web-apps.</li>
<li>Thread pooling</li>
<li>HTTP and Server/Cluster ports</li>
<li>Caching</li>
<li>virtual host configuration and common web-app-default</li>
</ul>
<p>The &lt;server&gt; will generally contain a &lt;class-loader&gt; configuration
which loads the resin/lib jars dynamically, allowing for system-wide jars
to be dropped into resin/lib.  &lt;server&gt; configures
the main dynamic environment.  Database pools common to all virtual hosts,
for example, should be configured in the &lt;server&gt; block.</p>
<p>The &lt;server&gt; configures the &lt;thread-pool&gt; and a set
of &lt;http&gt; and &lt;server&gt; ports which share the thread pool.
Requests received on those ports will use worker threads from the
thread pool.</p>
<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr><td>alternate-session-url-prefix</td>
    <td>a prefix to add the session to the beginning of the URL as a path
        prefix instead of the standard ;jsessionid= suffix. For clients like
        mobile devices with limited memory, this will allow careful web
        designers to minimize the page size.</td>
    <td>null</td></tr>
<tr><td>keepalive-max</td>
    <td>the maximum number of keepalive connections</td>
    <td>512</td></tr>
<tr><td>keepalive-timeout</td>
    <td>the maximum time a connection is maintained in the keepalive state</td>
    <td>15s</td></tr>
</attributes>
<example title="alternate-session-url-prefix">
&lt;server&gt;
  ...
  &lt;alternate-session-url-prefix&gt;/~J=&lt;/alternate-session-url-prefix&gt;
  ...
</example>
<s2 name="server-el" title="EL variables and functions">
<deftable title="EL variables defined by &lt;server&gt;">
<tr><th>variable</th>
    <th>corresponding API</th></tr>
<tr><td>serverId</td>
    <td><i>server</i>.getServerId()</td></tr>
<tr><td>root-dir</td>
    <td><i>server</i>.getRootDirectory()</td></tr>
<tr><td>server-root</td><td><i>server</i>.getRootDirectory()</td></tr>
</deftable>
<deftable title="EL functions defined by &lt;server&gt;">
<tr><th>function</th>
    <th>corresponding API</th></tr>
<tr><td>jndi</td>
    <td><a href="javadoc|com.caucho.naming.Jndi|lookup(String)">Jndi.lookup(String)</a></td></tr>
</deftable>
</s2>
</defun>

<defun title="&lt;server-default>" version="Resin 3.1" name="server-default">
<parents>cluster</parents>
<description>
<p>&lt;server-default> defines default values for
all &lt;server&gt; instances.  Since most &lt;server> configuration
is identical for all server instances, the shared configuration belongs
in a &lt;server-default>.  For example, &lt;http> ports, timeouts,
JVM arguments, and keepalives are typically identical for all
server instances and therefore belong in a server-default.</p>
</description>
<example title="server">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="web-tier"&gt;
        &lt;server-default&gt;
           &lt;thread-max>512&lt;/thread-max>

           &lt;jvm-arg>-Xmx512m -Xss1m&lt;/jvm-arg>

           &lt;http port="8080"/&gt;
        &lt;/server-default&gt;

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;
        &lt;server id="c" address="192.168.0.12" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>
</defun>

<defun title="&lt;server-multi>" version="Resin 4.0" name="server-multi">
<parents>cluster</parents>
<description>
<p>&lt;server-multi> allows to specify multiple servers in a single tag. The
servers are named using id–prefix concatenated with position of server's ip in the
address-list.

</p></description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>id-prefix</td>
  <td>Prefix used to construct server name dynamically</td>
</tr>
<tr>
  <td>address-list</td>
  <td>List of addresses the corresponding servers will bind to</td>
</tr>
<tr>
 <td>require-explicit-id</td>
 <td>Requires passing -server &lt;id> to the CLI</td>
</tr>
<tr>
 <td>port</td>
 <td>cluster port</td>
</tr>
</attributes>

<example title="server-multi">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app"&gt;
    &lt;server-multi id-prefix="app-" address-list="192.168.1.2 192.168.1.3" port="6800"/>
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

<p>In the example above server app-0 is bound to ip ending with 1.2, app-1 – 1.3</p>

</defun>

<defun title="&lt;server-header>" version="Resin 3.1" name="server-header">
<parents>cluster</parents>
<default>Resin/4.0.x</default>

<description>
<p>Configures the HTTP Server: header which Resin sends back to any
HTTP client.</p>
</description>

<schema>
element server-header {
  string
}
</schema>

<example title="server-header">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="web-tier"&gt;
        &lt;server-header&gt;MyServer/1.0&lt;/server-header&gt;
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;servlet>" name="servlet" version="Servlet 2.2">
<description>
<p>Defines a servlet to process HTTP URL
requests.  The servlet class can either implement 
<a javadoc="javax.servlet.Servlet"/>
to handle the HTTP request directly or it can use a remoting protocol
like Hessian to handle remoting requests.</p>

<p>Since servlets are full <a href="admin/config-candi.xtp">Resin-CanDI</a> beans,
they can use dependency injection, EJB aspects like @TransactionAttribute,
custom @InterceptorType interceptors, and listen for @Observes events.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>init</td>
  <td><a href="admin/config-candi.xtp">Resin-IoC</a> initialization</td>
</tr>
<tr>
  <td>init-param</td>
  <td>Initialization parameters</td>
</tr>
<tr>
 <td>load-on-startup</td>
 <td>Initializes the servlet when the server starts.</td>
</tr>
<tr>
 <td>protocol</td>
 <td>Protocol configuration for Resin remoting.</td>
</tr>
<tr>
  <td>run-at</td>
  <td>Times to execute the servlet automatically.</td>
</tr>
<tr>
  <td>servlet-name</td>
  <td>The servlet's name (alias)</td>
</tr>
<tr>
  <td>servlet-class</td>
  <td>The servlet's class (In Resin, defaults to servlet-name)</td>
</tr>
</attributes>

<schema>
element servlet {
  servlet-name
  &lt; (servlet-class | jsp-file)
  &lt; init*
  &lt; init-param*
  &lt; load-on-startup?
  &lt; protocol?
  &lt; run-as?
  &lt; run-at?
}
</schema>

<example title="Example: WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns">

  &lt;servlet&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;servlet-class&gt;test.HelloWorld&lt;/servlet-class&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;title&lt;/param-name&gt;
      &lt;param-value&gt;Hello, World&lt;/param-value&gt;
    &lt;/init-param&gt;
  &lt;/servlet&gt;

  &lt;!-- using Resin shortcut syntax --&gt;
  &lt;servlet servlet-name='cron'
           servlet-class='test.DailyChores'&gt;
    &lt;init-param title='Daily Chores'/&gt;
    &lt;load-on-startup/&gt;
    &lt;run-at&gt;3:00&lt;/run-at&gt;
  &lt;/servlet&gt;

  &lt;!-- mapping a url to use the servlet --&gt;
  &lt;servlet-mapping url-pattern='/hello.html'
                   servlet-name='hello'/&gt;

&lt;/web-app&gt;
</example>


<p>Several <var>servlet</var> configurations might configure the same
servlet class with different <var>init-param</var> values.  Each will
have a separate <var>servlet-name</var>.</p>
      
<example title="Example: multiple servlets using the same class">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;servlet servlet-name='foo-a'&gt;
    &lt;servlet-class&gt;test.FooServlet&lt;/servlet-class&gt;
    &lt;init-param name='foo-a sample'/&gt;
  &lt;/servlet&gt;

  &lt;servlet servlet-name='foo-b'&gt;
    &lt;servlet-class&gt;test.FooServlet&lt;/servlet-class&gt;
    &lt;init-param name='foo-b sample'/&gt;
  &lt;/servlet&gt;
&lt;/web-app&gt;
</example>

<p><var>load-on-startup</var> can specify an (optional) integer
value.  If the value is 0 or greater, it indicates an order for
servlets to be loaded, servlets with higher numbers get loaded
after servlets with lower numbers.</p>
      
<p>There are a number of named servlets that are usually
available to a Resin application, as defined in
<var>$RESIN_HOME/conf/app-default.xml</var>.</p>

<example title="Example: servlet-mappings in $RESIN_HOME/conf/app-default.xml">
  &lt;servlet servlet-name="directory"
           servlet-class="com.caucho.servlets.DirectoryServlet"/&gt;

  &lt;servlet servlet-name="file"
           servlet-class="com.caucho.servlets.FileServlet"/&gt;

  &lt;servlet servlet-name="jsp"
           servlet-class="com.caucho.jsp.JspServlet"/&gt;

  &lt;servlet servlet-name="xtp"
           servlet-class="com.caucho.jsp.XtpServlet"/&gt;

&lt;servlet servlet-name="j_security_check"
         servlet-class="com.caucho.server.security.FormLoginServlet"/&gt;
</example>
</defun>


<defun title="&lt;servlet-hack>" name="servlet-hack" occur="*" version="Resin 3.0">
  <parents>class-loader</parents>

<description>
<p>Use of servlet-hack is discouraged.  Using servlet-hack violates
the JDK's classloader delegation model and can
produce surprising ClassCastExceptions.</p>

<p>servlet-hack reverses the normal class loader order.
Instead of parent classloaders having priority, child classloaders
have priority.</p>
</description>

<schema>
element servlet-hack {
  boolean
}
</schema>

</defun>

<defun title="&lt;servlet-mapping>" name="servlet-mapping" version="Servlet 2.2">
<description>
<p>Maps url patterns to servlets.  <var>servlet-mapping</var> has two
children, <var>url-pattern</var> and <var>servlet-name</var>.
<var>url-pattern</var> selects the urls which should execute the servlet.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>init</td>
  <td><a href="admin/config-candi.xtp">Resin-IoC</a> configuration of the servlet.</td>
</tr>
<tr>
  <td>protocol</td>
  <td>Defines the optional remoting protocol.</td>
</tr>
<tr>
  <td>servlet-class</td>
  <td>The servlet-mapping can define the servlet directly as a shortcut.</td>
</tr>
<tr>
  <td>servlet-name</td>
  <td>The servlet name</td>
</tr>
<tr>
  <td>url-pattern</td>
  <td>A pattern matching the url: <var>/foo/*</var>, <var>/foo</var>, or <var>*.foo</var></td>
</tr>
<tr>
  <td><a config-tag="url-regexp"/></td>
  <td>A regular expression matching the portion of the url that follows the <g>context path</g></td>
</tr>
</attributes>

<schema>
element servlet-mapping {
  init?
  &amp; protocol?
  &amp; servlet-class?
  &amp; servlet-name?
  &lt; url-pattern*
  &lt; url-regexp*
}
</schema>

<example title="Example: WEB-INF/resin-web.xml &lt;servlet-mapping>">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;servlet&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;servlet-class&gt;test.HelloWorld&lt;/servlet-class&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;url-pattern&gt;/hello.html&lt;/url-pattern&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
  &lt;/servlet-mapping&gt;

  &lt;!-- resin shortcut syntax --&gt;
  &lt;servlet-mapping url-pattern='*.xtp'
                   servlet-name='com.caucho.jsp.XtpServlet'/&gt;

&lt;/web-app&gt;
</example>

<p>In Resin, the special <code>servlet-name</code>
<var>'invoker'</var> is used to dispatch servlets by class name.
</p>

<warn>Enabling the <var>invoker</var> servlet can
create a security hole in your application.  Any servlet in the
classpath, perhaps even one in a .jar that you are unaware of,
could be invoked.</warn>

<example title="Example: WEB-INF/resin-web.xml servlet invoker">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;!-- 
    used with urls like 
    http://localhost:8080/servlets/test.HelloServlet 
  --&gt;
  &lt;servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/&gt;

&lt;/web-app&gt;
</example>

<p>There are a number of mappings to servlets that are usually
available to a Resin application, as defined in
<var>$RESIN_HOME/conf/app-default.xml</var>.</p>

<example title="Example: servlet-mappings in $RESIN_HOME/conf/app-default.xml">
&lt;cluster>

&lt;web-app-default>
  &lt;servlet-mapping url-pattern="*.jsp" servlet-name="jsp"/&gt;
  &lt;servlet-mapping url-pattern="*.xtp" servlet-name="xtp"/&gt;

  &lt;servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/&gt;
  &lt;servlet-mapping url-pattern="/" servlet-name="file"/&gt;
&lt;/web-app-default>
&lt;/cluster>
</example>

<p>The plugins use servlet-mapping to decide which URLs to send to Resin.
The following servlet-name values are used by the plugins:</p>

<deftable title="servlet-name values used by plugins">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>plugin_match</td>
  <td>The plugin will send the request to Resin, but
Resin will ignore the entry.  Use to get around regexp limitations. (Resin 1.2.2)
</td>
</tr>
<tr>
  <td>plugin_ignore</td>
  <td>The plugin will ignore the request.  Use this
to define a sub-url the web server should handle, not Resin. (Resin 1.2.2)
</td>
</tr>
</deftable>
</defun>

<defun title="&lt;servlet-regexp>" name="servlet-regexp" version="Resin 3.0" type="defun">
<p>Maps URL by regular expressions to custom servlets.</p>

<schema>
element servlet-regexp {
  init?
  &amp; servlet-class?
  &amp; servlet-name?
  &amp; url-regexp
}
</schema>

<example>
&lt;servlet-regexp url-regexp="/([^.]*).do"
                servlet-class="qa.\${regexp[1]}Servlet"&gt;
  &lt;init a="b"/&gt;
&lt;/servlet-regexp&gt;
</example>

</defun>

<defun title="ServletRequestPredicate" name="ServletRequestPredicate">
<description>
<p>
Although extremely rare, it is sometimes useful to create
a custom predicate (for example for encapsulating complex
custom authorization logic). You can easily do this by extending <a
javadoc="com.caucho.rewrite.RequestPredicate">com.caucho.rewrite.RequestPredicate</a>.
This essentially allows you to create your own &lt;IfXXX> rule.
</p>
</description>

<p>The following example demonstrates how to create a custom Resin predicate:</p>
<example title="WEB-INF/resin-web.xml - Custom rule">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:foo="urn:java:com.foo"
 ...
 &lt;resin:Allow url-pattern="/safe/*"
    &lt;foo:IfMyTest value="abcxyz"/>
 &lt;/resin:Allow url-pattern="/safe/*"
 ...
&lt;/web-app&gt;
</example>
<example>
package com.foo;

import javax.servlet.http.HttpServletRequest;
import com.caucho.security.ServletRequestPredicate;

public class IfMyTest extends ServletRequestPredicate {
  private String value;

  // Your custom attribute for the tag.
  public void setValue(String value)
  {
    this.value = value;
  }

  // Here you must actually determine the match.
  public boolean isMatch(HttpServletRequest request)
  {
    return value.equals(request.getHeader("Foo"));
  }
}
</example>
</defun>
<defun title="&lt;session-cookie>" version="Resin 3.1" name="session-cookie">
<parents>cluster</parents>
<default>JSESSIONID</default>

<description>
<p>Configures the cookie used for servlet sessions.</p>
</description>

<schema>
element session-cookie {
  string
}
</schema>

</defun>
<defun title="&lt;session-config>" name="session-config" version="Servlet 2.2">

<description>
<p>&lt;session-config> configures Resin's session handling, including the
cookies Resin sends, the maximum sessions, and session persistence and clustering.</p>

<p>See also: <a href="admin/clustering-overview.xtp">Resin clustering</a> for more
information about distributed sessions and persistence.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>always-load-session</td>
  <td>Reload data from the store on every request</td>
  <td>false</td>
</tr>
<tr>
  <td>always-save-session</td>
  <td>Save session data to the store on every request</td>
  <td>false</td>
</tr>
<tr>
  <td>enable-cookies</td>
  <td>Enable cookies for sessions</td>
  <td>true</td>
</tr>
<tr>
  <td>enable-url-rewriting</td>
  <td>Enable URL rewriting for sessions</td>
  <td>true</td>
</tr>
<tr>
  <td>cookie-version</td>
  <td>Version of the cookie spec for sessions</td>
  <td>1.0</td>
</tr>
<tr>
  <td>cookie-domain</td>
  <td>Domain for session cookies</td>
  <td>none</td>
</tr>
<tr>
  <td>cookie-domain-regexp</td>
  <td>Regex for cookies-domain for multi-domain webapps</td>
  <td>none</td>
</tr>
<tr> 
  <td>cookie-max-age</td>
  <td>Max age for persistent session cookies</td>
  <td>none</td>
</tr>
<tr>
  <td>cookie-length</td>
  <td>Maximum length of the cookie</td>
  <td></td>
</tr>
<tr>
  <td>ignore-serialization-errors</td>
  <td>When persisting a session, ignore any values which don't implement java.io.Serializable</td>
  <td>true</td>
</tr>
<tr>
  <td>invalidate-after-listener</td>
  <td>If true, invalidate the sessions after the session listeners have
been called</td>
  <td></td>
</tr>
<tr>
  <td>reuse-session-id</td>
  <td>Reuse the session id even if the session has timed out. A value of false defeats single signon capabilities. (resin 2.0.4)</td>
  <td>true</td>
</tr>
<tr>
  <td>session-max</td>
  <td>Maximum active sessions</td>
  <td>8192</td>
</tr>
<tr>
  <td>session-timeout</td>
  <td>The session timeout in minutes, 0 means never timeout.</td>
  <td>30 minutes</td>
</tr>
<tr>
  <td>serialization-type</td>
  <td>Use one of "java" or "hessian" for serialization, hessian is significantly faster and smaller (resin 3.1.2)</td>
  <td>java</td>
</tr>
<tr>
  <td>serialize-collection-type</td>
  <td>For hessian serialization, ignore the collection type when serializing lists (disable for some Hibernate lists)</td>
  <td>true</td>
</tr>
<tr>
  <td>save-mode</td>
  <td>When to save sessions, one of "before-headers", "after-request", or "on-shutdown"</td>
  <td>after-request</td>
</tr>
<tr>
  <td>use-persistent-store</td>
  <td>Uses the current <a href="deploy-ref.xtp#session-config">persistent-store</a> to save sessions. (resin 3.0.8)</td>
  <td>none</td>
</tr>
</attributes>

<schema>
element session-config {
  always-load-session?
  &amp; always-save-session?
  &amp; cookie-append-server-index?
  &amp; cookie-domain?
  &amp; cookie-domain-regexp?
  &amp; cookie-length?
  &amp; cookie-max-age?
  &amp; cookie-port?
  &amp; cookie-secure?
  &amp; cookie-version?
  &amp; enable-cookies?
  &amp; enable-url-rewriting?
  &amp; ignore-serialization-errors?
  &amp; invalidate-after-listener?
  &amp; reuse-session-id?
  &amp; save-mode?
  &amp; save-on-shutdown?
  &amp; serialization-type?
  &amp; session-max?
  &amp; session-timeout?
  &amp; use-persistent-store?
}
</schema>

<p>The <var>session-timeout</var> and <var>session-max</var> are usually
used together to control the number of
sessions.  Sessions are stored in an LRU cache. When the number
of sessions in the cache fills up past <var>session-max</var>, the
oldest sessions are recovered.  In addition, sessions idle for
longer than <code>session-timeout</code> are purged.</p>

<example title="using session-config and session-timeout to control the number of sessions">
&lt;web-app id='/dir'&gt;

  &lt;session-config&gt;
     &lt;!-- 2 hour timeout --&gt;
     &lt;session-timeout&gt;120&lt;/session-timeout&gt;
     &lt;session-max&gt;4096&lt;/session-max&gt;
  &lt;/session-config&gt;

&lt;/web-app&gt;
</example>

<p><var>cookie-length</var> is used to limit the maximum length for
the session's generated cookie for special situations like WAP devices.
Reducing this value reduces the randomness in the cookie and increases the
chance of session collisions.</p>

<p><var>reuse-session-id</var> defaults to true so that Resin can share the session
id amongst different web-apps.</p>

<p>The class that corresponds to &lt;session-config&gt; is <a javadoc="com.caucho.server.session.SessionManager"/></p>

</defun>


<!--
<defun title="&lt;session-sticky-disable>" version="Resin 3.1" name="session-sticky-disable">
<parents>cluster</parents>
<default>false</default>

<description>
<p>Disables sticky sessions from the load balancer.</p>
</description>

<schema>
element session-sticky-disable {
  r_boolean-Type
}
</schema>

</defun>
-->
<defun title="&lt;session-url-prefix>" version="Resin 3.1" name="session-url-prefix">
<parents>cluster</parents>
<default>;jsessionid=</default>

<description>
<p>Configures the URL prefix used for session rewriting.</p>

<note>Session rewriting is discouraged as a potential security issue.</note>
</description>

<schema>
element session-cookie {
  string
}
</schema>

</defun>

<defun title="&lt;shutdown-wait-max>" version="Resin 3.0" name="shutdown-wait-max">
<parents>server</parents>

<description>
<p>&lt;shutdown-wait-max> configures the maximum time the server
will wait for the graceful shutdown before forcing an exit.</p>
</description>

<default>60s</default>

<schema>
element shutdown-wait-max {
  r_period-Type
}
</schema>


</defun>

<defun title="&lt;simple-loader>" name="simple-loader" occur="*" version="Resin 3.0">
  <parents>class-loader</parents>
  <!-- com.caucho.loader.SimpleLoader -->

<description>
<p>&lt;simple-loader> Configures a
simple <var>WEB-INF/classes</var>-style class loader.</p>

<p>.class files in the specified directory will be loaded without any
special compilation steps (in contrast with compiling-loader.)</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>path</td>
  <td>Filesystem path for the class loader.  Since Resin 3.0</td>
  <td>required</td>
</tr>
<tr>
  <td>prefix</td>
  <td>Class package prefix to only load to a subset of classes. Resin 3.0</td>
  <td>none</td>
</tr>
</attributes>

<schema>
element simple-loader {
  path
  &amp; prefix?
}
</schema>

</defun>

<defun title="&lt;socket-timeout>" name="socket-timeout" version="Resin 3.1">
<parents>http, cluster-port, protocol, server</parents>
<default>60s</default>

<description>
<p>&lt;socket-timeout> is the maximum time
a socket <a href="admin/clustering-overview.xtp">load balancer</a>
and <a href="deploy-ref.xtp#session-config">distributed sessions</a> will wait for
a read or write to a cluster socket.</p>

<p>Crashed servers may never respond to a read request or accept a write.
The socket-timeout lets Resin recover from these kinds of crashes.</p>

<p>Lower values can detect crashes more quickly, but too-low values may
report bogus failures when the server machine is just a little slow.</p>
</description>

<example title="socket-timeout">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;
        &lt;server-default>
          &lt;socket-timeout>60s&lt;/socket-timeout>
        &lt;/server-default>

        &lt;server id="a" address="192.168.0.10" port="6800"/&gt;
        &lt;server id="b" address="192.168.0.11" port="6800"/&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>
</defun>

<defun title="&lt;spy>" name="spy" version="Resin 3.1">
<parents>database</parents>
<default>false</default>

<description>
<p>The &lt;spy> tag is a very useful logging tag for debugging database
problems.  If &lt;spy> is enabled, all database queries will be logged
at the "fine" level.  Applications can use &lt;spy> to debug unexpected
database queries, or to improve query performance.</p>
</description>

<example title="Example: spy output">
0.6:setString(1,1)
0.6:executeQuery(select o.DATA from my_bean o where o.ID=?)

</example>

</defun>


<defun title="&lt;ssl-session-cookie>" version="Resin 3.1" name="ssl-session-cookie">
<parents>cluster</parents>
<default>value of session-cookie</default>

<description>
<p>Defines an alternative session cookie to be used for a SSL
connection.  Having two separate cookies increases security.</p>
</description>

<schema>
element ssl-session-cookie {
  string
}
</schema>

<example title="Example: ssl-session-cookie">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="web-tier"&gt;
        &lt;ssl-session-cookie&gt;SSLJSESSIONID&lt;/ssl-session-cookie&gt;
        ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;startup-mode>" name="startup-mode">
<parents>host, web-app, web-app-deploy</parents>

<description>
<p>&lt;startup-mode> configures the virtual-host's behavior on Resin startup,
either "automatic", "lazy" or "manual".</p>
</description>

<attributes>
<tr>
  <th>Mode</th>
  <th>Description</th>
</tr>
<tr>
  <td>automatic</td>
  <td>automatically start when Resin starts</td>
</tr>
<tr>
  <td>lazy</td>
  <td>start only when the first request is received</td>
</tr>
<tr>
  <td>manual</td>
  <td>start only when JMX administration requests a start</td>
</tr>
</attributes>

<schema>
element startup-mode {
  string
}
</schema>

</defun>

<defun title="&lt;stat-service>" name="stat-service">

<description>
<p>&lt;stat-service> periodically checks the status of the server,
and reports errors as necessary.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>unix-load-avg-exit-threshold</td>
  <td>CPU load triggering a Resin exit (and restart)</td>
  <td>100.0</td>
</tr>
<tr>
  <td>cpu-load-log-info-threshold</td>
  <td>CPU load triggering a log message at the info level</td>
  <td>1.0</td>
</tr>
<tr>
  <td>cpu-load-log-warning-threshold</td>
  <td>CPU load triggering a log message at the warning level</td>
  <td>5.0</td>
</tr>
<tr>
  <td>cpu-load-log-thread-dump-threshold</td>
  <td>CPU load triggering thread dump to the log</td>
  <td>5.0</td>
</tr>
<tr>
  <td>sample-period</td>
  <td>how often to sample the statistics</td>
  <td>60s</td>
</tr>
<tr>
  <td>thread-dump-interval</td>
  <td>minimum time between thread dumps</td>
  <td>15m</td>
</tr>
</attributes>

<schema>
element stat-service {
  unix-load-avg-exit-threshold?
  &amp; cpu-load-log-info-threshold?
  &amp; cpu-load-log-warning-threshold?
  &amp; cpu-load-thread-dump-threshold?
  &amp; sample-period?
  &amp; thread-dump-interval?
}
</schema>

</defun>

<defun title="&lt;statistics-enable>" name="statistics-enable">
<default>false</default>

<description>
<p>&lt;statistics-enable> enables more detailed statistics for the
<code>WebAppMXBean</code> administration.  The statistics gathering
is disabled by default for performance reasons.</p>
</description>

<schema>
element statistics-enable {
  r_boolean-Type
}
</schema>

</defun>

<defun title="&lt;stderr-log>" name="stderr-log" occur="?">
<parents>resin, cluster, host-default, host, web-app-default, web-app</parents>

<description>
<p>Configures the destination for <code>System.err</code>.</p>
</description>

<p>The <a href="admin/logging.xtp">log configuration</a> describes
stderr-log in detail.</p>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-format</td>
  <td>defines a format string for log rollover</td>
  <td></td>
</tr>
<tr>
  <td>path</td>
  <td>sets the VFS path for the log file</td>
  <td></td>
</tr>
<tr>
  <td>path-format</td>
  <td>sets a pattern for creating the VFS path for the messages</td>
  <td></td>
</tr>
<tr>
  <td>rollover-count</td>
  <td>sets the maximum number of rollover files</td>
  <td></td>
</tr>
<tr>
  <td>rollover-period</td>
  <td>sets the number of days before a log file rollover </td>
  <td>1m</td>
</tr>
<tr>
  <td>rollover-size</td>
  <td>sets the maximum log size before a rollover</td>
  <td>1g</td>
</tr>
<tr>
  <td>timestamp</td>
  <td>sets the formatting string for the timestamp label</td>
  <td></td>
</tr>
</attributes>

<schema>
element stderr-log {
  (path | path-format)
  &amp; archive-format?
  &amp; rollover-period?
  &amp; rollover-size?
  &amp; rollover-count?
  &amp; timestamp?
}
</schema>

</defun>

<defun title="&lt;stdout-log>" name="stdout-log" occur="?">
<parents>resin, cluster, host-default, host, web-app-default, web-app</parents>

<description>
<p>Configures the destination for <code>System.out</code>.</p>

<p>The <a href="admin/logging.xtp">log configuration</a> describes
stderr-log in detail.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-format</td>
  <td>defines a format string for log rollover</td>
  <td></td>
</tr>
<tr>
  <td>path</td>
  <td>sets the VFS path for the log file</td>
  <td></td>
</tr>
<tr>
  <td>path-format</td>
  <td>sets a pattern for creating the VFS path for the messages</td>
  <td></td>
</tr>
<tr>
  <td>rollover-count</td>
  <td>sets the maximum number of rollover files</td>
  <td></td>
</tr>
<tr>
  <td>rollover-period</td>
  <td>sets the number of days before a log file rollover </td>
  <td>1m</td>
</tr>
<tr>
  <td>rollover-size</td>
  <td>sets the maximum log size before a rollover</td>
  <td>1g</td>
</tr>
<tr>
  <td>timestamp</td>
  <td>sets the formatting string for the timestamp label</td>
  <td></td>
</tr>
</attributes>

<schema>
element stdout-log {
  (path | path-format)
  &amp; archive-format?
  &amp; rollover-period?
  &amp; rollover-size?
  &amp; rollover-count?
  &amp; timestamp?
}
</schema>

</defun>

<defun title="&lt;strict-mapping>" name="strict-mapping" version="Resin 1.2" type="defun">
<default>false, allowing /foo/bar.jsp/foo.</default>

<description>
<p>Forces servlet-mapping to follow strict Servlet 2.2, disallowing
PATH_INFO. Value is <var>true</var> or <var>false</var>.</p>
</description>

<schema>
element strict-mapping {
  r_boolean-Type
}
</schema>

<example title="Example: enabling strict-mapping in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;strict-mapping&gt;true&lt;/strict-mapping&gt;
&lt;/web-app&gt;
</example>

</defun>

<defun title="&lt;system-property>" name="system-property" occur="*" version="Resin 2.0">
<parents>resin, cluster, host, web-app</parents>

<description>
<p>Sets a Java system property.  The effect is the same as if you
had called <a javadoc="java.lang.System#setProperty(String,String)"/> before starting Resin.</p>
</description>

<schema>
element system-property {
  attribute * { string }+
}
</schema>

<example title="Example: setting system property">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;system-property foo="bar"/&gt;
&lt;/resin&gt;
</example>
</defun>

<defun title="Time intervals" name="time intervals">
<description>
  <p>Time intervals are used throughout Resin configuration. To specify the
    units for a given interval, use the appropriate suffix as shown below.</p>

<deftable>
<tr>
  <th>Suffix</th>
  <th>Meaning</th>
</tr>
<tr>
  <td>s</td>
  <td>seconds</td>
</tr>
<tr>
  <td>m</td>
  <td>minutes</td>
</tr>
<tr>
  <td>h</td>
  <td>hours</td>
</tr>
<tr>
  <td>D</td>
  <td>days</td>
</tr>
</deftable>

</description>
</defun>

<defun title="&lt;temp-dir>" name="temp-dir" occur="?" version="Resin 1.1">
<parents>resin, cluster, host-default, host, web-app-default, web-app</parents>
<default>Defaults to <var>WEB-INF/tmp</var></default>

<description>
<p>&lt;temp-dir> configures the application temp directory.
This is the path used in
<var>javax.servlet.context.tempdir</var>.</p>
</description>

<schema>
element temp-dir {
  string
}
</schema>

</defun>

<defun title="&lt;thread-idle-max>" name="thread-idle-max" version="Resin 3.1">
<parents>server</parents>
<default>10</default>

<description>
<p>&lt;thread-idle-max> configures the maximum number of idle
threads in the thread pool.  &lt;thread-idle-max> works
with &lt;thread-idle-min> to maintain a steady number of idle
threads, avoiding the creation or destruction threads when possible.</p>

<p>&lt;thread-idle-max> should be set high enough beyond
&lt;thread-idle-min> so a spiky load will avoid
creating a thread and then  immediately destroying it.</p>
</description>

<example title="thread-idle-max in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;thread-max>512&lt;/thread-max>

      &lt;thread-idle-min>10&lt;/thread-idle-min>
      &lt;thread-idle-max>20&lt;/thread-idle-max>

      &lt;jvm-arg>-Xss1m -Xmx1024m&lt;/jvm-arg>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;thread-idle-min>" name="thread-idle-min" version="Resin 3.1">
<parents>server</parents>
<default>5</default>

<description>
<p>&lt;thread-idle-min> configures the minimum number of idle
threads in the thread pool.  &lt;thread-idle-min> helps spiky loads,
avoiding delays for thread requests by keeping threads ready for future
requests.  When the number of idle threads drops
below &lt;thread-idle-min>, Resin creates a new thread.</p>

<p>&lt;thread-idle-min> should be set high enough to deal with load
spikes.  Since idle threads are relatively inexpensive in modern operating
systems, having a number of idle threads is not a major resource hog,
especially since these threads are idle, waiting for a new job.</p>

<p>&lt;thread-idle-min> works together with &lt;thread-idle-max> to
avoid thread allocation thrashing, i.e. avoiding creating a new thread
because of &lt;thread-idle-min> and then quickly destroying it
because of &lt;thread-idle-max>.</p>
</description>

<example title="thread-idle-min in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;thread-max>512&lt;/thread-max>

      &lt;thread-idle-min>10&lt;/thread-idle-min>
      &lt;thread-idle-max>20&lt;/thread-idle-max>

      &lt;jvm-arg>-Xss1m -Xmx1024m&lt;/jvm-arg>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;thread-max>" name="thread-max" version="Resin 3.1">
<parents>server</parents>
<default>8192</default>

<description>
<p>&lt;thread-max> configures the maximum number of threads
managed by Resin's thread pool.  Resin's thread pool is used
for connection threads, timers, and Resin worker threads for JMS, JCA
and EJB.  Since Resin's thread pool only manages Resin threads,
the actual number of threads in the JVM will be higher.</p>

<p>Modern operating systems can handle a fairly large number of threads,
so values of 512 or 1024 are often reasonable values for thread-max.  The
main limitation for thread-max is virtual memory.  Since each thread
takes up stack space (configured with -Xss), a 32-bit system
might have a thread limit based on virtual memory.</p>

<p>For example, on Linux the user space is only 2G.  If the heap memory
is 1024m (-Xmx1024m) and the stack size is 1m (-Xss1m), the maximum
number of threads is somewhat less than 1024.</p>

<p>In general, JVMs do not handle running out of threads very well, either
freezing or throwing out of memory errors.  Although it may be necessary
to limit the number of threads to avoid running out of memory,
&lt;thread-max> should generally be set to a high value.</p>
</description>

<example title="thread-max in resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="web-tier"&gt;
    &lt;server-default&gt;
      &lt;thread-max>512&lt;/thread-max>

      &lt;jvm-arg>-Xss1m -Xmx1024m&lt;/jvm-arg>
    &lt;/server-default&gt;

    &lt;server id="web-a" address="192.168.0.10"/>
        ...
  &lt;/cluster>
&lt;/resin>
</example>
</defun>

<defun title="&lt;transaction-timeout>" name="transaction-timeout" version="Resin 3.1">
<parents>database</parents>
<default>-1</default>

<description>
<p>&lt;transaction-timeout> configures the maximum time a transaction
can be alive before a mandatory rollback.</p>
</description>
</defun>

<defun title="&lt;tree-loader>" name="tree-loader" occur="*" version="Resin 3.0">
<parents>class-loader</parents>
<!-- com.caucho.loader.TreeLoader -->

<description>
<p>&lt;tree-loader> configures a jar library, <var>WEB-INF/lib</var>-style class loader similar to
<a config-tag="library-loader"/>, but will also find <code>.jar</code> and
<code>.zip</code> files in subdirectories.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>path</td>
  <td>Filesystem path for the class loader.  Since Resin 3.0</td>
  <td>required</td>
</tr>
</attributes>

<schema>
element tree-loader {
  path
}
</schema>

</defun>

<defun title="&lt;url-character-encoding>" version="Resin 3.1" name="url-character-encoding">
<parents>cluster</parents>
<default>UTF-8</default>

<description>
<p>Defines the character encoding for decoding URLs.</p>

<p>The HTTP specification does not define the character-encoding for
URLs, so the server must make assumptions about the encoding.</p>
</description>

<schema>
element url-character-encoding {
  string
}
</schema>

</defun>

<defun title="&lt;url-regexp>" version="Resin 3.1" name="url-regexp">
<parents>cache-mapping, filter-mapping, path-mapping, servlet-mapping, servlet-regexp, web-app</parents>

<description>
<p>
&lt;url-regexp> matches the portion of the url that
follows the <g>context path</g>.  A webapp in <code>webapps/ROOT</code>,
and a url <code>http://localhost/foo/hello.html</code> will have
a value of <code>"/foo/hello.html"</code> for the purposes of the
regular expression match.  A webapp in <code>webapps/baz</code> and
a url <code>http://localhost/baz/hello.html</code> will have a url of
<code>"/hello.html"</code> for the purposes of the regular expression
match, because "/baz" is the context path.
</p>
</description>

</defun>

<defun title="&lt;user-data-constraint>" name="user-data-constraint" version="Servlet" type="defun">
<parents>security-constraint</parents>

<description>
<p>Restricts access to secure transports, such as SSL</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>transport-guarantee</td>
  <td>Required transport properties.  NONE,
INTEGRAL, and CONFIDENTIAL are allowed values.</td>
</tr>
</attributes>

<schema>
element user-data-constraint {
  transport-guarantee
}
</schema>

</defun>

<defun title="&lt;user-name>" version="Resin 4.0" name="user-name">
<parents>server</parents>

<description>
<p>&lt;user-name> configures the operating system user Resin should
run as.  Since the HTTP port 80 is protected in Unix, the web server
needs to start as root to bind to port 80.  For security, Resin should
switch to a non-root user after binding to port 80.</p>
</description>

<example title="resin.xml with user-name">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">

    &lt;server-default>
      &lt;http port="80"/>

      &lt;user-name>resin&lt;/user-name>
    &lt;/server-default>

    &lt;server id="web-a"/>
    ...
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="Variables: java">

<deftable title="java properties">
<tr>
  <th>Property</th>
  <th>Description</th>
</tr>
<tr>
  <td>version</td>
  <td>Returns the JDK version from the java.version property</td>
</tr>
</deftable>

</defun>

<defun title="Variables: resin">

<deftable title="resin properties">
<tr>
  <th>Property</th>
  <th>Description</th>
</tr>
<tr>
  <td>address</td>
  <td>The machine's address as returned by InetAddress</td>
</tr>
<tr>
  <td>conf</td>
  <td>The path to the resin.xml</td>
</tr>
<tr>
  <td>home</td>
  <td>The --resin-home value, i.e. the location of the Resin installation</td>
</tr>
<tr>
  <td>homeName</td>
  <td>The local hostname as returned by InetAddress</td>
</tr>
<tr>
  <td>id</td>
  <td>The --serverId command line value (see serverId)</td>
</tr>
<tr>
  <td>isProfessional()</td>
  <td>True if Resin professional is installed and licensed</td>
</tr>
<tr>
  <td>root</td>
  <td>The --resin-root value, i.e. the site's deployment directory</td>
</tr>
<tr>
  <td>serverId</td>
  <td>The --serverId command line value</td>
</tr>
<tr>
  <td>version</td>
  <td>The Resin version</td>
</tr>
<tr>
  <td>versionDate</td>
  <td>The compilation date of Resin</td>
</tr>
</deftable>

</defun>
<defun title="Variables: system">

<p>The ${system} variable return the <code>System.getProperties()</code>
value.</p>

<example title="Example: returning -Dfoo=bar">
&lt;resin xmlns="http://caucho.com/ns/resin"
      xmlns:resin="http://caucho.com/ns/resin/core">

  &lt;resin:message>${system['foo']}&lt;/resin:message>

  ...
&lt;/resin>
</example>

</defun>


<defun title="&lt;watchdog>" name="watchdog">

<description>
<p>The &lt;watchdog> tag is used in ISP-style
configurations where the &lt;watchdog-manager> is configured separately
from the resin.xml instances, and where the configuration file is generally
not readable by the instance users.</p>

<p>The &lt;watchdog> tag corresponds to the &lt;server> tag in standard
resin.xml configurations, and specifies the resin.xml, the root directory
and resin-user.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>chroot</td>
  <td>calls chroot before starting the Resin process</td>
  <td></td>
</tr>
<tr>
  <td>group-name</td>
  <td>setgid value for unix systems</td>
  <td></td>
</tr>
<tr>
  <td>java-exe</td>
  <td>java executable to use for the Resin instance</td>
  <td>java</td>
</tr>
<tr>
  <td>java-home</td>
  <td>JAVA_HOME value for the Resin instance</td>
  <td></td>
</tr>
<tr>
  <td>open-port</td>
  <td>list of ports the watchdog should open for the Resin instance, e.g.
for ports that require root access</td>
  <td></td>
</tr>
<tr>
  <td>resin.xml</td>
  <td>Path to the resin.xml file for the Resin instance</td>
  <td>same as for watchdog</td>
</tr>
<tr>
  <td>resin-root</td>
  <td>Root directory for the Resin instance</td>
  <td>same as for watchdog</td>
</tr>
</attributes>

<schema>
element watchdog {
  attribute id { string }
  &amp; chroot?
  &amp; group-name?
  &amp; java-exe?
  &amp; java-home?
  &amp; jvm-arg*
  &amp; resin.xml?
  &amp; resin-root?
  &amp; open-port { address &amp; port }*
  &amp; user-name?
}
</schema>

</defun>

<defun title="&lt;watchdog-arg>" version="Resin 4.0" name="watchdog-arg">
<parents>server</parents>

<description>
<p>The &lt;watchdog-arg> configures arguments for the
watchdog process.  The watchdog improves reliability by
monitoring the Resin instance, restarting it if necessary.</p>

<p>The &lt;watchdog-arg> typically is used to enable <g>jconsole</g>
for the watchdog JVM.</p>
</description>

<example title="resin.xml">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">
    &lt;server-default>

      &lt;watchdog-arg>-Dcom.sun.management.jmxremote&lt;/watchdog-arg>

    &lt;/server-default>

    ...
       
  &lt;/cluster>
&lt;/resin>
</example>

</defun>

<defun title="&lt;watchdog-manager>" name="watchdog-manager">

<description>
<p>For ISP configurations, &lt;watchdog-manager> is used for a separate
resin.xml just to configure the watchdog-manager itself.  The
&lt;watchdog-manager> selects the &lt;user-name>, &lt;resin.xml>,
ports, and Resin home directories before giving access to the user's
Resin instance.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>watchdog</td>
  <td>Watchdog configuration for a Resin instance, corresponding to a &lt;server> in the resin.xml</td>
  <td></td>
</tr>
<tr>
  <td>watchdog-address</td>
  <td>The TCP address the watchdog-manager listens for start, stop, status</td>
  <td>127.0.0.1</td>
</tr>
<tr>
  <td>watchdog-default</td>
  <td>Defaults applied to all watchdog instances</td>
  <td></td>
</tr>
<tr>
  <td>watchdog-jvm-arg</td>
  <td>JVM arguments for the watchdog-manager when launched</td>
  <td></td>
</tr>
<tr>
  <td>watchdog-port</td>
  <td>The TCP port the watchdog-manager listens for start, stop, status</td>
  <td>6700</td>
</tr>
</attributes>

<schema>
element watchdog-manager {
  watchdog*
  &amp; watchdog-address?
  &amp; watchdog-default*
  &amp; watchdog-jvm-arg*
  &amp; watchdog-port?
}
</schema>

</defun>

<defun title="&lt;watchdog-port>" version="Resin 4.0" name="watchdog-port">
<parents>server</parents>
<default>6700</default>

<description>
<p>&lt;watchdog-port> configures the administration port for the
watchdog JVM.  The watchdog launches the server JVM and monitors its
health, restarting the JVM when necessary to improve site reliability.
The command line arguments use the watchdog-port for
the "start" and "stop" commands to tell the watchdog to start and
stop the server JVM.  The administration also uses the watchdog port
for watchdog administration.</p>

<p>The watchdog port will use the same &lt;address> as the server, so it
will always be an internal network address, never an external internet
address.</p>
</description>
</defun>

<defun title="&lt;web-app>" name="web-app">
<parents>host, web-app</parents>

<description>
<p>web-app configures a web application.</p>

<p>When specified by <var>id</var>, the application will be initialized on
server start.  When specified by <a config-tag="url-regexp"/>, the application
will be initialized at the first request.  This means that
<var>load-on-startup</var> servlets may start later than expected for
<var>url-regexp</var> applications.</p>
</description>

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

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

<example>
&lt;host id=''&gt;
  &lt;web-app id='/apache' root-directory='/usr/local/apache/htdocs'&gt;

  ...

&lt;/host&gt;
</example>

<p>The following example sets the root web-app to the IIS
root directory. </p>

<example>
  &lt;web-app id='/' root-directory='C:/inetpub/wwwroot'&gt;
</example>

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

<p>In the following, each user gets his or her own independent
application using <var>~user</var>.</p>

<example>
&lt;host id=''&gt;

  &lt;web-app url-regexp='/~([^/]*)'
           root-directory='/home/$1/public_html'&gt;

    ...

  &lt;/web-app&gt;

&lt;/host&gt;
</example>
</examples>

</defun>

<defun title="&lt;web-app-default>" version="Resin 3.1" name="web-app-default">
<parents>cluster</parents>

<description>
<p>&lt;web-app-default&gt; defines default values for any <g>web-app</g> in
the cluster.</p>
</description>

<example title="Example: web-app-default">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
    &lt;cluster id="app-tier"&gt;

        &lt;web-app-default&gt;
            &lt;servlet servlet-name="resin-php"
                     servlet-class="com.caucho.quercus.servlet.QuercusServlet"/&gt;

            &lt;servlet-mapping url-pattern="*.php"
                             servlet-name="resin-php"/&gt;
        &lt;/web-app-default&gt;

        &lt;host id=""&gt;
          ...
    &lt;/cluster&gt;
&lt;/resin&gt;
</example>

</defun>

<defun title="&lt;web-app-deploy>" name="web-app-deploy" type="defun">
<parents>host, web-app</parents>

<description>
<p>Specifies war expansion.</p>

<p>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.</p>
</description>

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

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

<s2 title="Overriding web-app-deploy configuration">

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

<example title="Example: resin.xml overriding web.xml">
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;cluster id="">
&lt;host id="">

&lt;web-app-deploy path="webapps"&gt;
  &lt;web-app context-path="/wiki"
              root-directory="wiki"&gt;
    &lt;context-param database="jdbc/wiki"&gt;
  &lt;/web-app&gt;
&lt;/web-app-deploy&gt;

&lt;/host>
&lt;/cluster>
&lt;/resin>
</example>

</s2>

<s2 title="versioning">

<p>The versioning attribute of the &lt;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.</p>

</s2>

<p>The <em>expand-preserve-fileset</em> attribute lets you keep files
for a redeployment, which can improve restart times.
Normally, Resin will delete all files for an update,
including the compiled files for JSP, which forces Resin
to recompile JSP files, even if they haven't changed in the update.
If you add the <em>expand-preserve-fileset</em>, Resin will only recompile the JSP files that have changed.</p>

</defun>

<defun title="&lt;web-resource-collection>" name="web-resource-collection" version="Servlet" type="defun">
<parents>security-constraint</parents>

<description>
<p>Specifies a collection of areas of the web site for security purposes.
See <a href="admin/security-overview.xtp">Resin security</a> for an overview.</p>
</description>

<attributes>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>web-resource-name</td>
  <td>a name for a web resource collection</td>
</tr>
<tr>
 <td>description</td>
  <td></td>
</tr>
<tr>
  <td>url-pattern</td>
  <td>url patterns describing the resource</td>
</tr>
<tr>
  <td>http-method</td>
  <td>HTTP methods to be restricted.</td>
</tr>
<tr>
  <td>method</td>
  <td></td>
</tr>
</attributes>

<schema>
element web-resource-collection {
  url-method*
  &amp; http-method*
  &amp; web-resource-name?
}
</schema>

</defun>

<defun title="&lt;welcome-file-list>" name="welcome-file-list" version="Servlet 2.2" type="defun">
<parents>web-app</parents>

<description>
<p>Sets the files to use as when no filename is present in
url. According to the spec, each file is in a &lt;welcome-file&gt;
element.</p>
</description>

<schema>
element welcome-file-list {
  string
  | welcome-file*
}
</schema>

<example title="Example: WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;welcome-file-list&gt;
    &lt;welcome-file&gt;index.jsp&lt;/welcome-file&gt;
    &lt;welcome-file&gt;index.xtp&lt;/welcome-file&gt;
    &lt;welcome-file&gt;home.xtp&lt;/welcome-file&gt;
  &lt;/welcome-file-list&gt;
&lt;/web-app&gt;
</example>

<p>Resin also provides a shortcut where you can just list the files:</p>

<example title="Example: WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;welcome-file-list&gt;
    index.jsp, index.xtp, home.xtp
  &lt;/welcome-file-list&gt;
&lt;/web-app&gt;
</example>

<default>in $RESIN_HOME/conf/app-default.xml is index.xtp, index.jsp, index.html.</default>

</defun>

<defun title="&lt;work-dir>" name="work-dir" occur="?" version="Resin 2.0.0">
<parents>resin, config, host, web-app</parents>
<default>Defaults to <var>WEB-INF/work</var></default>

<description>
<p>&lt;work-dir> configures a work directory for automatically generated
code, e.g. for JSP, PHP, and JPA classes.</p>
</description>

<schema>
element work-dir {
  string
}
</schema>
</defun>

</body>
</document>
