<document>
<header>
  <product>resin</product>
  <title>Web Application: Servlets and Filters</title>
  <version>Resin 3.0</version>

  <description>

  <glossary title="web application" type="inline">
  A web application is a self-contained
  subtree of the web site.  It has a distinct Application object
  (ServletContext), sessions, and servlet mappings.
  </glossary>

  <p>Web applications are configured with the <a config-tag="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 <a config-tag="host"/>.</li>

  </ul>

  </description>
</header>

<body>

<summary objsummary="localtoc"/>

<s1 title="Resin Web Applications">

<s2 title="cache-mapping" version="Resin 1.1" type="defun">
<parents>web-app-default, web-app</parents>
      
<p>Specifies <var>Expires</var> times for cacheable pages.</p>

<p>cache-mapping is intended to provide Expires times for pages that
have Last-Modified or ETags specified, but do not wish to hard-code the
Expires timeout in the servlet.  For example, Resin's FileServlet relies
on cache-mapping to set the expires times for static pages.</p>
      
<deftable-childtags>
<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><tr><td>expires</td><td>A time interval.</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>

<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="cache-mapping">
&lt;web-app id='/'&gt;

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

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

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

<s2 title="config-file" version="Resin 3.0" type="defun">
<parents>web-app-default, web-app</parents>

<p>Specifies configuration files for the web-app.</p>

<p>The use of files like WEB-INF/web.xml and WEB-INF/resin-web.xml
are configured using &lt;config-file&gt;.  You can add application-specific
 configuration files using the &lt;config-file&gt; tag.</p>

<p>Configuration files will be read and applied in the order they
are specified.</p>

<example title="app-default.xml">
...
&lt;config-file&gt;WEB-INF/web.xml&lt;/config-file&gt;
&lt;config-file&gt;WEB-INF/resin-web.xml&lt;/config-file&gt;
...
</example>

</s2>
    
<s2 title="ear-deploy" type="defun">
<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-childtags>
<tr><td>path</td><td>The path to the deploy directory</td><td>required
</td></tr><tr><td>expand-path</td><td>directory where ears should be expanded</td><td>value of path
</td></tr></deftable-childtags>

</s2>
    
<s2 title="jsp" type="defun">
<parents>web-app-default, web-app</parents>

<p>Configures JSP behavior.</p>

<deftable-childtags>
<tr><td>auto-compile</td><td>Automatically compile changed JSP files</td><td>true
</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 JSP compilation</td><td>true
</td></tr><tr><td>ignore-el-exception</td><td>Ignore exceptions generated in EL expressions</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>precompile</td><td>Try to load precompiled JSP pages</td><td>true
</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>require-source</td><td>Return 404 when JSP source is deleted</td><td>false
</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>session</td><td>Creates sessions for each JSP page</td><td>true
</td></tr><tr><td>velocity-enabled</td><td>Enable Velocity statements</td><td>false
</td></tr></deftable-childtags>

<p>The class that corresponds to &lt;jsp&gt; is 
<a href="javadoc|com.caucho.jsp.cfg.JspPropertyGroup|"/></p>

</s2>

<s2 title="multipart-form" version="Resin 1.2" type="defun">
<parents>web-app-default, 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-childtags>
<tr><td>upload-max</td><td>maximum size of an upload request (in kb).</td><td>no limit
</td></tr></deftable-childtags>

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

<s2 title="path-mapping" type="defun">
<parents>web-app-default, 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-childtags>
<tr><td><var>url-pattern</var></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 url
</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-childtags>

<example>
&lt;web-app id='/'&gt;

&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>
</s2>

<s2 title="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>
</s2>

<s2 title="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>

<example>
&lt;web-app&gt;
  &lt;strict-mapping&gt;true&lt;/strict-mapping&gt;
&lt;/web-app&gt;
</example>
</s2>

<s2 title="web-app-default" type="defun">
<parents>server, host-default, host</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>

</s2>

<s2 title="web-app" type="defun">
<parents>host-default, host, WEB-INF/web.xml, WEB-INF/resin-web.xml</parents>

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

<deftable-childtags>
<tr><td>id</td><td>The url prefix selecting this application.</td><td>n/a
</td></tr><tr><td>url-regexp</td><td>A regexp to select this application.</td><td>n/a
</td></tr><tr><td>document-directory</td><td>The document 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>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></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>

</s2>

<s2 title="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-childtags>
<tr>
  <td>path</td>
  <td>The path to the webapps directory</td>
  <td>required</td>
</tr>
<tr>
  <td>url-prefix</td>
  <td>url-prefix added to all expanded webapps</td>
  <td>""</td>
</tr>
<tr>
  <td>expand-path</td>
  <td>directory where wars should be expanded</td>
  <td>value of path</td>
</tr>
<tr>
  <td>lazy-init</td>
  <td>true if web-apps should only be initialized when first used</td>
  <td>false</td>
</tr>
<tr>
  <td>versioning</td>
  <td>if true, versioned applications are served according to the base-name, e.g. webapps/foo-1.1 is served as /foo.</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-childtags>

<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="overriding web.xml">
&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;
</example>

</s2>

</s1>

<s1 title="Servlet 2.4">

<p>Resin implements the Servlet 2.4 specification.</p>

<s2 title="description" version="Servlet" type="defun">
</s2>

<s2 title="display-name" version="Servlet" type="defun">
</s2>

<s2 title="distributable" version="Servlet" type="defun">
</s2>

<s2 title="context-param" version="Servlet 2.2" type="defun">
<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|getInitParameter(String)"/>.</p>

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

  &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>
</s2>

<s2 title="filter" version="Servlet 2.3" type="defun">
<p>Defines a filter alias for later mapping.</p>

<deftable-childtags>
<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|"/>
</td></tr><tr><td>init-param</td><td>Initialization parameters, see <a href="javadoc|javax.servlet.FilterConfig">FilterConfig.getInitParameter(String)</a>.
</td></tr></deftable-childtags>

<p>The following example defines a filter alias 'image'</p>
<example>
&lt;web-app id='/'&gt;

  &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>
&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>
</s2>

<s2 title="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-childtags title="Servlet 2.4 definition for filter-mapping">
<tr><td>filter-name</td><td>The filter 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>dispatcher</td><td>
</td></tr></deftable-childtags>

<deftable-childtags title="Resin extensions to filter-mapping">
<tr><td>url-regexp</td><td>A regular expression matching the url
</td></tr><tr><td>filter-name</td><td>The filter name can use replacement vars
from url-regexp like <var>$1</var>.  It can also specify a
class name directly like <var>test.HelloWorld</var></td><td>n/a
</td></tr></deftable-childtags>

<example>
&lt;web-app&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>
</s2>

<s2 title="listener" version="Servlet" type="defun">
</s2>

<s2 title="servlet" version="Servlet 2.2" type="defun">
<p>Defines a servlet alias for later mapping using <a config-tag="servlet-mapping"/>.</p>

<deftable-childtags>
<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><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>run-at</td><td>Times to execute the servlet automatically,
A Resin extension.
</td></tr></deftable-childtags>

<example title="using the &lt;servlet&gt; tag">
&lt;web-app id='/'&gt;

  &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="multiple servlets using the same class">
&lt;web-app&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="servlet-mapping's 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>
</s2>

<s2 title="servlet-mapping" version="Servlet 2.2" type="defun">
<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-childtags title="Servlet 2.4 definition for servlet-mapping">
<tr><td>servlet-name</td><td>The servlet name</td><td>n/a
</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>n/a
</td></tr></deftable-childtags>

<deftable-childtags title="Resin extensions to servlet-mapping">
<tr><td>url-regexp</td><td>A regular expression matching the url</td><td>n/a
</td></tr><tr><td>servlet-name</td><td>The servlet name can use replacement vars
from url-regexp like <var>$1</var>.  It can also specify a
class name directly like <var>test.HelloWorld</var></td><td>n/a
</td></tr></deftable-childtags>

<example title="servlet-mapping">
&lt;web-app id='/'&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;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>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="servlet invoker">
&lt;web-app id='/'&gt;

  &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="servlet-mapping's in $RESIN_HOME/conf/app-default.xml">
&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;
</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><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>
</s2>

<s2 title="servlet-regexp" version="Resin 3.0" type="defun">
<p>Maps URL by regular expressions to custom servlets.</p>

<example>
&lt;servlet-regexp url-regexp="/([^.]*).do"
                servlet-class="qa.\${regexp[1]}Servlet"&gt;
  &lt;init a="b"/&gt;
&lt;/servlet-regexp&gt;
</example>

</s2>

<s2 title="session-config" version="Servlet 2.2" type="defun">
<p>Session configuration parameters.</p>

<deftable-childtags title="Servlet 2.4 definition for session-timeout">
<tr><td>session-timeout</td><td>The session timeout in minutes, 0 means never timeout.</td><td>30 minutes
</td></tr></deftable-childtags>

<p>Resin add's a number of <var>session-config</var> tags.</p>

<deftable-childtags title="Resin extensions to session-config">
<tr><td>session-max</td><td>Maximum active sessions</td><td>4096
</td></tr><tr><td>enable-cookies</td><td>Enable cookies for sessions. (resin 1.1)</td><td>true
</td></tr><tr><td>enable-url-rewriting</td><td>Enable URL rewriting for sessions. (resin 1.1)</td><td>true
</td></tr><tr><td>cookie-version</td><td>Version of the cookie spec for sessions. (resin 1.2)</td><td>1.0
</td></tr><tr><td>cookie-domain</td><td>Domain for session cookies. (resin 1.2)</td><td>none
</td></tr><tr><td>cookie-max-age</td><td>Max age for persistent session cookies. (resin 2.0)</td><td>none
</td></tr>
<tr>
  <td>cookie-length</td>
  <td>Maximum length of the cookie. (resin 2.1.1)</td>
  <td>Integer.MAX_VALUE</td>
</tr>
<tr>
  <td>file-store</td>
  <td>Persistent sessions using a file store. (resin 1.2)</td>
  <td>none</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><tr><td>always-load-session</td><td>Reload data from the store on every request. (resin 1.2)</td><td>false
</td></tr><tr><td>always-save-session</td><td>Save session data to the store on every request. (resin 1.2)</td><td>false
</td></tr><tr><td>save-only-on-shutdown</td><td>Only save session when the application shuts down. (resin 1.2.3)</td><td>false
</td></tr><tr><td>reuse-session-id</td><td>Reuse the session id even if the session has timed out. (resin 2.0.4)</td><td>true
</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>. (resin 3.0)</td><td>
</td></tr></deftable-childtags>

<p>By default, both <code>enable-cookies</code> and
<code>enable-url-rewriting</code> are true. To force url rewriting, you
would create a configuration like:</p>

<example>
&lt;web-app id='/'&gt;

  &lt;session-config
   enable-cookies='false'
   enable-url-rewriting='true'/&gt;

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

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

</s2>

<s2 title="mime-mapping" version="Servlet 2.2" type="defun">
<parents>web-app-default, web-app</parents>
<p>Maps url patterns to mime-types.</p>

<deftable-childtags>
<tr><td>extension</td><td>url extension
</td></tr><tr><td>mime-type</td><td>the mime-type
</td></tr></deftable-childtags>

<example>
&lt;web-app id='/'&gt;

  &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>
</s2>

<s2 title="welcome-file-list" version="Servlet 2.2" type="defun">
<parents>web-app-default, web-app</parents>
<default>in $RESIN_HOME/conf/app-default.xml is index.xtp, index.jsp, index.html.</default>

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

<example>
&lt;web-app id='/'&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>
&lt;web-app id='/'&gt;
  &lt;welcome-file-list&gt;
    index.jsp, index.xtp, home.xtp
  &lt;/welcome-file-list&gt;
&lt;/web-app&gt;
</example>

</s2>

<s2 title="error-page" version="Servlet 2.2" type="defun">
<parents>web-app-default, web-app</parents>

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

<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="Catching File Not Found">
&lt;web-app&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 id='/foo'&gt;
      &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="/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>

<s3 title="Request attributes for error handling">

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

</s3>

</s2>

<s2 title="jsp-config" version="Servlet" type="defun">
</s2>

<s2 title="resource-env-ref" version="Servlet" type="defun">
</s2>

<s2 title="message-destination-ref" version="Servlet" type="defun">
</s2>

<s2 title="resource-ref" version="Servlet" type="defun">
</s2>

<s2 title="security-constraint" version="Servlet" type="defun">
<parents>web-app-default, 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.</p>

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

<example>
&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;
</example>
</s2>

<s2 title="display-name" version="Servlet" type="defun">
<parents>security-constraint</parents>
</s2>

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

<p>Specifies a collection of areas of the web site.</p>

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

<s2 title="auth-constraint" version="Servlet" type="defun">
<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>

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

</s2>

<s2 title="user-data-constraint" version="Servlet" type="defun">
<parents>security-constraint</parents>

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

<deftable-childtags>
<tr><td>transport-guarantee</td><td>Required transport properties.  NONE,
INTEGRAL, and CONFIDENTIAL are allowed values.
</td></tr></deftable-childtags>

</s2>

<s2 title="constraint" version="Resin" type="defun">
<parents>security-constraint</parents>

<p>
Defines a custom constraint.
</p>

<deftable-childtags>
<tr><td>resin:type</td><td>A class that extends <a href="javadoc|com.caucho.http.security.AbstractConstraint|"/>
</td></tr><tr><td>init</td><td>initialization parameters, set in the object using Bean-style setters and getters
</td></tr></deftable-childtags>

</s2>

<s2 title="login-config" version="Servlet 2.2" type="defun">
<parents>web-app-default, web-app</parents>
<default>no authentication</default>

<deftable-childtags title="Servlet 2.4 definition for login-config">
<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>realm-name</td><td>The realm name to use in HTTP authentication
</td></tr><tr><td>form-login-config</td><td>Configuration for form login, see <a config-tag="form-login-config"/>
</td></tr></deftable-childtags>

<deftable-childtags title="Resin extensions to login-config">
<tr><td>type</td><td>Defines a custom class which extends <code>com.caucho.server.security.AbstractLogin</code>
</td></tr><tr><td>init</td><td>Initialization for the custom login class
</td></tr></deftable-childtags>


<p>HTTP Authentication is defined in the RFC <a href="http://www.faqs.org/rfcs/rfc2617.thml">HTTP Authentication: Basic and
Digest</a>.</p> 

<p>HTTP digest authentication is discussed in <a href="security-digest.xtp">Digest Passwords</a>.

</p></s2>


<s2 title="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-childtags title="Servlet 2.4 definition for form-login-config">
<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></deftable-childtags>

<deftable-childtags title="Resin extensions to form-login-config">
<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-childtags>

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

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

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

</s2>

<s2 title="security-role" version="Servlet" type="defun">
</s2>

<s2 title="env-entry" version="Servlet" type="defun">
</s2>

<s2 title="ejb-ref" version="Servlet" type="defun">
<parents>web-app-default, web-app</parents>
</s2>

<s2 title="ejb-local-ref" version="Servlet" type="defun">
<parents>web-app-default, web-app</parents>
</s2>

<s2 title="message-destination" version="Servlet" type="defun">
</s2>

<s2 title="locale-encoding-mapping-list" version="Servlet" type="defun">
</s2>
</s1>
</body>

</document>