Caucho Technology

web application: tags

Web applications are configured with the <web-app> tag, which can occur in a number of places.

  • WEB-INF/web.xml contains a top-level web-app element. It is the Servlet standard location for defining things like servlet mappings and security roles.
  • WEB-INF/resin-web.xml is also used by Resin and will override and supplement the configuration in WEB-INF/web.xml. Use it to specify Resin specific configuration if you prefer to keep WEB-INF/web.xml strictly conforming to the Servlet specification.
  • A web application can also be configured in the main Resin configuration, and in this context web-app is a child of <host>.


<access-log> configures the access log file.

As a child ofweb-app, overrides the definition in thehostthat the web-app is deployed in. As a child ofhost, overrides the definition in theserverthat the host is in.

The default archive format is

path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

The access log formatting variables follow the Apache variables:

format patterns
%bresult content length
%Dtime taken to complete the request in microseconds (since 3.0.16)
%hremote IP addr
%{xxx}irequest header xxx
%{xxx}oresponse header xxx
%{xxx}ccookie value xxx
%nrequest attribute
%rrequest URL
%sstatus code
%Srequested session id
%{xxx}trequest date with optional time format string.
%Ttime taken to complete the request in seconds
%uremote user
%Urequest URI
%vname of the virtual host serving the request

The default format is:

default access log format
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

resin:typeallows for custom logging. Applications can extend a custom class fromcom.caucho.http.log.AccessLog.Resin-IoC initializationcan be used to set bean parameters in the custom class.

<access-log> Attributes
pathOutput path for the log entries, see "Log Paths".required
path-formatSelects a format for generating path names. The syntax is the same as for archive-format.optional
archive-formatthe format for the archive filename when a rollover occurs, see Rollovers. see below
auto-flushtrue to flush the memory buffer with each request. false
auto-flush-timesets time interval for flushing the memory buffers 60s
excludeaccess logging exclude patterns for request URIs. Access to matching URIs does not get logged.none
formatAccess log format.see above
hostname-dns-lookuplog the dns name instead of the IP address (has a performance hit).false
rollover-periodhow often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See "Rollovers". none
rollover-sizemaximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See "Rollovers". 1mb
rollover-countmaximum number of rollover files before the oldest ones get overwritten. See "Rollovers". 1mb
resin:typea class extending com.caucho.server.log.AccessLog for custom logging com.caucho.server.log.AccessLog
initResin-IoC initialization for the custom classn/a
<access-log> schema
element access-log {
  & path-format?
  & archive-format?
  & auto-flush-time?
  & exclude*
  & format?
  & hostname-dns-lookup?
  & rollover-period?
  & rollover-size?
  & rollover-count?
  & resin:type?
  & init?
Example: <access-log> in host configuration
<resin xmlns="">
<cluster id="app-tier">

  <host id="">
    <access-log path='log/access.log'>
Example: custom access log
<resin xmlns="">

<cluster id="app-tier">

  <host id=''>

      <test:MyLog xmlns:test="urn:java:test">



child of web-app

<active-wait-time> sets a 503 busy timeout for requests trying to access a restarting web-app. If the timeout expires before the web-app complete initialization, the request will return a 503 Busy HTTP response.

<active-wait-time> schema
element active-wait-time {


child of web-app

The <allow-forward-after-flush> flag configures whether IllegalStateExcdeption is thrown when using forward() method after response has been committed. Flag configures behavior of servlet and jsp.

<allow-forward-after-flush> schema
element allow-forward-after-flush {


child of web-app

The <allow-servlet-el> flag configures whether <servlet> tags allow EL expressions in the init-param.

<allow-servlet-el> schema
element allow-servlet-el {


child of web-app

<archive-path> configures the location of the web-app's .war file. In some configurations, the .war expansion might not use thewebapps/directory, but will still want automatic war expantion.

<archive-path> schema
element archive-path {
Example: resin.xml explicit archive location
<resin xmlns="">
<cluster id="">

  <host id="">

    <web-app id="/foo"



Requires that authenticated users fill the specified role. In Resin's JdbcAuthenticator, normal users are in the "user" role. Think of a role as a group of users.

The roles are defined by the authenticators (seeResin security). When using Resin's <resin:AdminAuthenticator> as a default, the role name isresin-admin. (SeeResin management.)

<auth-constraint> Attributes
role-nameRoles which are allowed to access the resource.
<auth-constraint> schema
element auth-constraint {



child of web-app

<cache-mapping> specifiesmax-ageandExpirestimes for cacheable pages.

Seecachingfor more information.

<cache-mapping> is intended to provide Expires times for pages that have ETags or Last-Modified specified, but do not wish to hard-code the max-age timeout in the servlet. For example, Resin's FileServlet relies on cache-mapping to set the expires times for static pages. Using cache-mapping lets cacheable pages be configured in a standard manner.

<cache-mapping> does not automatically make pages cacheable. Your servlets must already set theETag(or Last-Modified) header to activate <cache-mapping>.

  • cache-mapping requires an enabled <cache>. If the cache is disabled, cache-mapping will be ignored.
  • cache-mapping does not automatically make a page cacheable. Only cacheable pages are affected by cache-mapping, i.e. pages with an ETag or Last-Modified.

The time intervals default to seconds, but will allow othertime intervals.

<cache-mapping> Attributes
expiresA time interval to be used for the HTTP Expires header.
max-ageA time interval to be used for the "Cache-Control max-age=xxx" header. max-age affects proxies and browsers.
s-max-ageA time interval to be used for the "Cache-Control s-max-age=xxx" header. s-max-age affects proxy caches (including Resin), but not browsers.
url-patternA pattern matching the url:/foo/*, /foo, or *.foo
url-regexpA regular expression matching the url
<cache-mapping> schema
element cache-mapping {
  (url-pattern | url-regexp)
  & expires?
  & max-age?
  & s-max-age?
Example: cache-mapping in resin-web.xml
<web-app xmlns="">

  <cache-mapping url-pattern='/*'

  <cache-mapping url-pattern='*.gif'



Defines a custom constraint. Applications can define their own security constraints to handle custom authentication requirements.

<constraint> Attributes
resin:typeA class that extends AbstractConstraint
initinitialization parameters, set in the object using Bean-style setters and getters
<constraint> schema
element constraint {
  & init?


child of web-app

Initializes application (ServletContext) variables.context-paramdefines initial values forapplication.getInitParameter("foo"). See alsoServletContext.getInitParameter().

<context-param> Attributes
param-nameNamed parameter
param-valueParameter value
fooParameter name
<context-param> schema
element context-param {
  (param-name, param-value)*
  | (attribute * { string })*
  | (element * { string })*
Example: context-param in resin-web.xml
<web-app xmlns="">


  <!-- shortcut -->
  <context-param foo="bar"/>



child of web-app

The <cookie-http-only> flag configures the Http-Only attribute for all Cookies generated from the web-app. The Http-Only attribute can add security to a website by not forwarding HTTP cookies to SSL HTTPS requests.

<cookie-http-only> schema
element cookie-http-only {
Example: <cookie-http-only> in resin.xml
<resin xmlns="">
<cluster id="">

  <host id="">
    <web-app id="" root-directory="/var/www/foo">
    <web-app id="">

  <host id="">
    <web-app id="" root-directory="/var/www/foo-secure">
    <web-app id="">



child of host,web-app

Specifies ear expansion.

ear-deploy can be used in web-apps to define a subdirectory for ear expansion.

<ear-deploy> Attributes
archive-pathThe path to the directory containing ear filespath
ear-defaultresin.xml default configuration for all ear files, e.g. configuring database, JMS or EJB defaults.
expand-cleanup-filesetSpecifies the files which should be automatically deleted when a new .ear version is deployed.
expand-directorydirectory where ears should be expandedvalue of path
expand-prefixautomatic prefix of the expanded directory_ear_
expand-suffixautomatic suffix of the expanded directory
lazy-initif true, the ear file is only started on first accessfalse
pathThe path to the deploy directoryrequired
redeploy-mode"automatic" or "manual". If automatic, detects new .ear files automatically and deploys them.automatic
url-prefixoptional URL prefix to group deployed .ear files
<ear-deploy> schema
element ear-deploy {
  & archive-directory?
  & ear-default?
  & expand-cleanup-fileset?
  & expand-directory?
  & expand-path?
  & expand-prefix?
  & expand-suffix?
  & lazy-init?
  & redeploy-mode?
  & require-file*
  & url-prefix?


child of web-app

Allows applications to customize the response generated for errors. By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages. With <error-page>, you may specify a handler page for these errors.

The handler page has several request attributes set so that it may log, display, or otherwise use information about the error that occured. The following table describes the available attributes.

Request attributes for error handling
<error-page> Attributes
error-codeSelect the error page based on an HTTP status code
exception-typeSelect the error page based on a Java exception
locationThe error page to display
<error-page> schema
element error-page {
  (error-code | exception-type)?
  & location
Catching File Not Found
<web-app xmlns="">
Catching Exceptions
<web-app xmlns="">
   <error-page exception-type="java.lang.NullPointerException"
Using request attributes to obtain information about the request that caused the error
<%@ page session="false" isErrorPage="true" %>

<head><title>404 Not Found</title></head>
<h1>404 Not Found</h1>

The url <code>${requestScope["javax.servlet.error.request_uri"]}</code> 
was not found.


child of web-app

Defines a filter name for later mapping. Because Filters are fully integrated withResin CanDI, they can use dependency-injection, transactional aspects, custom interception with @InterceptorType, and event handling with @Observes.

<filter> Attributes
filter-nameThe filter's name (alias)
filter-classThe filter's class (defaults to filter-name), which extends javax.servlet.Filter
initResin-IoC initialization configuration, see Resin-IoC
init-paramInitialization parameters, see FilterConfig.getInitParameter
<filter> schema
element filter {
  & filter-class
  & init*
  & init-param*
Defining a filter name 'image'
<web-app xmlns="">

      <param-value>Hello, World</param-value>


init-param shortcut syntax
<web-app id='/'>

<filter filter-name='test.HelloWorld'>
  <init-param foo='bar'/>




child of web-app

Maps url patterns to filters.filter-mappinghas two children,url-patternandfilter-name.url-patternselects the urls which should execute the filter.

filter-namecan either specify a filter class directly or it can specify a filter alias defined byfilter.

<filter-mapping> Attributes
filter-nameThe filter namerequired
url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the portion of the url that follows the context path
<filter-mapping> schema
element filter-mapping {
  (url-pattern | url-regexp | servlet-name)+
  & filter-name
  & dispatcher*
Example: resin-web.xml filters
<web-app xmlns="">






child of login-config

Configures authentication using forms. The login form has specific parameters that the servlet engine's login form processing understands. If the login succeeds, the user will see the original page. If it fails, she will see the error page.

The form itself must have the actionj_security_check. It must also have the parametersj_usernameandj_password. Optionally, it can also havej_uriandj_use_cookie_auth.j_urigives the next page to display when login succeeds.j_use_cookie_authallows Resin to send a persistent cookie to the user to make following login easier.

j_use_cookie_authgives control to the user whether to generate a persistent cookie. It lets you implement the "remember me" button. By default, the authentication only lasts for a single session.

<form-login-config> Attributes
form-login-pageThe page to be used to prompt the user login
form-error-pageThe error page for unsuccessful login
internal-forwardUse an internal redirect on success instead of a sendRedirectfalse
form-uri-priorityIf true, the form's j_uri will override a stored URIfalse
Special form input names
j_security_checkThe form's mandatory action
j_usernameThe user name
j_passwordThe password
j_uriOptional Resin extension for the successful display page.
j_use_cookie_authOptional Resin extension to allow cookie login.
<form-login-config> schema
element form-login-config {
Example: login.html
<form action='j_security_check' method='POST'>
<tr><td>User:<td><input name='j_username'>
<tr><td>Password:<td><input name='j_password'>
<tr><td colspan=2>hint: the password is 'quidditch'
<tr><td><input type=submit>


child of web-app

The <idle-time> specifies the timeout for lazy-idle web-apps. In some configurations, web-apps are created only on demand and are closed when no requests access the web-app. The idle-time configures when those web-apps should be freed.

For example, the resin-doc web-app uses idle-time for its child web-apps because there are a large number of sub-web-apps for the individual tutorials.

<idle-time> schema
element idle-time {


child of web-app

Configures JSF behavior.

<jsf> Attributes
fast-jsfOptimize JSF code generationtrue
state-serialization-methodConfigures method of JSF state serialization. Setting value to hessian provides fast, size optimized Hessian serialization. Method java allows fallback to Java Serialization. hessian
enable-developer-aidif true, makes snapshots of component tree and request information available via a link displayed at the right bottom corner of a JSF page. false
developer-aid-link-stylecontrols appearance of the JSF Dev Aid on a JSF page. position:absolute; bottom:0; right:0
<jsf> schema
element jsf {
  & fast-jsf?


child of web-app

Configures JSP behavior.

<jsp> Attributes
auto-compileAutomatically compile changed JSP filestrue
deferred-syntax-allowed-as-literalenables the #{...} syntax as text contentstrue
dependency-check-intervalHow often to check the jsp for changes, -1 disablesinherited
el-ignoredIgnore EL expressions in JSP textfalse
fast-jstlOptimize JSTL code generationtrue
ignore-el-exceptionIgnore exceptions generated in EL expressions. For debugging, set to falsetrue
is-xmlDefault JSP pages to use XML syntaxfalse
page-encodingSets the default page encodingISO-8859-1
precompileTry to load precompiled JSP pagestrue
print-null-as-blankIf true, expressions evaluating to null are not printedfalse
recompile-on-errorRecompile the JSP file when an Error occurs in loadingfalse
recycle-tagsReuse tag instances when possible for performancetrue
require-sourceReturn 404 when JSP source is deletedfalse
scriping-invalidDisables all Java scripting and expression in JSP pagesfalse
sessionCreates sessions for each JSP pagetrue
static-page-generates-classIf true, JSPs with no active content still generate a .classtrue
tld-dirrestricts the directory to scan for .tld files, improving startup performanceWEB-INF
tld-file-setadds an ant-style pattern for .tld scanningWEB-INF
trim-directive-whitespaceif true, trims whitespace around JSP directivesfalse
validate-taglib-schemaif true, validate .tld files against the .tld schema. Set to false to handle invalid .tld filestrue
velocity-enabledif true, velocity-style tags are allowedfalse
character-encodingSets JSP response character encoding; overrides character encoding defined at web-app level
<jsp> schema
element jsp {
  & deferred-syntax-allowed-as-literal?
  & dependency-check-interval?
  & el-ignored?
  & fast-jstl?
  & ide-hack?
  & ignore-el-exception?
  & is-xml?
  & page-encoding?
  & precompile?
  & print-null-as-blank?
  & recompile-on-error?
  & recycle-tags?
  & require-source?
  & scripting-invalid?
  & session?
  & static-page-generates-class?
  & tld-dir?
  & tld-file-set?
  & trim-directive-whitespaces?
  & validate-taglib-schema?
  & velocity-enabled?


<jsp-config> configure standard settings for JSP files.

<jsp-config> Attributes
url-patternselects the URLs which this jsp-config applies to
el-ignoredIf true, EL expressions are ignoredfalse
page-encodingDefines the default page encoding for the JSP fileISO-8859-1
scripting-invalidIf true, Java scripting is forbidded in the JSP pagefalse
trim-directive-whitespacesIf true, extra whitespace is trimmed around JSP directivesfalse
is-xmlIf true, for XML syntax for JSP pagesfalse
include-preludeIncludes JSP fragments before the JSP page as headers
include-codaIncludes JSP fragments before the JSP page as footers
<jsp-config> schema
element jsp-config {

element jsp-property-group {


default false

<lazy-servlet-validate> defers validation of servlet classes until the servlet is used. Some servlet libraries are bundled with web.xml files which include servlets with no available classes. Since Resin will normally send an error in this situation, <lazy-servlet-validate> lets you turn the validation off.

<lazy-servlet-validate> schema
element lazy-servlet-validate {


<listener> configures servlet event listeners. The listeners are registered based on interfaces they implement. The listener instances are fullyResin-IoCaware, including dependency injection, observing events, and supporting aspects.

listener interfaces
javax.servlet.ServletContextListenerCalled when the web-app starts and stops
javax.servlet.ServletContextAttributeListenerCalled when the web-app attributes change
javax.servlet.ServletRequestListenerCalled when the request starts and stops
javax.servlet.ServletRequestAttributeListenerCalled when request attributes change
javax.servlet.http.HttpSessionListenerCalled when HTTP sessions start or stop
javax.servlet.http.HttpSessionAttributeListenerCalled when HTTP sessions attributes change
javax.servlet.http.HttpSessionActivationListenerCalled when HTTP sessions passivate or activate
<listener> Attributes
listener-classclassname of the listener implementation
initIoC initialization of the listener
<listener> schema
element listener {


child of web-app
default no authentication

Configures the login method for authentication, one of BASIC, DIGEST or FORM.

See also:Resin securityfor an overview.

<login-config> Attributes
auth-methodAuthentication method, either BASIC for HTTP Basic Authentication, FORM for form based authentication, or DIGEST for HTTP Digest Authentication.
authenticatorSpecifies the authenticator to use to lookup users and passwords.
classDefines a custom class which extends
form-login-configConfiguration for form login.
initInitialization for the custom login class
realm-nameThe realm name to use in HTTP authentication

HTTP Authentication is defined in the RFCHTTP Authentication: Basic and Digest.

HTTP digest authentication is discussed inDigest Passwords.

<login-config> schema
element login-config {
  & auth-method?
  & authenticator?
  & form-login-config?
  & init?
  & realm-name?


child of web-app

Maps url patterns to mime-types.

<mime-mapping> Attributes
extensionurl extension
mime-typethe mime-type
<mime-mapping> schema
element mime-mapping {
Example: WEB-INF/resin-web.xml
<web-app xmlns="">


  <!-- resin shortcut syntax -->
  <mime-mapping extension='.bar'


Resin has a long list of default mime types in$RESIN_HOME/conf/app-default.xml


child of web-app

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

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

<multipart-form> Attributes
upload-maxmaximum size of an upload request (in kb).no limit

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. The "caucho.multipart.form.error.size" will contain the attempted upload size.

Requests can set the maximum by setting the request attribute "caucho.multipart.form.upload-max" with an Integer or Long value.

By default, multipart-form is disabled.

<multipart-form> schema
element multipart-form {
  & upload-max?


child of web-app

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

<path-mapping> Attributes
url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the portion of the url that follows the context path
real-pathThe prefix of the real path. When used with url-regexp, allows substitution variables like $1.
<path-mapping> schema
element path-mapping {
  (url-pattern | url-regexp)

  & real-path
Example: resin-web.xml aliasing paths
<web-app xmlns="">

<path-mapping url-pattern='/resin/*'

<path-mapping url-regexp='/~([^/]*)'



<protocol> configures a remoting protocol for a Java bean. The bean is configured with the <servlet> and <servlet-mapping> tags, since it will process HTTP URL requests.

Protocol drivers extend thecom.caucho.remote.server.AbstractProtocolServletFactoryinterface and can register a URI alias to simplify configuration.

<protocol> Attributes
classClassname of the protocol driver implementing ProtocolServletFactory
initOptional IoC initialization for the protocol driver
uriProtocol configuration shortcut
Current drivers
burlap:The burlap XML protocol
cxf:The CXF SOAP implementation
hessian:The Hessian protocol
xfire:The XFire SOAP implementation
<protocol> schema
element protocol {
  (class | uri)
  & init?


child of web-app
default 60s

<redeploy-check-interval> specifies how often Resin should check if a .war file has been updated or added to a <web-app-deploy> directory.

<redeploy-check-interval> schema
element redeploy-check-interval {


child of web-app
default automatic

<redeploy-mode> specifies how Resin handles updates to web-apps and .war files. By default, Resin restarts web-apps when classes or configuration files change.

<redeploy-mode> Attributes
automaticchecks for redeployment and auto-redeploy if modified
manualdoes not check for redeployment. Only checks if manual (JMX)
<redeploy-mode> schema
element redeploy-mode {
  automatic | manual


<rewrite-real-path> lets you rewrite the URL to physical path mapping, to allow aliasing or for filesystem organization.

<rewrite-real-path> Attributes
real-pathspecifies the URL to real-path mapping
regexpa regular expression matching a URL
replacementspecifies a replacement pattern for URL to URL rewriting
rewriterewrites a URL to another URL as a preprocessing-step
targetspecifies the target for URL to real-path mapping
<rewrite-real-path> schema
element rewrite-real-path {
  element rewrite {
    & replacement

  & element rewrite {
    & target
Example: aliasing /foo to /bar
<web-app xmlns="">

    <real-path regexp="^/foo" target="/bar"/>



<root-directory> specifies the base directory for the contexts. All EL-style directory paths are relative to the root-directory.

<root-directory> schema
element root-directory {
Example: cluster root-directory
<resin xmlns="">
    <cluster id="app-tier">

        <server id="a" ...>

        <host host-name="">


child of web-app

The <secure> flag requires that the web-app only be accessed in a secure/SSL mode. Equivalent to a <security-constraint>.

<secure> schema
element secure {


child of web-app

Specifies protected areas of the web site. Sites using authentication as an optional personalization feature will typically not use any security constraints. SeeResin securityfor an overview.

Security constraints can also be custom classes.

SeeResin securityfor an overview of security issues and configuration.

<security-constraint> Attributes
auth-constraintDefines a security condition based on a logged-in user's role
constraintDefines a custom security condition
ip-constraintDefines a security condition based the remote IP address
role-nameDefines role-name requirement
url-patternURL pattern to match the security constraint
user-data-constraintDefines SSL or non-SSL requirements
web-resource-collectionURL patterns and HTTP methods defining the constraint
<security-constraint> schema
element security-constraint {
  & constraint*
  & ip-constraint*
  & role-name*
  & user-data-constraint*
  & url-pattern?
  & web-resource-collection*
Example: 'user' role required in WEB-INF/resin-web.xml
<web-app xmlns="">

  <auth-constraint role-name='user'>



Defines a servlet to process HTTP URL requests. The servlet class can either implementjavax.servlet.Servletto handle the HTTP request directly or it can use a remoting protocol like Hessian to handle remoting requests.

Since servlets are fullResin-CanDIbeans, they can use dependency injection, EJB aspects like @TransactionAttribute, custom @InterceptorType interceptors, and listen for @Observes events.

<servlet> Attributes
initResin-IoC initialization
init-paramInitialization parameters
load-on-startupInitializes the servlet when the server starts.
protocolProtocol configuration for Resin remoting.
run-atTimes to execute the servlet automatically.
servlet-nameThe servlet's name (alias)
servlet-classThe servlet's class (In Resin, defaults to servlet-name)
<servlet> schema
element servlet {
  < (servlet-class | jsp-file)
  < init*
  < init-param*
  < load-on-startup?
  < protocol?
  < run-as?
  < run-at?
Example: WEB-INF/resin-web.xml
<web-app xmlns="">

      <param-value>Hello, World</param-value>

  <!-- using Resin shortcut syntax -->
  <servlet servlet-name='cron'
    <init-param title='Daily Chores'/>

  <!-- mapping a url to use the servlet -->
  <servlet-mapping url-pattern='/hello.html'


Severalservletconfigurations might configure the same servlet class with differentinit-paramvalues. Each will have a separateservlet-name.

Example: multiple servlets using the same class
<web-app xmlns="">
  <servlet servlet-name='foo-a'>
    <init-param name='foo-a sample'/>

  <servlet servlet-name='foo-b'>
    <init-param name='foo-b sample'/>

load-on-startupcan specify an (optional) integer value. If the value is 0 or greater, it indicates an order for servlets to be loaded, servlets with higher numbers get loaded after servlets with lower numbers.

There are a number of named servlets that are usually available to a Resin application, as defined in$RESIN_HOME/conf/app-default.xml.

Example: servlet-mappings in $RESIN_HOME/conf/app-default.xml
  <servlet servlet-name="directory"

  <servlet servlet-name="file"

  <servlet servlet-name="jsp"

  <servlet servlet-name="xtp"

<servlet servlet-name="j_security_check"


Maps url patterns to servlets.servlet-mappinghas two children,url-patternandservlet-name.url-patternselects the urls which should execute the servlet.

<servlet-mapping> Attributes
initResin-IoC configuration of the servlet.
protocolDefines the optional remoting protocol.
servlet-classThe servlet-mapping can define the servlet directly as a shortcut.
servlet-nameThe servlet name
url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the portion of the url that follows the context path
<servlet-mapping> schema
element servlet-mapping {
  & protocol?
  & servlet-class?
  & servlet-name?
  < url-pattern*
  < url-regexp*
Example: WEB-INF/resin-web.xml <servlet-mapping>
<web-app xmlns="">



  <!-- resin shortcut syntax -->
  <servlet-mapping url-pattern='*.xtp'


In Resin, the specialservlet-name'invoker'is used to dispatch servlets by class name.

Warning Enabling the invoker servlet can create a security hole in your application. Any servlet in the classpath, perhaps even one in a .jar that you are unaware of, could be invoked.
Example: WEB-INF/resin-web.xml servlet invoker
<web-app xmlns="">

    used with urls like 
  <servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/>


There are a number of mappings to servlets that are usually available to a Resin application, as defined in$RESIN_HOME/conf/app-default.xml.

Example: servlet-mappings in $RESIN_HOME/conf/app-default.xml

  <servlet-mapping url-pattern="*.jsp" servlet-name="jsp"/>
  <servlet-mapping url-pattern="*.xtp" servlet-name="xtp"/>

  <servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/>
  <servlet-mapping url-pattern="/" servlet-name="file"/>

The plugins use servlet-mapping to decide which URLs to send to Resin. The following servlet-name values are used by the plugins:

servlet-name values used by plugins
plugin_matchThe plugin will send the request to Resin, but Resin will ignore the entry. Use to get around regexp limitations. (Resin 1.2.2)
plugin_ignoreThe plugin will ignore the request. Use this to define a sub-url the web server should handle, not Resin. (Resin 1.2.2)


Maps URL by regular expressions to custom servlets.

<servlet-regexp> schema
element servlet-regexp {
  & servlet-class?
  & servlet-name?
  & url-regexp
<servlet-regexp url-regexp="/([^.]*).do"
  <init a="b"/>


<session-config> configures Resin's session handling, including the cookies Resin sends, the maximum sessions, and session persistence and clustering.

See also:Resin clusteringfor more information about distributed sessions and persistence.

<session-config> Attributes
always-load-sessionReload data from the store on every requestfalse
always-save-sessionSave session data to the store on every requestfalse
enable-cookiesEnable cookies for sessionstrue
enable-url-rewritingEnable URL rewriting for sessionstrue
cookie-versionVersion of the cookie spec for sessions1.0
cookie-domainDomain for session cookiesnone
cookie-max-ageMax age for persistent session cookiesnone
cookie-lengthMaximum length of the cookie
ignore-serialization-errorsWhen persisting a session, ignore any values which don't implement
invalidate-after-listenerIf true, invalidate the sessions after the session listeners have been called
reuse-session-idReuse the session id even if the session has timed out. A value of false defeats single signon capabilities. (resin 2.0.4)true
session-maxMaximum active sessions4096
session-timeoutThe session timeout in minutes, 0 means never timeout.30 minutes
serialization-typeUse one of "java" or "hessian" for serialization, hessian is significantly faster and smaller (resin 3.1.2)java
serialize-collection-typeFor hessian serialization, ignore the collection type when serializing lists (disable for some Hibernate lists)true
save-modeWhen to save sessions, one of "before-headers", "after-request", or "on-shutdown"after-request
use-persistent-storeUses the current persistent-store to save sessions. (resin 3.0.8)none
<session-config> schema
element session-config {
  & always-save-session?
  & cookie-append-server-index?
  & cookie-domain?
  & cookie-length?
  & cookie-max-age?
  & cookie-port?
  & cookie-secure?
  & cookie-version?
  & enable-cookies?
  & enable-url-rewriting?
  & ignore-serialization-errors?
  & invalidate-after-listener?
  & reuse-session-id?
  & save-mode?
  & save-on-shutdown?
  & serialization-type?
  & session-max?
  & session-timeout?
  & use-persistent-store?

Thesession-timeoutandsession-maxare usually used together to control the number of sessions. Sessions are stored in an LRU cache. When the number of sessions in the cache fills up pastsession-max, the oldest sessions are recovered. In addition, sessions idle for longer thansession-timeoutare purged.

using session-config and session-timeout to control the number of sessions
<web-app id='/dir'>

     <!-- 2 hour timeout -->


cookie-lengthis used to limit the maximum length for the session's generated cookie for special situations like WAP devices. Reducing this value reduces the randomness in the cookie and increases the chance of session collisions.

reuse-session-iddefaults to true so that Resin can share the session id amongst different web-apps.

The class that corresponds to <session-config> iscom.caucho.server.session.SessionManager


child of server

<shutdown-wait-max> configures the maximum time the server will wait for the graceful shutdown before forcing an exit.

default 60s
<shutdown-wait-max> schema
element shutdown-wait-max {


default false

<statistics-enable> enables more detailed statistics for theWebAppMXBeanadministration. The statistics gathering is disabled by default for performance reasons.

<statistics-enable> schema
element statistics-enable {


default false, allowing /foo/bar.jsp/foo.

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

<strict-mapping> schema
element strict-mapping {
Example: enabling strict-mapping in resin-web.xml
<web-app xmlns="">


Restricts access to secure transports, such as SSL

<user-data-constraint> Attributes
transport-guaranteeRequired transport properties. NONE, INTEGRAL, and CONFIDENTIAL are allowed values.
<user-data-constraint> schema
element user-data-constraint {


child of host,web-app

web-app configures a web application.

When specified byid, the application will be initialized on server start. When specified byurl-regexp, the application will be initialized at the first request. This means thatload-on-startupservlets may start later than expected forurl-regexpapplications.

<web-app> Attributes
active-wait-timehow long a thread should wait for the web-app to initialize before returning a 503-busy.15s
archive-pathSpecifies the location of the web-app's .war file.n/a
context-pathSpecifies the URL prefix for the web-app.the id value
idThe url prefix selecting this application.n/a
redeploy-mode'automatic' or 'manual', see redeploy-modeautomatic
redeploy-check-intervalhow often to check the .war archive for redeployment60s
root-directoryThe root directory for the application, corresponding to a url of /id/. A relative path is relative to the root-directory of the containing host. Can use regexp replacement variables.A relative path constricted with the id or the regexp match
startup-mode'automatic', 'lazy', or 'manual', see startup-modeautomatic
startup-priorityspecifies a priority for web-app startup to force an ordering between webapps -1
url-regexpA regexp to select this application.n/a

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

<host id=''>
  <web-app id='/apache' root-directory='/usr/local/apache/htdocs'>



The following example sets the root web-app to the IIS root directory.

  <web-app id='/' root-directory='C:/inetpub/wwwroot'>

When theweb-appis specified with aurl-regexp,root-directorycan use replacement variables ($2).

In the following, each user gets his or her own independent application using~user.

<host id=''>

  <web-app url-regexp='/~([^/]*)'





child of cluster

<web-app-default> defines default values for anyweb-appin the cluster.

Example: web-app-default
<resin xmlns="">
    <cluster id="app-tier">

            <servlet servlet-name="resin-php"

            <servlet-mapping url-pattern="*.php"

        <host id="">


child of host,web-app

Specifies war expansion.

web-app-deploy can be used in web-apps to define a subdirectory for war expansion. The tutorials in the documentation use web-app-deploy to allow servlet/tutorial/helloworld to be an independent war file.

<web-app-deploy> Attributes
archive-directorydirectory containing the .war filesvalue of path
dependency-check-intervalHow often to check the .war files for a redeploy60s
expand-cleanup-filesetdefines the files which should be automatically deleted when an updated .war expandsall files
expand-directorydirectory where wars should be expandedvalue of path
expand-prefixprefix string to use when creating the expansion directory, e.g. _war_
expand-suffixprefix string to use when creating the expansion directory, e.g. .war
pathThe path to the webapps directoryrequired
redeploy-mode"automatic" or "manual"automatic
require-fileadditional files to use for dependency checking for auto restart
startup-mode"automatic", "lazy" or "manual"automatic
url-prefixurl-prefix added to all expanded webapps""
versioningif true, use the web-app's numeric suffix as a versionfalse
web-app-defaultdefaults to be applied to expaned web-apps
web-appoverriding configuration for specific web-apps
<web-app-deploy> schema
element web-app-deploy {

Overriding web-app-deploy configuration

The web-app-deploy can override configuration for an expanded war with a matching <web-app> inside the <web-app-deploy>. The <root-directory> is used to match web-apps.

Example: resin.xml overriding web.xml
<resin xmlns="">
<cluster id="">
<host id="">

<web-app-deploy path="webapps">
  <web-app context-path="/wiki"
    <context-param database="jdbc/wiki">



The versioning attribute of the <web-app-deploy> tag improves web-app version updates by enabling a graceful update of sessions. The web-apps are named with numeric suffixes, e.g. foo-10, foo-11, etc, and can be browsed as /foo. When a new version of the web-app is deployed, Resin continues to send current session requests to the previous web-app. New sessions go to the new web-app version. So users will not be aware of the application upgrade.


Specifies a collection of areas of the web site for security purposes. SeeResin securityfor an overview.

<web-resource-collection> Attributes
web-resource-namea name for a web resource collection
url-patternurl patterns describing the resource
http-methodHTTP methods to be restricted.
<web-resource-collection> schema
element web-resource-collection {
  & http-method*
  & web-resource-name?


child of web-app

Sets the files to use as when no filename is present in url. According to the spec, each file is in a <welcome-file> element.

<welcome-file-list> schema
element welcome-file-list {
  | welcome-file*
Example: WEB-INF/resin-web.xml
<web-app xmlns="">

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

Example: WEB-INF/resin-web.xml
<web-app xmlns="">
    index.jsp, index.xtp, home.xtp
default in $RESIN_HOME/conf/app-default.xml is index.xtp, index.jsp, index.html.

Copyright © 1998-2011 Caucho Technology, Inc. All rights reserved.
Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.