By default, uses the host access-log.

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.

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

No default browser-mappings are defined.

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.

The default value is 2 seconds.

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

The default value is ISO-8859-1.

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.

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.

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

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

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

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(); %>

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)

The default uses the containing host's error log.

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.

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.

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

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.

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.

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.

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.

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)

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>

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>

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.

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.

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.

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

See distributed sessions for more details.

Disabled by default.

Defaults to WEB-INF/tmp.

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.

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(); } %>

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.

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

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

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