<title>Web Application Configuration</title>

HTTP configuration follows the Servlet 2.2 deployment descriptors.
The nesting order is important, but order is generally not important.
In the sections that follow, the section
header tells where the attribute belongs.  For example, an attribute in
<var/caucho.com/http-server/host/> belongs in a <var/host/> element which
belongs in an <var/http-server/> element which belongs in the
<var/caucho.com/> element.

<p/>The application configuration can be placed in <var/WEB-INF/web.xml/>
If <var/web.xml/> exists, Resin will use it to configure the application.

<p/><a href='servlet-config.xtp'>Servlet</a> configuration interacts with the
application configuration.  In particular, <var/servlet-mapping/> tells Resin
how to map urls to servlets.

<objsummary/>

<section name='web-app' title=web-app>

<defun name=access-log title='access-log' index='access-log'>
<sum>Specifies the access logging.</sum>  See
the host <a href="http-config.xtp#access-log">access-log</a> for more details.

<p/>By default, uses the host access-log.
</defun>

<defun name=app-dir title='app-dir' index='app-dir' version="Resin 1.1">
<sum>Specifies the directory of the application.</sum>  If
unspecified, the application will have the same path as the id.  When
the <var/web-app/> is specified with a <var/url-regexp/>,
<var/app-dir/> can use replacement variables (<var/$2/>).

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

<deftable>
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>id<td>The url prefix selecting this application.<td>n/a
<tr><td>url-regexp<td>A regexp to select this application.<td>n/a
<tr><td>app-dir<td>The root document directory for the application (can use
regexp replacement variables.)<td>Same as id or the regexp match
</deftable>

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

<example>
&lt;host id=''&gt;
  &lt;web-app id='/apache' app-dir='/usr/local/apache/htdocs'&gt;

 ...

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

<p/>The following example sets the root application to the IIS
root directory.  The host and web-app will use the http-server app-dir
as a default.

<example>
&lt;caucho.com&gt;
&lt;http-server app-dir='c:\inetpub\wwwroot'&gt;

 ...

&lt;/http-server&gt;
&lt;/caucho.com&gt;
</example>

<p/>In the following, each user gets her own independent
application using ~user.  (Note, since mod_caucho and IIS don't understand
regexps, so you may need to manually configure the web server.)

<example>
&lt;host id=''>

&lt;web-app url-regexp='/~([^/]*)'
         app-dir='/home/$1/public_html'>

 ...

&lt;/web-app>

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

<p/>By default, uses the subdiretory under the host app-dir with the
application's name.
</defun>

<defun title='browser-mapping' version="Resin 1.1">
<sum>Browser-specific configuration.</sum>  Used to deal with
broken browsers.

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td>regexp<td>Regular expression to match the User-Agent
<tr><td>force10<td>If set, force HTTP/1.0
</deftable>

<p/>No default browser-mappings are defined.
</defun>

<defun title='cache-mapping' version='Resin 1.1'>
<sum>Specifies <var/Expires/> times for cacheable pages.</sum>
Uncacheable pages, e.g. pages with sessions, are not affected.

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td><ct:anchor/url-pattern/><td>A pattern matching the url:
<var//foo/*/>, <var//foo/>, or <var/*.foo/>
<tr><td>url-regexp<td>A regular expression matching the url
<tr><td>expires<td>A time interval.
</deftable>

The time interval defaults to seconds, but will allow other
periods:
<deftable>
<tr><th>Suffix<th>Meaning
<tr><td>s<td>seconds
<tr><td>m<td>minutes
<tr><td>h<td>hours
<tr><td>d<td>days
</deftable>

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

<p/>There is no default value.
</defun>

<defun title="chain-mapping" index='chain-mapping' version="Resin 1.2.2">
<sum>Defines a Servlet filter to transform the output of another
servlet based on mime-type.</sum>  By default, the content type
<var/x-application/xsl/> executes com.caucho.jsp.XslFilter.

<p/>For example, a servlet could call
<code/setContentType("x-application/xsl")/> to format its XML results
using XSL.

<deftable>
<tr><th>Attribute<th>Description
<tr><td>mime-type<td>The mime-type to match
<tr><td>servlet-name<td>The servlet name to execute
</deftable>

<example title='Filter XML by an XSL processor'>
&lt;chain-mapping mime-type='x-application/xsl'
                servlet-name='com.caucho.jsp.XslFilter'/&gt;
</example>

<p/><note>Versions before Resin 1.2.2 use <var/filter-mapping/> instead
of chain-mapping.  This has been changed to avoid conflicts with
the Servlet 2.3 spec</note>

<p/>By default, Resin maps the x-application/xsl to com.caucho.jsp.XslFilter.
</defun>

<defun name=classpath title='classpath' version="Resin 1.1">
<sum>Adds to the application-specific classpath.</sum>  The classpath
can also automatically compile java classes when the <var/source/>
attribute is specified.

<note>Each <var/classpath/> directive must only contain a single class
directory.  In other words, you need two <var/classpaths/> to
specify "foo.jar:bar.jar".</note>

<deftable>
<tr><th>Attribute<th>Description<th>Default
<tr><td>id<td>Single class directory or jar<td>required
<tr><td>library-dir<td>To be used as a jar directory like WEB-INF/lib<td>false
<tr><td>source<td>Optional java source directory<td>same as id
<tr><td>compile<td>Enable automatic compilation<td>true
<tr><td>encoding<td>When compiling, what character encoding to use<td>javac default
<tr><td>args<td>When compiling, additional args to javac<td>none
</deftable>

<p/>For example, to automatically compile classes in the
WEB-INF/classes directory

<example>
&lt;classpath id='WEB-INF/classes'
           source='WEB-INF/classes'
	   compile='true'/>
</example>

<p/>To compile classes into the WEB-INF/classes directory with the
source in a home work directory:
<example>
&lt;classpath id='WEB-INF/classes'
           source='/home/ferg/ws/src'/>
&lt;classpath id='/home/test/library/classes'/>
</example>

<p/>By default, WEB-INF/classes is compiled and WEB-INF/lib contains jars.
</defun>

<defun title='class-update-interval' version="Resin 1.1">
<sum>Interval in seconds between checking for servlet updates.</sum>
For development, this can be set to 0 or to a small number to pick up
new servlet versions quickly.  For deployment, class-update-interval
can be large to avoid the overhead of checking for updates.

<p/>The default value is 2 seconds.
</defun>

<defun title='character-encoding' version="Resin 1.1">
<sum>Specifies the default character encoding for form parameters.</sum>

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

  ...

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

<p/>The default value is ISO-8859-1.
</defun>

<defun title='config-update-interval' version="Resin 2.0">
<sum>Interval in seconds between checking for configuration updates.</sum>
For development, this can be set to 0 or to a small number to pick up
new configuration file versions quickly.
For deployment, config-update-interval can be large to avoid
the overhead of checking for updates.

<p/>The default value is the value of class-update-interval.
</defun>

<defun title='context-param' index='context-param' version="Servlet 2.2">
<sum>Initializes application variables.</sum>  <code/context-param/>
defines initial values for <a href='../javadoc/javax/servlet/ServletContext.html#getInitParameter(java.lang.String)'>application.getInitParameter("foo")</a>.

The full servlet 2.2 syntax is supported and allows a simple shortcut
<example>
&lt;web-app id='/'&gt;

&lt;context-param foo='bar'/&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;/web-app>
</example>
</defun>

<defun title='directory-servlet' version="Resin 1.2">
<sum>Specifies the servlet to use to display directories.</sum>  To
disable directory listing, set this to 'none'.

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

  &lt;directory-servlet>none&lt;/directory-servlet>

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

<p/>The default is com.caucho.server.http.DirectoryServlet.
</defun>

<defun title="ejb-ref" version="Servlet 2.2">
<sum>Instantiates a EJB client bean.</sum>  Normally, EJB clients
use <a href="#jndi-link">jndi-link</a> instead.  There are
<a href="ejb.xtp">EJB configuration</a> examples for some vendors.

<deftable>
<tr><th>Attribute><th>Meaning
<tr><td>ejb-ref-name<td>JNDI path attribute to store the bean
<tr><td>ejb-ref-type<td>EJB class type
<tr><td>ejb-ref-factory<td>Factory for creating an EJB client bean
(Resin 1.2)
<tr><td>init-param<td>Parameter for the factory (Resin 1.2)
</deftable>

</defun>

<defun title="env-entry" version="Servlet 2.2">
<sum>JNDI parameter configuration.</sum>  <var/env-entry/> binds JNDI
variables, similar to either
<a href="servlet-config.xtp#init-param">init-param</a> or
<a href="#context-param">context param</a>.  <var/env-entry/> is
useful for configuring non-servlet-aware classes, like EJBs.

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td>env-entry-name<td>JNDI path attribute to store the variable.  The path is relative to java:comp/env.
<tr><td>env-entry-type<td>Java type of the variable
<tr><td>env-entry-value<td>The variable value.
</deftable>

<example title="Example resin.conf fragment">
&lt;env-entry>
  &lt;env-entry-name>max-price&lt;/env-entry-name>
  &lt;env-entry-type>java.lang.Double&lt;/env-entry-type>
  &lt;env-entry-value>22.27&lt;/env-entry-type>
&lt;/env-entry>
</example>

<example title="Example test.jsp">
&lt;%@ page import="javax.naming.*" %>
&lt;%
Context env = (Context) new InitialContext().lookup("java:comp/env");

Double dValue = (Double) env.lookup("max-price");
double price = dValue.doubleValue();
%>
</example>
</defun>

<defun name=error-log title='error-log' index='error-log'>
<sum>Specifies the file for error logging.</sum>  See
the host <a href="http-config.xtp#error-log">error-log</a> for more details.

<p/>The default uses the containing host's error log.
</defun>

<defun title='error-page' index='error-page' version="Servlet 2.2">
<sum>A page to display if the current request fails.</sum>  The web
server plugins use a <a href='http-config.xtp#error-page'>special case</a>
of error-page to handle connection failures.

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

<example title='Catching File Not Found'>
&lt;web-app id='/'&gt;
    &lt;error-page error-code='404'
                location='/file_not_found.jsp'/>
&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'/>
&lt;/web-app>
</example>

<p/>The following is a special case for the mod_caucho or isapi_srun
plugin to redirect to another page if it can't connect to srun.
Unlike the other two forms, this must be in http-server web-app as
below.  It can't be in a specific web-app.

<example title="Special can't connect to srun">
&lt;caucho.com>
&lt;http-server>

&lt;error-page exception-type='connection'
              location='/missing_file.html'/>
	      
&lt;/http-server&gt;
&lt;/caucho.com&gt;
</example>

<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.
</defun>

<defun title='jdbc-store' version="Servlet 2.2">
<sum>Configure sessions to use a JDBC backing store</sum> The database must be
specified using the resource-ref configuration.  The database store
will automatically create a table to store the sessions.

<deftable>
<tr><td>data-source<td>data source name for the table
<tr><td>table-name<td>database table for the session data
<tr><td>blob-type<td>database type for a blob
<tr><td>timestamp-type<td>database type for a blob
<tr><td>session-timeout<td>cleanup time
</deftable>

<example title="Example configuration">
&lt;session-config>
  &lt;jdbc-store>
    &lt;data-source>jdbc/sessions&lt;/data-source>
  &lt;/jdbc-store>
&lt;/session-config>
</example>

<example title="Example table created by session">
CREATE TABLE session (
  id VARCHAR(64) NOT NULL,
  data BLOB,
  mod_time TIMESTAMP,
  PRIMARY KEY(id)
)
</example>

<p/>By default, Resin does not use JDBC persistent sessions.
</defun>

<defun title="jndi-link" version="Resin 1.2">
<sum>Links a foreign JNDI context to the Resin JNDI context.</sum>
For example, you can use <var/jndi-link/> to link in client EJBs from
a foreign EJB container.

<deftable>
<tr><th>Attribute<th>Description.
<tr><td>jndi-name<td>JNDI path attribute to bind the link
<tr><td>property-file<td>jndi.property to use to obtain the Context.
<tr><td>jndi-factory<td>Class name of an InitialContextFactory used to
create the bean.
<tr><td>init-param<td>Properties to be used to get the initial
context.
<tr><td>jndi-lookup<td>JNDI path for the foreign context.
</deftable>

<example title="Linking a WebLogic EJB client bean">
&lt;jndi-link>
  &lt;jndi-name>java:comp/env/ejb/traderHome&lt;/jndi-name>
  &lt;jndi-factory>weblogic.jndi.WLInitialContextFactory&lt;/jndi-factory>
  &lt;init-param java.naming.provider.url="t3://localhost:7001"/>
  &lt;jndi-lookup>statelessSession.TraderHome&lt;/jndi-lookup>
&lt;/jndi-link>
</example>

<p/>By default, Resin does not add any special JNDI links.
</defun>

<defun name=jsp title='jsp' version="Resin 1.1">
<sum>JSP configuration</sum>

<deftable>
<tr><th>attribute<th>meaning<th>default
<tr><td>precompile<td>use precompiled JSP classes if available.<td>true
<tr><td>session<td>If "false", disable sessions by default.<td>true
<tr><td>static-encoding<td>allow JSP to precompile character encoding.<td>true
<tr><td>auto-compile<td>if false, changes in .jsp will not
force auto-compile.<td>true
<tr><td>disable-init-log<td>if true, disables logging of the jsp init and destroy<td>false
<tr><td>recycle-tags<td>recycles tags following the JSP 1.2 (since Resin 2.0.2)<td>true
<tr><td>velocity<td>allows Velocity-style syntax (since Resin 2.0.3)<td>false
</deftable>

</defun>

<defun title=login-config version="Servlet 2.2">
<sum>Configures user authentication.</sum>  See
<a href='security.xtp'>auth config</a> for more details.

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td>auth-method<td>Authentication method
<tr><td>form-login-config<td>Configuration for form login
<tr><td>authenticator<td>Select authenticator class
<tr><td>security-constraint<td>Select the files to protect.
</deftable>

<p/>By default, Resin does not authenticate.
</defun>

<defun title='mime-mapping' index='mime-mapping' version="Servlet 2.2">
<sum>Maps url patterns to mime-types.</sum>

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td>extension<td>url extension
<tr><td>mime-type<td>the mime-type
</deftable>

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

&lt;mime-mapping extension='.foo'
              mime-type='text/html'/&gt;

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

<p/>Resin has a long list of default mime types in com.caucho.server.http.Application.
</defun>

<defun title='multipart-form' version="Resin 1.2">
<sum>Enables multipart-mime for forms and file uploads.</sum>  multipart-mime
is disabled by default.

<p/>For an uploaded file with a form name of <var/foo/>, the parameter
value contains the path name to a temporary file containing the uploaded
file.  <var/foo.filename/> contains the uploaded filename, and
<var/foo.content-type/> contains the content-type of the uploaded file.

<deftable>
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>enable<td>if set false, this disables multipart-form processing.<td>true
<tr><td>upload-max<td>maximum size of an upload request (in kb).<td>no limit
</deftable>

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 "caucho.multipart.form.error" request attribute. (Resin 2.0.2)

<p/>By default, multipart-form is disabled.
</defun>

<defun title="run-at" version="Resin 1.1">
<sum>Times to execute the servlet automatically.</sum>
The run-at value in the servlet configuration configures a servlet to be
run at certain times of the day.

<p/>The value of the run-at is a list of hours or minutes the servlet
should be run at.  To run the servlet at 3am and at 2:25pm, use:
<example title='Run test.Alarm at 3am and 2:25pm'>
&lt;servlet servlet-name='foo' servlet-class='test.Alarm'>
  &lt;run-at>3:00 14:25&lt;/run-at>
&lt;/servlet>
</example>

<p/>To run the servlet at 5 minutes past the hour and at 45 minutes past the
our use ":05 :45".

<p/>You can also assign a period to the run-at, instead of specifying
specific times.  This can be useful if the period is something short like
every 5 minutes:
<example title='Run test.Alarm every 5 minutes'>
&lt;servlet servlet-name='foo' servlet-class='test.Alarm'>
  &lt;run-at period='5m'/>
&lt;/servlet>
</example>
</defun>

<defun title="servlet-mapping" version="Servlet 2.2">
<sum>Maps url patterns to servlets.</sum>  <code/servlet-mapping/> has two
children, <ct:anchor/url-pattern/> and <code/servlet-name/>.
<ct:anchor/url-pattern/>
selects the urls which should execute the servlet.

<p/><code/servlet-name/> can either specify a servlet class directly or it
can specify a servlet alias defined by <code/servlet/>.

<p/>The special <code/servlet-name/> <em/invoker/> is used to dispatch
servlets by class name.  For example, /servlets/test.HelloServlet.

<deftable>
<tr><th>attribute<th>meaning<th>default
<tr><td><ct:anchor/url-pattern/><td>A pattern matching the url:
<var//foo/*/>, <var//foo/>, or <var/*.foo/><td>n/a
<tr><td>url-regexp<td>A regular expression matching the url<td>n/a
<tr><td>servlet-name<td>The servlet name (can use replacement vars
like <var/$1/>)<td>n/a
<tr><td>path-info<td>Path info rewriting string (can use replacement
vars like <var/$1/>)<td>The standard path-info
<tr><td>servlet-class<td>The servlet's class<td>uses servlet-name
<tr><td>init-param<td>Initialization parameters<td>n/a
<tr><td>load-on-startup<td>Initializes the servlet when the server starts.<td>none
<tr><td>run-at<td>Times to execute the servlet automatically<td>none
<tr><td>case-sensitive<td>If true, the match is case-sensitive<td>true on Unix and false on Windows
</deftable>

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

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

&lt;servlet-mapping url-pattern='/hello.html'
                 servlet-name='hello'/&gt;

&lt;servlet-mapping url-pattern='/servlet/*'
                 servlet-name='invoker'/&gt;

&lt;servlet-mapping url-pattern='*.xtp'
                 servlet-name='com.caucho.jsp.XtpServlet'/&gt;

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

<p/>The plugins use servlet-mapping to decide which URLs to send to Resin.
The following servlet-name value are special:

<deftable>
<tr><td>plugin_match<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)
<tr><td>plugin_ignore<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)
</deftable>

</defun>

<defun name=servlet title='servlet' index="servlet" version="Servlet 2.2">
<sum>Defines a servlet alias for later mapping.</sum>  More details are in the
<a href='servlet-config.xtp'>servlet configuration</a> section.

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td>servlet-name<td>The servlet's name (alias)
<tr><td>servlet-class<td>The servlet's class (defaults to servlet-name)
<tr><td>init-param<td>Initialization parameters
<tr><td>load-on-startup<td>Initializes the servlet when the server starts.
<tr><td>run-at<td>Times to execute the servlet automatically (Resin 1.1)
</deftable>

The following example defines a servlet alias 'hello'
<example>
&lt;web-app id='/'&gt;

&lt;servlet-mapping url-pattern='/hello.html'
                 servlet-name='hello'/&gt;

&lt;servlet servlet-name='hello'
         servlet-class='test.HelloWorld'&gt;
  &lt;init-param title='Hello, World'/&gt;
&lt;/servlet&gt;

&lt;servlet servlet-name='cron'
         servlet-class='test.DailyChores'&gt;
  &lt;run-at&gt;3:00&lt;/run-at&gt;
&lt;/servlet&gt;

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

<defun title='session-config' version="Servlet 2.2">
<sum>Contains session configuration parameters</sum>

<deftable>
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>session-timeout<td>The session timeout in minutes<td>30 minutes
<tr><td>session-max<td>Maximum active sessions<td>4096
<tr><td>enable-cookies<td>Enable cookies for sessions (resin 1.1)<td>true
<tr><td>enable-url-rewriting<td>Enable URL rewriting for sessions (resin 1.1)<td>true
<tr><td>cookie-version<td>Version of the cookie spec for sessions (resin 1.2)<td>1.0
<tr><td>cookie-domain<td>Domain for session cookies (resin 1.2)<td>none
<tr><td>cookie-max-age<td>Max age for persisten session cookies (resin 2.0)<td>none
<tr><td>file-store<td>Persistent sessions using a file store (resin 1.2)<td>none
<tr><td>jdbc-store<td>Persistent sessions using a JDBC store (resin 1.2)<td>none
<tr><td>tcp-store<td>Persistent sessions using a distributed ring (resin 1.2)<td>none
<tr><td>always-load-session<td>Reload data from the store on every request (resin 1.2)<td>false
<tr><td>always-save-session<td>Save session data to the store on every request (resin 1.2)<td>false
<tr><td>save-on-shutdown<td>Only save session when the application shuts down. (resin 1.2.3)<td>false
<tr><td>reuse-session-id<td>Reuse the session id even if the session has timed out. (resin 2.0.4)<td>true
</deftable>

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

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

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

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

<defun title='session-timeout' version="Servlet 2.2">
<sum>Sets the session timeout in minutes.</sum>  Sessions idle for
longer than <code/session-timeout/> are purged.

<p/><code/session-timeout/> must be contained in a
<code/session-config/> tag.

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

  &lt;session-config session-timeout='120'/&gt;

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

<p/>Defaults to 30 minutes.
</defun>

<defun title='session-max' version="Servlet 2.2">
<sum>Sets the maximum number of active sessions.</sum>  Sessions are
stored in an LRU cache.  When the cache fills, the oldest sessions are
recovered.

<p/><code/session-max/> must be contained in a
<code/session-config/> tag.

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

  &lt;session-config&gt;
     &lt;session-timeout id=120/&gt;
     &lt;session-max id=4096/&gt;
  &lt;/session-config&gt;

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

<p/>Defaults to 4096.
</defun>

<defun name=taglib title='taglib' version="Servlet 2.2">
<sum>Configures a JSP 1.1 tag library.</sum>  See the <a
href='taglib.xtp'>tlb</a> configuration for details.

<deftable>
<tr><th>Attribute<th>Description
<tr><td>taglib-uri<td>Matching uri for the tag library
<tr><td>taglib-location<td>Location for the tab library definition file.
</deftable>

<p/>The location is relative to the class path. In the following example,
MyTag.tlb should be in WEB-INF/classes/MyTag.tlb.

<example>
&lt;taglib taglib-uri='/mytag/test'
        taglib-location='/MyTag.tlb'/>
</example>

<p/>The JSP file will use the tag library as follows:
<example>
&lt;%@ taglib prefix='x' uri='/mytag/test' %>
&lt;x:mytag/>
</example>

<p/>By default, looks up all WEB-INF/*.tld and META-INF/*.tld.
</defun>

<defun title='tcp-store' version="Servlet 2.2">
<sum>Configure sessions to use a TCP-ring backing store.</sum> All the
&lt;srun> servers are arranged in a ring based on their order in the
resin.conf.  The <var/tcp-store/> will store the session based on that
ring order.

<example title="Example Symmetrical configuration">
&lt;http-server>
  &lt;http id='a' port='80'/>
  &lt;srun id='a' host='host-a' port='6802'/>

  &lt;http id='b' port='80'/>
  &lt;srun id='b' host='host-b' port='6802'/>

  &lt;host id=''>
  &lt;web-app id=''>

  &lt;session-config>
    &lt;tcp-store/>
    &lt;always-load-session/>
  &lt;/session-config>

  &lt;/web-app>
  &lt;/host>
&lt;/http-server>
</example>

The above example assumes the two hosts use an external load-balancer, like
a router load-balancer.

<p/>See <a href="sessions.xtp">distributed sessions</a> for more details.

<p/>Disabled by default.
</defun>

<defun name=temp-dir title='temp-dir' version="Resin 1.1">
<sum>Application temp directory</sum>  This is the path used in
<var/javax.servlet.context.tempdir/>.

<p/>Defaults to <var/WEB-INF/tmp/>.
</defun>

<defun title='url-pattern' index='url-pattern' version="Servlet 2.2">
<sum>Matches a set of URLs for servlet-mapping.</sum>

<deftable>
<tr><th width='25%'>Pattern<th>Description
<tr><td>/foo/bar.html<td>Matches exactly the /foo/bar.html URL.
<tr><td>/foo/*<td>Matches /foo and any children
<tr><td>*.foo<td>Matches any URL with a .foo extension
<tr><td>/<td>Replaces the default servlet.
</deftable>

<p/><var///> defines a default handler and <var//*/> defines a prefix handler.
<var//*/> will override extension handlers like <var/*.foo/>. <var///>
will only be used if no other pattern matches.

<p/>No default.  Either url-pattern or url-regexp is required.
</defun>

<defun title="resource-ref" version="Servlet 2.2">
<sum>Database pooling configuration.</sum>  <var/resource-ref/> puts
the DataSource in a JNDI context and also in the ServletContext.
Each web-app can configure its own database pool.  Resin can also
share a common pool by putting the resource-ref outside the http-server.

<p/>More details are in the <a href='db-config.xtp'>database config</a>
page.

<p/>The driver can be in WEB-INF/lib or WEB-INF/classes, although it's
a better idea to put it in the global classpath or resin-2.0.x/lib.

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td>res-ref-name<td>JNDI path attribute to store the pool.  The path is relative to java:comp/env.
<tr><td>res-type<td>javax.sql.DataSource or javax.sql.XADataSource for database pools
<tr><td>init-param<td>initialization parameters (Resin 1.2)
<tr><td>init-class<td>Class containing init params (Map or Hashtable) (Resin 1.2.4)
<tr><td>bean-name<td>optional bean class to be used as a resource (Resin 1.2)
</deftable>

<p/><var/init-param/> sets bean properties of the data source.
You can look at the com.caucho.sql.DBPool JavaDoc for its interface.
Unknown parameters are used to set the driver properties.  So you can
set any driver-specific property in the init-param.

<deftable title="DBPool Init Parameters">
<tr><th>Attribute<th>Meaning<th>Default
<tr><td>driver-name<td>JDBC driver class<td>required
<tr><td>url<td>JDBC url for the database<td>required
<tr><td>user<td>Database user<td>""
<tr><td>password<td>Database password<td>""
<tr><td>max-connections<td>Maximum number of allowed connections<td>20
<tr><td>max-idle-time<td>Maximum time an idle connection is kept in
the pool<td>30 sec
<tr><td>connection-wait-time<td>How long to wait for an idle connection (Resin 1.2.3)<td>10 minutes
<tr><td>max-overflow-connections<td>How many "overflow" connection are allowed if the connection wait times out.<td>0
<tr><td>ping-table<td>The database table used to "ping", checking that
the connection is still live.<td>false
<tr><td>ping-on-reuse<td>Test for live connections before allocating
them from the pool.<td>false
<tr><td>ping-on-free<td>Test for live connections before replacing
them in the pool.<td>false
<tr><td>ping-on-idle<td>Periodically test connections in the pool<td>false
<tr><td><var/any other/><td>calls DBPool.setProperty() to set driver properties.<td>none
</deftable>

<p/>Here's a sample minimal resin.conf fragment to bind a DBPool-based
database to the JNDI path "java:comp/env/jdbc/test".

<example title="Sample resin.conf fragment">
&lt;resource-ref>
  &lt;res-ref-name>jdbc/test&lt;/res-ref-name>
  &lt;res-type>javax.sql.DataSource&lt;/res-type>
  &lt;init-param driver-name="org.gjt.mm.mysql.Driver"/>
  &lt;init-param url="jdbc:mysql://localhost:3306/test"/>
&lt;/resource-ref>
</example>

<p/>The following is a sample design pattern for getting new database
connections.  The <var/try ... finally/> block is very important for
making database connections reliable.

<example title="Sample test.jsp to use database connections">
&lt;%@ page import='javax.sql.*, javax.naming.*, java.sql.*' %>
&lt;%
Context env = (Context) new InitialContext().lookup("java:comp/env");

DataSource source = (DataSource) env.lookup("jdbc/test");
Connection conn = source.getConnection();
try {
  ...
} finally {
  conn.close();
}
%>
</example>

</defun>

<defun title='path-mapping' version="Servlet 2.2">
<sum>Maps url patterns to real paths.</sum>  If using a server like
IIS, you may need to match the server's path aliases.

<deftable>
<tr><th>Attribute<th>Meaning
<tr><td><ct:anchor/url-pattern/><td>A pattern matching the url:
<var//foo/*/>, <var//foo/>, or <var/*.foo/>
<tr><td>url-regexp<td>A regular expression matching the url
<tr><td>real-path<td>The prefix of the real path.  When used with url-regexp, allows substitution variables like <var/$1/>.
</deftable>

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

<p/>No default.
</defun>

<defun title='stderr-log' version="Resin 2.0.2">
<sum>Configures the location for System.err for the current web-app.</sum>
The stdout-log may be put in the &lt;host> or &lt;http-server> context
to apply to all web-apps within that context.

<example>
&lt;web-app>
  &lt;stdout-log href='$app-dir/WEB-INF/logs/stdout.log'/>
  ...
&lt;/web-app>
</example>

<deftable>
<tr><th>attribute<th>meaning
<tr><td>href<td>The location of the file.  Path variables may be used.
<tr><td>rollover-period<td>How often the log should be rotated.
<tr><td>rollover-size<td>The maximum size of the log before rotation.
<tr><td>timestamp<td>Timestamp before each line (Resin 2.0.3)
</deftable>

</defun>

<defun title='stdout-log' version="Resin 2.0.2">
<sum>Configures the location for System.out for the current web-app.</sum>
The stdout-log may be put in the &lt;host> or &lt;http-server> context
to apply to all web-apps within that context.

<example>
&lt;web-app>
  &lt;stdout-log href='$app-dir/WEB-INF/logs/stdout.log'/>
  ...
&lt;/web-app>
</example>

<deftable>
<tr><th>attribute<th>meaning
<tr><td>href<td>The location of the file.  Path variables may be used.
<tr><td>rollover-period<td>How often the log should be rotated.
<tr><td>rollover-size<td>The maximum size of the log before rotation.
<tr><td>timestamp<td>Timestamp before each line (Resin 2.0.3)
</deftable>

</defun>

<defun title='strict-mapping' version="Resin 1.2">
<sum>Forces servlet-mapping to follow strict Servlet 2.2, disallowing
PATH_INFO</sum>

<p/>Defaults to false, allowing /foo/bar.jsp/foo.
</defun>

<defun title="welcome-file-list" version="Servlet 2.2">
<sum>Sets the files to use as index.jsp pages</sum>

<example>
&lt;web-app id='/'>
  &lt;welcome-file-list>index.jsp, home.xtp&lt;/welcome-file-list>
&lt;/web-app>
</example>

<p/>Defaults to index.xtp, index.jsp, index.html.
</defun>

<defun title='web-xml' version="Resin 2.0">
<sum>Lets applications specify the web.xml file.</sum>

<p/>Defaults to web.xml
</defun>

<defun title='work-dir' version="Resin 2.0.0">
<sum>Application work directory</sum>.  This is the directory used for
generated code like JSP, XSL and EJB classes.

<p/>Defaults to <var/WEB-INF/work/>.
</defun>

</section>
