Specifies the access logging. See the host access-log for more details.

By default, uses the host access-log.

Allows administration from the web-app. allow-admin must be specified in the resin.conf for security. In other words, a .war file can't enable admin in its web.xml.

Default: false

Allows JSP EL expressions in <init-param> for servlets, filters, and the <context-param>.

<servlet> <servlet-name>hello</servlet-name> <init-param greeting="Hello, ${host.url}"/> </servlet>

Specifies the directory of the application. If unspecified, the application will have the same path as the id. When the web-app is specified with a url-regexp, app-dir can use replacement variables ($2).

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

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

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

<host id=''> <web-app id='/apache' app-dir='/usr/local/apache/htdocs'> ... </host>

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.

<caucho.com> <http-server app-dir='c:\inetpub\wwwroot'> ... </http-server> </caucho.com>

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

<host id=''> <web-app url-regexp='/~([^/]*)' app-dir='/home/$1/public_html'> ... </web-app> </host>

By default, uses the subdiretory under the host app-dir with the application's name.

Browser-specific configuration. Used to deal with broken browsers.

Attribute	Meaning
regexp	Regular expression to match the User-Agent
force10	If set, force HTTP/1.0

No default browser-mappings are defined.

Specifies Expires times for cacheable pages. Uncacheable pages, e.g. pages with sessions, are not affected.

Attribute	Meaning
url-pattern	A pattern matching the url: /foo/*, /foo, or *.foo
url-regexp	A regular expression matching the url
expires	A time interval.

The time interval defaults to seconds, but will allow other periods:

Suffix	Meaning
s	seconds
m	minutes
h	hours
d	days

<web-app id='/'> <cache-mapping url-pattern='/*' expires='10'/> <cache-mapping url-pattern='*.gif' expires='15m'/> </web-app>

There is no default value.

Specifies whether servlet-mapping and filter-mapping is treated as case-sensitive or case-insensitive.

Default: false on Windows, true on Unix.

Defines a Servlet filter to transform the output of another servlet based on mime-type. By default, the content type x-application/xsl executes com.caucho.jsp.XslFilter.

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

Attribute	Description
mime-type	The mime-type to match
servlet-name	The servlet name to execute

Filter XML by an XSL processor

<chain-mapping mime-type='x-application/xsl' servlet-name='com.caucho.jsp.XslFilter'/>

Note: Versions before Resin 1.2.2 use filter-mapping instead of chain-mapping. This has been changed to avoid conflicts with the Servlet 2.3 spec

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

Adds to the application-specific classpath. The classpath can also automatically compile java classes when the source attribute is specified.

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

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

For example, to automatically compile classes in the WEB-INF/classes directory:

<classpath id='WEB-INF/classes'
           source='WEB-INF/classes'
	   compile='true'/>

To compile classes into the WEB-INF/classes directory with the source in a home work directory:

<classpath id='WEB-INF/classes' source='/home/ferg/ws/src'/> <classpath id='/home/test/library/classes'/>

By default, WEB-INF/classes is compiled and WEB-INF/lib contains jars.

Interval in seconds between checking for servlet updates. 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.

The default value is 2 seconds.

Specifies the default character encoding for form parameters.

<web-app id='/' character-encoding='shift_jis'> ... </web-app>

The default value is ISO-8859-1.

Interval in seconds between checking for configuration updates. 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.

The default value is the value of class-update-interval.

Initializes application variables. context-param defines initial values for application.getInitParameter("foo").

The full servlet 2.2 syntax is supported and allows a simple shortcut

<web-app id='/'> <context-param foo='bar'/> <context-param> <param-name>baz</param-name> <param-value>value</param-value> </context-param> </web-app>

Specifies the maximum length for the session's generated cookie. Only special situations like WAP devices should use this option. Reducing this value reduces the randomness in the cookie and increases the chance of session collisions.

Defaults to generate the maximum length of the cookie (64 random bits = 12 characters.)

Specifies the servlet to use to display directories. To disable directory listing, set this to 'none'.

<web-app id='/'> <directory-servlet>none</directory-servlet> </web-app>

The default is com.caucho.server.http.DirectoryServlet.

Instantiates a EJB client bean. Normally, EJB clients use jndi-link instead. There are EJB configuration examples for some vendors.

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

JNDI parameter configuration. env-entry binds JNDI variables, similar to either: init-param or context param. env-entry is useful for configuring non-servlet-aware classes, like EJBs.

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

Example resin.conf fragment

<env-entry> <env-entry-name>max-price</env-entry-name> <env-entry-type>java.lang.Double</env-entry-type> <env-entry-value>22.27</env-entry-value> </env-entry>

Example test.jsp

<%@ page import="javax.naming.*" %> <% Context env = (Context) new InitialContext().lookup("java:comp/env"); Double dValue = (Double) env.lookup("max-price"); double price = dValue.doubleValue(); %>

Specifies the file for error logging. See the host error-log for more details.

The default uses the containing host's error log.

A page to display if the current request fails. The web server plugins use a special case of error-page to handle connection failures.

Attribute	Description
location	The error page to display
exception-type	Select the error page based on a Java exception
error-code	Select the error page based on an HTTP status code

Catching File Not Found

<web-app id='/'> <error-page error-code='404' location='/file_not_found.jsp'/> </web-app>

Catching Exceptions

<web-app id='/foo'> <error-page exception-type='java.lang.NullPointerException' location='/nullpointer.jsp'/> </web-app>

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.

<caucho.com>
<http-server>

<error-page exception-type='connection'
              location='/missing_file.html'/>
	      
</http-server>
</caucho.com>

By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages.

If true, listeners are called before the session is invalidated. According to the Servlet spec, the session is invalidated before listeners are called. This means the listeners can't call getAttribute methods. For many applications, the spec behavior is not useful.

Default: false

Configure sessions to use a JDBC backing store. The database must be specified using the resource-ref configuration. The database store will automatically create a table to store the sessions.

data-source	data source name for the table
table-name	database table for the session data
blob-type	database type for a blob
timestamp-type	database type for a blob
session-timeout	cleanup time

Example configuration

<session-config> <jdbc-store> <data-source>jdbc/sessions</data-source> </jdbc-store> </session-config>

Example table created by session

CREATE TABLE session ( id VARCHAR(64) NOT NULL, data BLOB, mod_time TIMESTAMP, PRIMARY KEY(id) )

By default, Resin does not use JDBC persistent sessions.

Links a foreign JNDI context to the Resin JNDI context. For example, you can use jndi-link to link in client EJBs from a foreign EJB container.

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

Linking a WebLogic EJB client bean

<jndi-link> <jndi-name>java:comp/env/ejb/traderHome</jndi-name> <jndi-factory>weblogic.jndi.WLInitialContextFactory</jndi-factory> <init-param java.naming.provider.url="t3://localhost:7001"/> <jndi-lookup>statelessSession.TraderHome</jndi-lookup> </jndi-link>

By default, Resin does not add any special JNDI links.

JSP configuration.

attribute	meaning	default
auto-compile	if false, changes in .jsp will not
disable-init-log	if true, disables logging of the jsp init and destroy	false
jsp-update-interval	How often JSP files should be checked for changes (since Resin 2.1.1)	class-update-interval
jsp-max	limit the number of active JSP pages	1024
precompile	use precompiled JSP classes if available.	true
require-source	check to see if the *.jsp file has been deleted	false
recompile-on-error	If the JSP page throws a java.lang.Error, recompile it. (since Resin 1.2.3)	false
recycle-tags	recycles tags following the JSP 1.2 (since Resin 2.0.2)	true
session	If "false", disable sessions by default.	true
static-encoding	allow JSP to precompile character encoding.	true force auto-compile.	true
velocity	allows Velocity-style syntax (since Resin 2.0.3)	false

Marks the web-app as lazily initialized. Normally, web-apps are loaded when Resin starts and the load-on-init servlets are run. With lazy-init, the web-app will only be started on the first request.

Configures user authentication. See auth config for more details.

Attribute	Meaning
auth-method	Authentication method
form-login-config	Configuration for form login
authenticator	Select authenticator class
security-constraint	Select the files to protect.

By default, Resin does not authenticate.

Maps url patterns to mime-types.

Attribute	Meaning
extension	url extension
mime-type	the mime-type

<web-app id='/'> <mime-mapping extension='.foo' mime-type='text/html'/> </web-app>

Resin has a long list of default mime types in com.caucho.server.http.Application.

Enables multipart-mime for forms and file uploads. multipart-mime is disabled by default.

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

Attribute	Meaning	Default
enable	if set false, this disables multipart-form processing.	true
upload-max	maximum size of an upload request (default in kb).	no limit

units	bytes
128	128 bytes
128b	128 bytes
128k	128 kilobytes
128m	128 megabytes
128g	128 gigabytes

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)

By default, multipart-form is disabled.

Times to execute the servlet automatically. The run-at value in the servlet configuration configures a servlet to be run at certain times of the day.

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:

<servlet servlet-name='foo' servlet-class='test.Alarm'>
  <run-at>3:00 14:25</run-at>
</servlet>

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

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:

<servlet servlet-name='foo' servlet-class='test.Alarm'>
  <run-at period='5m'/>
</servlet>

Maps url patterns to servlets. servlet-mapping has two children, url-pattern and servlet-name. url-pattern selects the urls which should execute the servlet.

servlet-name can either specify a servlet class directly or it can specify a servlet alias defined by servlet.

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

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

<caucho.com> <web-app id='/'> <servlet servlet-name='hello' servlet-class='test.HelloWorld'/> <servlet-mapping url-pattern='/hello.html' servlet-name='hello'/> <servlet-mapping url-pattern='/servlet/*' servlet-name='invoker'/> <servlet-mapping url-pattern='*.xtp' servlet-name='com.caucho.jsp.XtpServlet'/> </web-app>

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

plugin_match	The plugin will send the request to Resin, but Resin will ignore the entry. Use to get around regexp limitations. (Resin 1.2.2)
plugin_ignore	The plugin will ignore the request. Use this to define a sub-url the web server should handle, not Resin. (Resin 1.2.2)

Defines a servlet alias for later mapping. More details are in the servlet configuration section.

Attribute	Meaning
servlet-name	The servlet's name (alias)
servlet-class	The servlet's class (defaults to servlet-name)
init-param	Initialization parameters
load-on-startup	Initializes the servlet when the server starts.
run-at	Times to execute the servlet automatically (Resin 1.1)
init	Allows bean-style configuration. See the servlet page (Resin 2.1.3).

The following example defines a servlet alias 'hello'

<web-app id='/'> <servlet-mapping url-pattern='/hello.html' servlet-name='hello'/> <servlet servlet-name='hello' servlet-class='test.HelloWorld'> <init-param title='Hello, World'/> </servlet> <servlet servlet-name='cron' servlet-class='test.DailyChores'> <run-at>3:00</run-at> </servlet> </web-app>

Contains session configuration parameters.

Attribute	Meaning	Default
session-timeout	The session timeout in minutes	30 minutes
session-max	Maximum active sessions	4096
enable-cookies	Enable cookies for sessions (resin 1.1)	true
enable-url-rewriting	Enable URL rewriting for sessions (resin 1.1)	true
cookie-version	Version of the cookie spec for sessions (resin 1.2)	1.0
cookie-domain	Domain for session cookies (resin 1.2)	none
cookie-max-age	Max age for persistent session cookies (resin 2.0)	none
cookie-length	Maximum length of the cookie. (resin 2.1.1)	Integer.MAX_VALUE
file-store	Persistent sessions using a file store (resin 1.2)	none
jdbc-store	Persistent sessions using a JDBC store (resin 1.2)	none
tcp-store	Persistent sessions using a distributed ring (resin 1.2)	none
always-load-session	Reload data from the store on every request (resin 1.2)	false
always-save-session	Save session data to the store on every request (resin 1.2)	false
save-on-shutdown	Only save session when the application shuts down. (resin 1.2.3)	false
reuse-session-id	Reuse the session id even if the session has timed out. (resin 2.0.4)	true
ignore-serialization-errors	When persisting a session, ignore any values which don't implement java.io.Serializable	false
invalidate-after-listener	Call listeners before the session is invalid	false

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

<web-app id='/'> <session-config enable-cookies='false' enable-url-rewriting='true'/> </web-app>

Sets the session timeout in minutes. Sessions idle for longer than session-timeout are purged.

session-timeout must be contained in a session-config tag.

<web-app id='/dir'> <session-config session-timeout='120'/> </web-app>

Defaults to 30 minutes.

Sets the maximum number of active sessions. Sessions are stored in an LRU cache. When the cache fills, the oldest sessions are recovered.

session-max must be contained in a session-config tag.

<web-app id='/dir'> <session-config> <session-timeout id=120/> <session-max id=4096/> </session-config> </web-app>

Defaults to 4096.

Configures a JSP 1.1 tag library. See the tlb configuration for details.

Attribute	Description
taglib-uri	Matching uri for the tag library
taglib-location	Location for the tab library definition file.

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

<taglib taglib-uri='/mytag/test' taglib-location='/MyTag.tld'/>

The JSP file will use the tag library as follows:

<%@ taglib prefix='x' uri='/mytag/test' %> <x:mytag/>

By default, looks up all WEB-INF/*.tld and META-INF/*.tld.

Configure sessions to use a TCP-ring backing store. All the <srun> servers are arranged in a ring based on their order in the resin.conf. The tcp-store will store the session based on that ring order.

<http-server>
  <http id='a' port='80'/>
  <srun id='a' host='host-a' port='6802'/>

  <http id='b' port='80'/>
  <srun id='b' host='host-b' port='6802'/>

  <host id=''>
  <web-app id=''>

  <session-config>
    <tcp-store/>
    <always-load-session/>
  </session-config>

  </web-app>
  </host>
</http-server>

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

See distributed sessions for more details.

Disabled by default.

Application temp directory. This is the path used in javax.servlet.context.tempdir.

Default: Defaults to WEB-INF/tmp.

Matches a set of URLs for servlet-mapping.

Pattern	Description
/foo/bar.html	Matches exactly the /foo/bar.html URL.
/foo/*	Matches /foo and any children
*.foo	Matches any URL with a .foo extension
/	Replaces the default servlet.

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

No default. Either url-pattern or url-regexp is required.

Database pooling configuration. 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.

More details are in the database config page.

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.

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

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.

DBPool Init Parameters

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

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

<resource-ref>
  <res-ref-name>jdbc/test</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
  <init-param driver-name="org.gjt.mm.mysql.Driver"/>
  <init-param url="jdbc:mysql://localhost:3306/test"/>
</resource-ref>

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

<%@ page import='javax.sql.*, javax.naming.*, java.sql.*' %>
<%
Context env = (Context) new InitialContext().lookup("java:comp/env");

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

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

Attribute	Meaning
url-pattern	A pattern matching the url: /foo/*, /foo, or *.foo
url-regexp	A regular expression matching the url
real-path	The prefix of the real path. When used with url-regexp, allows substitution variables like $1.

<web-app id='/'> <path-mapping url-pattern='/resin/*' real-path='e:\resin'/> <path-mapping url-regexp='/~([^/]*)' real-path='e:\home\$1'/> </web-app>

Requires that the web-app be only accessed from a secure connection, e.g. SSL.

Configures the location for System.err for the current web-app. The stdout-log may be put in the <host> or <http-server> context to apply to all web-apps within that context.

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

attribute	meaning
href	The location of the file. Path variables may be used.
rollover-period	How often the log should be rotated.
rollover-size	The maximum size of the log before rotation.
timestamp	Timestamp before each line (Resin 2.0.3)
encoding	Character encoding

Configures the location for System.out for the current web-app. The stdout-log may be put in the <host> or <http-server> context to apply to all web-apps within that context.

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

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

Forces servlet-mapping to follow strict Servlet 2.2, disallowing PATH_INFO.

Default: Defaults to false, allowing /foo/bar.jsp/foo.

Sets the files to use as index.jsp pages. According to the spec, each file is in a <welcome-file> element.

<web-app id='/'> <welcome-file-list> <welcome-file>index.jsp<welcome-file> <welcome-file>index.xtp<welcome-file> <welcome-file>home.xtp<welcome-file> </welcome-file-list> </web-app>

Resin also provides a shortcut where you can just list the files:

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

Default: Defaults to index.xtp, index.jsp, index.html.

Lets applications specify the web.xml file.

Default: Defaults to web.xml.

Application work directory. This is the directory used for generated code like JSP, XSL and EJB classes.

Default: Defaults to WEB-INF/work.