<document>
<header>
  <product>resin</product>
  <title>Web Application: tags</title>
  <version>Resin 3.0</version>

  <description>

  <p>Web applications are configured with the &lt;web-app> tag, which can occur in a number of places.</p>
      
  <ul>
        
  <li><var type="file">WEB-INF/web.xml</var> contains a top-level
  web-app element.  It is the Servlet standard location for defining
  things like servlet mappings and security roles.</li>
        
  <li><var type="file">WEB-INF/resin-web.xml</var> is also used by
  Resin and will override and supplement the configuration in <var type="file">WEB-INF/web.xml</var>.  Use it to specify Resin specific
  configuration if you prefer to keep <var>WEB-INF/web.xml</var> strictly
  conforming to the Servlet specification.</li>
        
  <li>A web application can also be configured in the main Resin
  configuration, and in this context <var>web-app</var> is a child of &lt;<a href="host-tags.xtp">host</a>&gt;.</li>

  </ul>

  </description>
</header>

<body>

<localtoc/>

<s1 title="See Also">
<ul>
<li><a href="env-tags.xtp">Resources tags</a> for beans, components,
databases, @Stateless and @Stateful EJBs, JMS queues, etc.</li>
<li><a href="resin-security.xtp">Security</a> for a full description
of Resin's authentication and authorization.</li>
<li><a href="rewrite-tags.xtp">Rewrite tags</a> for Resin's rewrite-dispatch
rewriting.</li>
</ul>
</s1>

<defun title="&lt;access-log>">
<parents>web-app</parents>

<p>&lt;access-log> configures a HTTP access log for an indivitual
web-app.  See <a href="host-tags.xtp#%3caccess-log%3d">access-log</a>
in the &lt;host> tag for more information.</p>

</defun>

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

<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>

<def title="&lt;active-wait-time> schema">
element active-wait-time {
  r_period-Type
}
</def>

</defun>

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

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

<def title="&lt;allow-servlet-el> schema">
element allow-servlet-el {
  r_boolean-Type
}
</def>

</defun>

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

<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>

<def title="&lt;archive-path> schema">
element archive-path {
  r_path-Type
}
</def>

<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/www/foo"
             archive-path="/var/www/wars/foo.war"/>

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

</defun>

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

<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="resin-security.xtp">Resin security</a>).  When using Resin's &lt;management> authentication
as a default, the role name is <var>resin-admin</var>.  (See
<a href="resin-admin.xtp">Resin management</a>.)</p>

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

<def title="&lt;auth-constraint> schema">
element auth-constraint {
  description*,

  role-name*
}
</def>

<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;cache-mapping>" version="Resin 1.1">
<parents>web-app</parents>
      
<p>&lt;cache-mapping> specifies <var>max-age</var> and <var>Expires</var> times for cacheable pages.</p>

<p>See <a href="proxy-cache.xtp">caching</a> for more information.</p>

<p>&lt;cache-mapping> 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> does not automatically make pages cacheable.  Your
servlets must already set the <var>ETag</var> (or Last-Modified) header
to activate &lt;cache-mapping>.</p>
      
<deftable-childtags>
<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>url-regexp</td>
    <td>A regular expression matching the url</td>
    <td></td>
</tr>
</deftable-childtags>

<p>The time interval defaults to seconds, but will allow other periods:</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>

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

<ul>
<li>cache-mapping requires an enabled &lt;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>

<example title="Example: cache-mapping in resin-web.xml">
&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;constraint>" version="Resin">
<parents>security-constraint</parents>

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

<deftable-childtags>
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>resin:type</td>
  <td>A class that extends <a href="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>
</deftable-childtags>

<def title="&lt;constraint> schema">
element constraint {
  class
  &amp; init?
}
</def>

</defun>

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

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

<deftable title="&lt;context-param 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>
</deftable>

<def title="&lt;context-param> schema">
element context-param {
  (param-name, param-value)*
  | (attribute * { string })*
  | (element * { string })*
}
</def>

<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>">
<parents>web-app</parents>

<p>The &lt;cookie-http-only> flag configures the Http-Only attribute
for all Cookies 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>

<def title="&lt;cookie-http-only> schema">
element cookie-http-only {
  r_boolean-Type
}
</def>

<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/www/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/www/foo-secure">
      &lt;secure/>
    &lt;web-app id="">
  &lt;/host>

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

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

<p>Specifies ear expansion.</p>

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

<deftable title="&lt;ear-deploy> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>archive-path</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>
</deftable>

<def title="&lt;ear-deploy> 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?
}
</def>

</defun>

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

<deftable-childtags>
<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>
</deftable-childtags>

<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>

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

<p>By default, Resin returns a 500 Servlet Error and a stack trace for
exceptions and a simple 404 File Not Found for error pages.  Applications can
customize the response generated for errors.  </p>

<example title="Example: 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="Example: 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>

<p>The error page can use request attributes to obtain information about the
request that caused the error:</p>

<example title="Example: /file_not_found.jsp">
&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;filter>" version="Servlet 2.3">

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

<deftable-childtags>
<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 href="javadoc|javax.servlet.Filter">javax.servlet.Filter</a></td>
</tr>
<tr>
  <td>init</td>
  <td>Resin-IoC initialization configuration, see <a href="resin-ioc.xtp">Resin-IoC</a></td>
</tr>
<tr>
  <td>init-param</td>
  <td>Initialization parameters, see <a href="javadoc|javax.servlet.FilterConfig">FilterConfig.getInitParameter</a></td>
</tr>
</deftable-childtags>

<def title="&lt;filter> schema">
element filter {
  filter-name
  &amp; filter-class
  &amp; init*
  &amp; init-param*
}
</def>

<p>The following example defines a filter alias 'image'</p>
<example title="Example: WEB-INF/resin-web.xml">
&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>

<p>The full Servlet 2.3 syntax for <var>init-param</var> is supported as
well as a simple shortcut.</p>

<example title="WEB-INF/resin-web.xml">
&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>" version="Servlet 2.3" type="defun">
<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 servlet class directly or it
can specify a servlet alias defined by <code>filter</code>.
</p>

<deftable title="&lt;filter-mapping> 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>url-regexp</td>
  <td>A regular expression matching the portion of the url that follows the <g>context path</g></td>
  <td></td>
</tr>
</deftable>

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

<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>

<p>
<code>url-regexp</code> 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>

</defun>

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

<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>

<deftable title="&lt;form-login-config> 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>
</deftable>

<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>

<deftable-childtags>
<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>
</deftable-childtags>

<def title="&lt;form-login-config> schema">
element form-login-config {
  form-login-page,
  form-error-page,
  internal-forward,
  form-uri-priority
}
</def>

<p>The following is an example of a servlet-standard login page:</p>

<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;idle-time>">
<parents>web-app</parents>

<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>

<def title="&lt;idle-time> schema">
element idle-time {
  r_period-Type
}
</def>

</defun>

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

<p>Configures JSF behavior.</p>

<deftable-childtags>
<tr>
  <th>Attribute</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>fast-jsf</td>
  <td>Optimize JSF code generation</td>
  <td>true</td>
</tr>
<tr>
  <td>state-serialization-method</td>
  <td>Configures method of JSF state serialization. Setting value to
    <code>hessian</code> provides fast, size optimized Hessian
    serialization. Method <code>java</code> allows fallback
    to Java Serialization.
  </td>
  <td>hessian</td>
</tr>
<tr>
  <td>enable-developer-aid</td>
  <td>if true, makes snapshots of component tree and request information
    available via a link displayed at the right bottom corner of a JSF page.
  </td>
  <td>false</td>
</tr>
<tr>
  <td>developer-aid-link-style</td>
  <td>controls appearance of the <em>JSF Dev Aid</em> on a JSF page.
  </td>
  <td>position:absolute; bottom:0; right:0</td>
</tr>
<tr>
  <td>disable-managed-bean-property-check</td>
  <td>if true disables checking of setter's existence for managed-bean->managed-property.
  </td>
  <td>false</td>
</tr>
</deftable-childtags>

<def title="&lt;jsf> schema">
element jsf {
  &amp; fast-jsf?
}
</def>

</defun>

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

<p>Configures JSP behavior.</p>

<deftable-childtags>
<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>
</deftable-childtags>

<def title="&lt;jsp> 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?
}
</def>

</defun>

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

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

<deftable title="&lt;jsp-config> 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>
</deftable>

<def title="&lt;jsp-config> 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*
}
</def>

</defun>

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

<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>

<def title="&lt;lazy-servlet-validate> schema">
element lazy-servlet-validate {
  r_boolean-Type
}
</def>

</defun>

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

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

<deftable title="&lt;listener> 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>
</deftable>

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

<def title="&lt;listener> schema">
element listener {
  listener-class,
  init?
}
</def>

</defun>

<defun title="&lt;login-config>" version="Servlet 2.2">
<parents>web-app</parents>
<default>no authentication</default>

<p>Configures the login method for authentication, one of BASIC,
DIGEST or FORM.</p>

<p>See also: <a href="resin-security.xtp">Resin security</a> for an
overview.</p>

<deftable-childtags title="&lt;login-config> 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="security-digest.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>
</deftable-childtags>

<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="security-digest.xtp">Digest Passwords</a>.</p>

<def title="&lt;login-config> schema">
element login-config {
  class?
  &amp; auth-method?
  &amp; authenticator?
  &amp; form-login-config?
  &amp; init?
  &amp; realm-name?
</def>

</defun>

<defun title="&lt;mime-mapping>" version="Servlet 2.2">
<parents>web-app</parents>
<p>Maps url patterns to mime-types.</p>

<deftable-childtags title="&lt;mime-mapping> 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>
</deftable-childtags>

<def title="&lt;mime-mapping> schema">
element mime-mapping {
  extension,
  mime-type
}
</def>

<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>" version="Resin 1.2">
<parents>web-app</parents>

<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>

<deftable title="&lt;multipart-form> 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>
</deftable>

<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>

<def title="&lt;multipart-form> schema">
element multipart-form {
  enable?
  &amp; upload-max?
}
</def>

</defun>

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

<p>Maps url patterns to real paths.  If using a server like
IIS, you may need to match the server's path aliases.</p>

<deftable title="&lt;path-mapping> 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>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>
</deftable>

<def title="&lt;path-mapping> schema">
element path-mapping {
  (url-pattern | url-regexp)

  &amp; real-path
}
</def>

<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;protocol>">
<parents>servlet, servlet-mapping</parents>

<p>&lt;protocol> configures a <a href="resin-remoting.xtp">remoting</a>
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 href="http://caucho.com/resin-javadoc/com/caucho/remote/server/AbstractProtocolServletFactory.html">AbstractProtocolServletFactory</a> interface and can register a URI alias to simplify configuration.</p>

<deftable title="&lt;protocol> 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>
</deftable>

<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>

<def title="&lt;protocol> schema">
element protocol {
  (class | uri)
  &amp; init?
}
</def>

<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>">
<parents>web-app</parents>
<default>60s</default>

<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>

<def title="&lt;redeploy-check-interval> schema">
element redeploy-check-interval {
  r_period-Type
}
</def>

</defun>

<defun title="&lt;redeploy-mode>">
<parents>web-app</parents>
<default>automatic</default>

<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>

<deftable>
<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>
</deftable>

<def title="&lt;redeploy-check-interval> schema">
element redeploy-mode {
  automatic | manual
}
</def>

</defun>

<defun title="Resource Tags" version="Resin 3.1">
<parents>cluster, host, web-app</parents>

<p>See the <a href="env-tags.xtp">Resource tag documentation</a> for
 a full list of resources available to the web-app.</p>

<p>All resource tags are available to
the &lt;web-app>, like databases, IoC beans and components, EJB stateful,
stateless and message beans, JMS queues, remote clients, etc.</p>

<example title="Example: web-app database in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;database jndi-name="jdbc/test"&gt;
    &lt;driver type="org.postgresql.Driver"&gt;
      &lt;url&gt;jdbc:postgresql://localhost/test&lt;/url&gt;
      &lt;user&gt;caucho&lt;/user&gt;
    &lt;/driver&gt;
  &lt;/database&gt;
&lt;/web-app&gt;
</example>

<p>Or <a href="ioc-bean.xtp">IoC-configured Beans</a>:</p>

<example title="Example: IoC bean in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;bean jndi-name="jdbc/test" type="example.Theater&gt;
    &lt;init name="Balboa Theater">
      &lt;movie title="Attack of the Killer Tomatoes"/>

      &lt;movie title="Snakes on a Plane"/>

      &lt;movie title="Casablanca"/>
    &lt;/init>
  &lt;/bean>
&lt;/web-app&gt;
</example>

</defun>

<defun title="&lt;rewrite-dispatch>" version="Resin 3.1">
<parents>cluster, host, web-app</parents>

<p>&lt;rewrite-dispatch&gt; defines a set of rewriting rules for
dispatching and forwarding URLs.  Applications can use these rules
to redirect old URLs to their new replacements.</p>

<p>See <a href="rewrite-tags.xtp">rewrite-dispatch</a> for more
details.</p>

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

 &lt;rewrite-dispatch>
   &lt;dispatch regexp="\.(php|gif|css|jpg|png)"/>
   &lt;forward regexp="^" target="/index.php"/>
 &lt;/rewrite-dispatch>

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

</defun>

<defun title="&lt;rewrite-real-path>" version="Resin 3.1">
<parents>cluster, host, web-app</parents>

<p>&lt;rewrite-real-path> lets you rewrite the URL to physical path
mapping, to allow aliasing or for filesystem organization.</p>

<deftable title="&lt;rewrite-real-path> 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>
</deftable>

<def title="&lt;rewrite-real-path> schema">
element rewrite-real-path {
  element rewrite {
    regexp
    &amp; replacement
  }*

  &amp; element rewrite {
    regexp
    &amp; target
  }*
}
</def>

<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;root-directory>" version="Resin 3.1">

<p>&lt;root-directory> configures the web-app's filesystem root.</p>

<def title="&lt;root-directory> schema">
element root-directory {
  string
}
</def>

</defun>

<defun title="&lt;secure>">
<parents>web-app</parents>

<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>

<def title="&lt;secure> schema">
element secure {
  r_boolean-Type
}
</def>

</defun>

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

<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="resin-security.xtp">Resin
security</a> for an overview.</p>

<p>Security constraints can also be custom classes.</p>

<p>See <a href="resin-security.xtp">Resin security</a> for an overview of
security issues and configuration.</p>

<deftable title="&lt;security-constraint> 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>
</deftable>

<def title="&lt;security-constraint> content">
element security-constraint {
  auth-constraint*
  &amp; constraint*
  &amp; ip-constraint*
  &amp; role-name*
  &amp; user-data-constraint*
  &amp; url-pattern?
  &amp; web-resource-collection*
}
</def>

<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;servlet>" version="Servlet 2.2">

<p>Defines a servlet to process HTTP URL requests.  The servlet class
can either implement <a href="http://caucho.com/resin-javadoc/javax/servlet/Servlet.html">javax.servlet.Servlet</a> to handle the HTTP request
directly or it can use a <a href="resin-remoting.xtp">remoting</a>
protocol like SOAP or Hessian to handle remoting requests.</p>

<p>Since servlets are full <a href="resin-ioc.xtp">Resin-IoC</a> beans,
they can use dependency injection, EJB aspects like @TransactionAttribute,
custom @InterceptorType interceptors, and listen for @Observes events.</p>

<deftable title="&lt;servlet> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>init</td>
  <td><a href="resin-ioc.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 <a href="resin-remoting.xtp">Resin remoting</a>.</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>
</deftable>

<def title="&lt;servlet> 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?
}
</def>

<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-mapping>" version="Servlet 2.2">
<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>

<deftable title="&lt;servlet-mapping> Attributes">
<tr>
  <th>Attribute</th>
  <th>Description</th>
</tr>
<tr>
  <td>init</td>
  <td><a href="resin-ioc.xtp">Resin-IoC</a> configuration of the
servlet.</td>
</tr>
<tr>
  <td>protocol</td>
  <td>Defines the optional <a href="resin-remoting.xtp">remoting</a>
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>url-regexp</td>
  <td>A regular expression matching the portion of the url that follows the <g>context path</g></td>
</tr>
</deftable>

<def title="&lt;servlet-mapping> schema">
element servlet-mapping {
  init?
  &amp; protocol?
  &amp; servlet-class?
  &amp; servlet-name?
  &lt; url-pattern*
  &lt; url-regexp*
}
</def>

<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;/servlet-class&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-class&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>
<code>url-regexp</code> 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>

<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>" version="Resin 3.0" type="defun">
<p>Maps URL by regular expressions to custom servlets.</p>

<def title="&lt;servlet-regexp> schema">
element servlet-regexp {
  init?
  &amp; servlet-class?
  &amp; servlet-name?
  &amp; url-regexp
}
</def>

<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="&lt;session-config>" version="Servlet 2.2">

<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="resin-clustering.xtp">Resin clustering</a> for more
information about distributed sessions and persistence.</p>

<deftable title="&lt;session-config> 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-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>false</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>4096</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>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="resin.xtp#persistent-store">persistent-store</a> to save sessions. (resin 3.0.8)</td>
  <td>none</td>
</tr>
</deftable>

<def title="&lt;session-config> schema">
element session-config {
  always-load-session?
  &amp; always-save-session?
  &amp; cookie-append-server-index?
  &amp; cookie-domain?
  &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?
}
</def>

<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 href="javadoc|com.caucho.server.session.SessionManager|"/></p>

</defun>

<defun title="&lt;shutdown-wait-max>" version="Resin 3.0.4" type="defun">
<p>The maximum time Resin will wait for requests to finish before closing the web-app.</p>
<default>15s</default>

<def title="&lt;shutdown-wait-max> schema">
element shutdown-wait-max {
  r_period-Type
}
</def>

</defun>

<defun title="&lt;statistics-enable>">
<default>false</default>

<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>

<def title="&lt;statistics-enable> schema">
element statistics-enable {
  r_boolean-Type
}
</def>

</defun>

<defun title="&lt;strict-mapping>" version="Resin 1.2" type="defun">
<default>false, allowing /foo/bar.jsp/foo.</default>
<p>Forces servlet-mapping to follow strict Servlet 2.2, disallowing
PATH_INFO. Value is <var>true</var> or <var>false</var>.</p>

<def title="&lt;strict-mapping> schema">
element strict-mapping {
  r_boolean-Type
}
</def>

<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;user-data-constraint>" version="Servlet" type="defun">
<parents>security-constraint</parents>

<p>Restricts access to secure transports, such as SSL</p>

<deftable title="&lt;user-data-constraints> 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>
</deftable>

<def title="&lt;user-data-constraint> schema">
element user-data-constraint {
  transport-guarantee
}
</def>

</defun>

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

<p>web-app configures a web application.</p>

<deftable-childtags>
<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 href="resin-tags.xtp#startup-mode">Startup and Redeploy Mode</a></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 href="resin-tags.xtp#startup-mode">Startup and Redeploy Mode</a></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>
</deftable-childtags>

<p>When specified by <var>id</var>, the application will be initialized on
server start.  When specified by <var>url-regexp</var>, 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>

<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' document-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='/' document-directory='C:/inetpub/wwwroot'&gt;
</example>

<p>When the <var>web-app</var> is specified with a <var>url-regexp</var>,
<var>document-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='/~([^/]*)'
           document-directory='/home/$1/public_html'&gt;

    ...

  &lt;/web-app&gt;

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

</defun>

<defun title="&lt;web-app-default>" type="defun">
<parents>cluster, host, web-app</parents>
      
<p>Establishes the defaults for a <a config-tag="web-app"/>.</p>

<p>When initializing a web-app, all the tags in
the web-app-defaults sections configure the web-app.  In other words,
the web-app-default value is essentially a macro that is cut-and-pasted
before the web-app configuration.</p>

<p>web-app-default is used for defining server-wide behavior, like *.jsp
handling, and for host-wide behavior.</p>

<example>
&lt;host&gt;
  &lt;web-app-default&gt;
    &lt;servlet servlet-name='test'
             servlet-class='test.MyServlet'/&gt;

    &lt;servlet-mapping url-pattern='*.text' servlet-class='test'/&gt;
  &lt;/web-app-default&gt;
&lt;/host&gt;
</example>

</defun>

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

<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>

<deftable title="&lt;web-app-deploy> 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-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>
</deftable>

<def title="&lt;web-app-deploy> schema">
element web-app-deploy {
  archive-directory?
  expand-cleanup-fileset?
  expand-directory?
  expand-prefix?
  expand-suffix?
  path?
  redeploy-check-interval?
  redeploy-mode?
  require-file*
  startup-mode?
  url-prefix?
  versioning?
  web-app-default*
  web-app*
}
</def>

<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;document-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"
              document-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>

</defun>

<defun title="&lt;web-resource-collection>" version="Servlet" type="defun">
<parents>security-constraint</parents>

<p>Specifies a collection of areas of the web site for security purposes.
See <a href="resin-security.xtp">Resin security</a> for an overview.</p>

<deftable-childtags title="&lt;web-resource-collection> 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>
</deftable-childtags>

<def title="&lt;web-resource-collection> schema">
element web-resource-collection {
  url-method*
  &amp; http-method*
  &amp; web-resource-name?
}
</def>

</defun>

<defun title="&lt;welcome-file-list>" version="Servlet 2.2" type="defun">
<parents>web-app</parents>

<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>

<def title="&lt;welcome-file-list> schema">
element welcome-file-list {
  string
  | welcome-file*
}
</def>

<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>

</body>

</document>
