Caucho Technology
  • resin 4.0
  • 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 of web-app, overrides the definition in the host that the web-app is deployed in. As a child of host, overrides the definition in the server that 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:type allows for custom logging. Applications can extend a custom class from com.caucho.http.log.AccessLog. Resin-IoC initialization can 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 the webapps/ 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 (see Resin security). When using Resin's <resin:AdminAuthenticator> as a default, the role name is resin-admin. (See Resin 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> specifies max-age and Expires times for cacheable pages.

    See caching for 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 the ETag (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 other time 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-param defines initial values for application.getInitParameter("foo"). See also ServletContext.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 with Resin 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-mapping has two children, url-pattern and filter-name. url-pattern selects the urls which should execute the filter.

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

    <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 action j_security_check. It must also have the parameters j_username and j_password. Optionally, it can also have j_uri and j_use_cookie_auth. j_uri gives the next page to display when login succeeds. j_use_cookie_auth allows Resin to send a persistent cookie to the user to make following login easier.

    j_use_cookie_auth gives 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 fully Resin-IoC aware, 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 security for 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 RFC HTTP Authentication: Basic and Digest.

    HTTP digest authentication is discussed in Digest 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 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.

    <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 the com.caucho.remote.server.AbstractProtocolServletFactory interface 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. See Resin security for an overview.

    Security constraints can also be custom classes.

    See Resin security for 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 implement javax.servlet.Servlet to handle the HTTP request directly or it can use a remoting protocol like Hessian to handle remoting requests.

    Since servlets are full Resin-CanDI beans, 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'

    Several servlet configurations might configure the same servlet class with different init-param values. Each will have a separate servlet-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-startup can 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-mapping has two children, url-pattern and servlet-name. url-pattern selects 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 special servlet-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 clustering for 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?

    The session-timeout and session-max are 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 past session-max, the oldest sessions are recovered. In addition, sessions idle for longer than session-timeout are purged.

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

    cookie-length is 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-id defaults to true so that Resin can share the session id amongst different web-apps.

    The class that corresponds to <session-config> is com.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 the WebAppMXBean administration. 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 is true or false.

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

    <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 the web-app is specified with a url-regexp, root-directory can 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 any web-app in 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. See Resin security for 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.