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

By default, uses the host access-log.

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.

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.

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.

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.

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

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
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-type> </env-entry>

Example test.jsp

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

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)

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

Special can't connect to srun

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

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.

JSP configuration

attribute	meaning	default
precompile	use precompiled JSP classes if available.	true
session	If "false", disable sessions by default.	true
static-encoding	allow JSP to precompile character encoding.	true
auto-compile	if false, changes in .jsp will not force auto-compile.	true

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.

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.

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.	no limit

If the upload is larger than the limit or if multipart-form processing is disabled, Resin will not parse the request.

By default, multipart-form is disabled.

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)

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 (resin 1.2)	1.0
cookie-domain	Domain for session cookies (resin 1.2)	none
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

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.tlb should be in WEB-INF/classes/MyTag.tlb.

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

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.

Example Symmetrical configuration

<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. Any request can come to either host-a or host-b, requiring always-load-session.

See distributed sessions for more details.

Disabled by default.

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

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.

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 resin1.2/lib.

Attribute	Meaning
res-ref-name	JNDI path attribute to store the pool
res-type	javax.sql.DataSource for database pools
init-param	initialization parameters (Resin 1.2)
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	5 sec
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 connectiong in the pool	false
connection-wait-time	How long to wait for an idle connection (Resin 1.2.3)	5 seconds
enable-transaction	Connections from this pool can participate in a transaction. Enabling transactions adds overhead, so non-transaction applications should not set this.	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".

Sample resin.conf fragment

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

Sample test.jsp to use database connections

<%@ page import='javax.sql.*, javax.naming.*, java.sql.*' %> <% Context env = 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>

No default.

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

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

Sets the files to use as index.jsp pages

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

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