Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server

Resin Documentation

home company docs
app server

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>

child of <cluster>,<cluster-default>,<server>,<server-default>,<host>,<host-default>,<web-app>,<web-app-default>

<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
PATTERN	DESCRIPTION
%b	result content length
%D	time taken to complete the request in microseconds (since 3.0.16)
%h	remote IP addr
%{xxx}i	request header xxx
%{xxx}o	response header xxx
%{xxx}c	cookie value xxx
%{xxx}n	request attribute
%{xxx}p	request parameter
%r	request URL
%s	status code
%S	requested session id
%{xxx}t	request date with optional time format string.
%T	time taken to complete the request in seconds
%u	remote user
%U	request URI
%v	name 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
ATTRIBUTE	DESCRIPTION	DEFAULT
path	Output path for the log entries, see "Log Paths".	required
path-format	Selects a format for generating path names. The syntax is the same as for archive-format.	optional
archive-format	the format for the archive filename when a rollover occurs, see Rollovers.	see below
auto-flush	true to flush the memory buffer with each request.	false
auto-flush-time	sets time interval for flushing the memory buffers	60s
exclude	access logging exclude patterns for request URIs. Access to matching URIs does not get logged.	none
format	Access log format.	see above
hostname-dns-lookup	log the dns name instead of the IP address (has a performance hit).	false
rollover-period	how often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See "Rollovers".	none
rollover-size	maximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See "Rollovers".	1gb
rollover-count	maximum number of rollover files before the oldest ones get overwritten. See "Rollovers".	none
resin:type	a class extending com.caucho.server.log.AccessLog for custom logging	com.caucho.server.log.AccessLog
init	Resin-IoC initialization for the custom class	n/a

<access-log> schema

element access-log {
  path?
  & path-format?
  & archive-format?
  $amp;auto-flush?
  & 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="http://caucho.com/ns/resin">
<cluster id="app-tier">

  <host id="">
    <access-log path='log/access.log'>
      <rollover-period>2W</rollover-period>
    </access-log>
  </host>
</cluster>
</resin>

Example: custom access log

<resin xmlns="http://caucho.com/ns/resin">

<cluster id="app-tier">

  <host id='foo.com'>

    <access-log>
      <test:MyLog xmlns:test="urn:java:test">
                 path='${resin.root}/foo/error.log'
                 rollover-period='1W'>
          <test:foo>bar</test:foo>
      </test:MyLog>
    </access-log>
    ...
  </host>

</cluster>
</resin>

<active-wait-time>

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 {
  r_period-Type
}

<allow-forward-after-flush>

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 {
  r_boolean-Type
}

<allow-servlet-el>

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 {
  r_boolean-Type
}

<archive-path>

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 {
  r_path-Type
}

Example: resin.xml explicit archive location

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <host id="">

    <web-app id="/foo"
             root-directory="/var/resin/foo"
             archive-path="/var/resin/wars/foo.war"/>

  </host>
</cluster>
</resin>

<auth-constraint>

child of <security-constraint>

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
ATTRIBUTE	DESCRIPTION
role-name	Roles which are allowed to access the resource.

<auth-constraint> schema

element auth-constraint {
  description*,

  role-name*
}

<cache-mapping>

child of <web-app>

<cache-mapping> specifies max-age and Expires times for cacheable pages.

See proxy-cache 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 dynamic (non-static) pages cacheable. Your servlets must already set the ETag (or Last-Modified) header to activate <cache-mapping>. For static resources, Resin's FileServlet sets the ETag header.

cache-mapping requires an enabled <proxy-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
ATTRIBUTE	DESCRIPTION	DEFAULT
expires	A time interval to be used for the HTTP Expires header.
max-age	A time interval to be used for the "Cache-Control max-age=xxx" header. max-age affects proxies and browsers.
s-max-age	A 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-pattern	A pattern matching the url:/foo/, /foo, or .foo
<url-regexp>	A regular expression matching the url

<cache-mapping> schema

element cache-mapping {
  (url-pattern | url-regexp)
  & expires?
  & max-age?
  & s-max-age?
}

Example: caching .gif files for 15 minutes

<web-app xmlns="http://caucho.com/ns/resin">

  <cache-mapping url-pattern='/*'
                 max-age='10'/>

  <cache-mapping url-pattern='*.gif'
                 max-age='15m'/>

</web-app>

<constraint>

child of <security-constraint>

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

<constraint> Attributes
ATTRIBUTE	DESCRIPTION
resin:type	A class that extends AbstractConstraint
init	initialization parameters, set in the object using Bean-style setters and getters

<constraint> schema

element constraint {
  class
  & init?
}

<context-param>

child of <web-app>

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

<context-param> Attributes
ATTRIBUTE	DESCRIPTION
param-name	Named parameter
param-value	Parameter value
foo	Parameter 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="http://caucho.com/ns/resin">

  <context-param>
    <param-name>baz</param-name>
    <param-value>value</param-value>
  </context-param>

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

</web-app>

<cookie-http-only>

child of <web-app>

The <cookie-http-only> flag configures the Http-Only attribute for the JSESSIONID cookie 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 {
  r_boolean-Type
}

Example: <cookie-http-only> in resin.xml

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <host id="www.foo.com">
    <web-app id="" root-directory="/var/resin/foo">
      <cookie-http-only>true</cookie-http-only>
    <web-app id="">
  </host>

  <host id="www.foo.com:443">
    <web-app id="" root-directory="/var/resin/foo-secure">
      <secure/>
    <web-app id="">
  </host>

</cluster>
</resin>

<ear-deploy>

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
ATTRIBUTE	DESCRIPTION	DEFAULT
archive-directory	The path to the directory containing ear files	path
ear-default	resin.xml default configuration for all ear files, e.g. configuring database, JMS or EJB defaults.
expand-cleanup-fileset	Specifies the files which should be automatically deleted when a new .ear version is deployed.
expand-directory	directory where ears should be expanded	value of path
expand-prefix	automatic prefix of the expanded directory	_ear_
expand-suffix	automatic suffix of the expanded directory
lazy-init	if true, the ear file is only started on first access	false
path	The path to the deploy directory	required
redeploy-mode	"automatic" or "manual". If automatic, detects new .ear files automatically and deploys them.	automatic
url-prefix	optional URL prefix to group deployed .ear files

<ear-deploy> schema

element ear-deploy {
  path
  & archive-directory?
  & ear-default?
  & expand-cleanup-fileset?
  & expand-directory?
  & expand-path?
  & expand-prefix?
  & expand-suffix?
  & lazy-init?
  & redeploy-mode?
  & require-file*
  & url-prefix?
}

<error-page>

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
ATTRIBUTE	TYPE
javax.servlet.error.status_code	java.lang.Integer
javax.servlet.error.message	java.lang.String
javax.servlet.error.request_uri	java.lang.String
javax.servlet.error.servlet_name	java.lang.String
javax.servlet.error.exception	java.lang.Throwable
javax.servlet.error.exception_type	java.lang.Class

<error-page> Attributes
ATTRIBUTE	DESCRIPTION
error-code	Select the error page based on an HTTP status code
exception-type	Select the error page based on a Java exception
location	The error page to display

<error-page> schema

element error-page {
  (error-code | exception-type)?
  & location
}

Catching File Not Found

<web-app xmlns="http://caucho.com/ns/resin">
  <error-page>
    <error-code>404</error-code>
    <location>/file_not_found.jsp</location>
  </error-page>
</web-app>

Catching Exceptions

<web-app xmlns="http://caucho.com/ns/resin">
   <error-page exception-type="java.lang.NullPointerException"
               location="/nullpointer.jsp"/>
</web-app>

Using request attributes to obtain information about the request that caused the error

<%@ page session="false" isErrorPage="true" %>

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

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

<filter>

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
ATTRIBUTE	DESCRIPTION
filter-name	The filter's name (alias)
filter-class	The filter's class (defaults to filter-name), which extends javax.servlet.Filter
init	Resin-IoC initialization configuration, see Resin-IoC
init-param	Initialization parameters, see FilterConfig.getInitParameter

<filter> schema

element filter {
  filter-name
  & filter-class
  & init*
  & init-param*
}

Defining a filter name 'image'

<web-app xmlns="http://caucho.com/ns/resin">

  <filter>
    <filter-name>image</filter-name>
    <filter-class>test.MyImage</filter-class>
    <init-param>
      <param-name>title</param-name>
      <param-value>Hello, World</param-value>
    </init-param>
  </filter>

  <filter-mapping>
    <filter-name>image</filter-name>
    <url-pattern>/images/*</url-pattern>
  </filter-mapping>

</web-app>

init-param shortcut syntax

<web-app id='/'>

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

  <init-param>
    <param-name>baz</param-name>
    <param-value>value</param-value>
  </init-param>
</servlet>

</web-app>

<filter-mapping>

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
ATTRIBUTE	DESCRIPTION	DEFAULT
dispatcher	REQUEST, INCLUDE, FORWARD, ERROR	REQUEST
filter-name	The filter name	required
url-pattern	A pattern matching the url: /foo/, /foo, or .foo
<url-regexp>	A 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="http://caucho.com/ns/resin">

  <filter>
    <filter-name>test-filter</filter-name>
    <filter-class>test.MyFilter</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>test-filter</filter-name>
    <url-pattern>/hello/*</url-pattern>
  </filter-mapping>

  <servlet>
    <servlet-name>hello</servlet-name>
    <servlet-class>test.HelloWorld</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>hello</servlet-name>
    <url-pattern>/hello</url-pattern>
  </servlet-mapping>
</web-app>

<form-login-config>

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
ATTRIBUTE	DESCRIPTION	DEFAULT
form-login-page	The page to be used to prompt the user login
form-error-page	The error page for unsuccessful login
internal-forward	Use an internal redirect on success instead of a sendRedirect	false
form-uri-priority	If true, the form's j_uri will override a stored URI	false

Special form input names
ATTRIBUTE	DESCRIPTION
j_security_check	The form's mandatory action
j_username	The user name
j_password	The password
j_uri	Optional Resin extension for the successful display page.
j_use_cookie_auth	Optional Resin extension to allow cookie login.

<form-login-config> schema

element form-login-config {
  form-login-page,
  form-error-page,
  internal-forward,
  form-uri-priority
}

Example: login.html

<form action='j_security_check' method='POST'>
<table>
<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>
</table>
</form>

<jsp>

child of <web-app>

Configures JSP behavior.

<jsp> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
auto-compile	Automatically compile changed JSP files	true
deferred-syntax-allowed-as-literal	enables the #{...} syntax as text contents	true
dependency-check-interval	How often to check the jsp for changes, -1 disables	inherited
el-ignored	Ignore EL expressions in JSP text	false
fast-jstl	Optimize JSTL code generation	true
ignore-el-exception	Ignore exceptions generated in EL expressions. For debugging, set to false	true
is-xml	Default JSP pages to use XML syntax	false
page-encoding	Sets the default page encoding	ISO-8859-1
precompile	Try to load precompiled JSP pages	true
print-null-as-blank	If true, expressions evaluating to null are not printed	false
recompile-on-error	Recompile the JSP file when an Error occurs in loading	false
recycle-tags	Reuse tag instances when possible for performance	true
require-source	Return 404 when JSP source is deleted	false
scriping-invalid	Disables all Java scripting and expression in JSP pages	false
session	Creates sessions for each JSP page	true
static-page-generates-class	If true, JSPs with no active content still generate a .class	true
tld-dir	restricts the directory to scan for .tld files, improving startup performance	WEB-INF
tld-file-set	adds an ant-style pattern for .tld scanning	WEB-INF
trim-directive-whitespace	if true, trims whitespace around JSP directives	false
validate-taglib-schema	if true, validate .tld files against the .tld schema. Set to false to handle invalid .tld files	true
velocity-enabled	if true, velocity-style tags are allowed	false
character-encoding	Sets JSP response character encoding; overrides character encoding defined at web-app level

<jsp> schema

element jsp {
  auto-compile
  & 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>

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

<jsp-config> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
url-pattern	selects the URLs which this jsp-config applies to
el-ignored	If true, EL expressions are ignored	false
page-encoding	Defines the default page encoding for the JSP file	ISO-8859-1
scripting-invalid	If true, Java scripting is forbidded in the JSP page	false
trim-directive-whitespaces	If true, extra whitespace is trimmed around JSP directives	false
is-xml	If true, for XML syntax for JSP pages	false
include-prelude	Includes JSP fragments before the JSP page as headers
include-coda	Includes JSP fragments before the JSP page as footers

<jsp-config> schema

element jsp-config {
  taglib*,
  jsp-property-group*
}

element jsp-property-group {
  url-pattern*,
  deferred-syntax-allowed-as-literal?,
  el-ignored?,
  page-encoding?
  scripting-invalid?
  trim-directive-whitespaces?
  is-xml?
  include-prelude*
  include-coda*
}

<lazy-servlet-validate>

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 {
  r_boolean-Type
}

<listener>

<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
INTERFACE	DESCRIPTION
javax.servlet.ServletContextListener	Called when the web-app starts and stops
javax.servlet.ServletContextAttributeListener	Called when the web-app attributes change
javax.servlet.ServletRequestListener	Called when the request starts and stops
javax.servlet.ServletRequestAttributeListener	Called when request attributes change
javax.servlet.http.HttpSessionListener	Called when HTTP sessions start or stop
javax.servlet.http.HttpSessionAttributeListener	Called when HTTP sessions attributes change
javax.servlet.http.HttpSessionActivationListener	Called when HTTP sessions passivate or activate

<listener> Attributes
ATTRIBUTE	DESCRIPTION
listener-class	classname of the listener implementation
init	IoC initialization of the listener

<listener> schema

element listener {
  listener-class,
  init?
}

<login-config>

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
ATTRIBUTE	DESCRIPTION
auth-method	Authentication method, either BASIC for HTTP Basic Authentication, FORM for form based authentication, or DIGEST for HTTP Digest Authentication.
authenticator	Specifies the authenticator to use to lookup users and passwords.
class	Defines a custom class which extends com.caucho.server.security.AbstractLogin
form-login-config	Configuration for form login.
init	Initialization for the custom login class
realm-name	The 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 {
  class?
  & auth-method?
  & authenticator?
  & form-login-config?
  & init?
  & realm-name?

<mime-mapping>

child of <web-app>

Maps url patterns to mime-types.

<mime-mapping> Attributes
ATTRIBUTE	DESCRIPTION
extension	url extension
mime-type	the mime-type

<mime-mapping> schema

element mime-mapping {
  extension,
  mime-type
}

Example: WEB-INF/resin-web.xml

<web-app xmlns="http://caucho.com/ns/resin">

  <mime-mapping>
    <extension>.foo</extension>
    <mime-type>text/html</mime-type>
  </mime-mapping>

  <!-- resin shortcut syntax -->
  <mime-mapping extension='.bar'
                mime-type='text/html'/>

</web-app>

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

<multipart-form>

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
ATTRIBUTE	DESCRIPTION	DEFAULT
upload-max	maximum 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 {
  enable?
  & upload-max?
}

<path-mapping>

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
ATTRIBUTE	DESCRIPTION
url-pattern	A pattern matching the url: /foo/, /foo, or .foo
<url-regexp>	A regular expression matching the portion of the url that follows the context path
real-path	The 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="http://caucho.com/ns/resin">

<path-mapping url-pattern='/resin/*'
              real-path='e:\resin'/>

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

</web-app>

<protocol>

child of <servlet>,<servlet-mapping>

<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
ATTRIBUTE	DESCRIPTION
class	Classname of the protocol driver implementing ProtocolServletFactory
init	Optional IoC initialization for the protocol driver
uri	Protocol configuration shortcut

Current drivers
URI SCHEME	DESCRIPTION
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?
}

<redeploy-check-interval>

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 {
  r_period-Type
}

<redeploy-mode>

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
MODE	DESCRIPTION
automatic	checks for redeployment and auto-redeploy if modified
manual	does not check for redeployment. Only checks if manual (JMX)

<redeploy-mode> schema

element redeploy-mode {
  automatic | manual
}

<rewrite-real-path>

child of <cluster>,<host>,<web-app>

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

<rewrite-real-path> Attributes
ATTRIBUTE	DESCRIPTION
real-path	specifies the URL to real-path mapping
regexp	a regular expression matching a URL
replacement	specifies a replacement pattern for URL to URL rewriting
rewrite	rewrites a URL to another URL as a preprocessing-step
target	specifies the target for URL to real-path mapping

<rewrite-real-path> schema

element rewrite-real-path {
  element rewrite {
    regexp
    & replacement
  }*

  & element rewrite {
    regexp
    & target
  }*
}

Example: aliasing /foo to /bar

<web-app xmlns="http://caucho.com/ns/resin">

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

</web-app>

<root-directory>

child of <resin>,<cluster>,<host>,<web-app>

<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 {
  r_path-Type
}

Example: cluster root-directory

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <root-directory>/var/resin/app-tier</root-directory>

        <server id="a" ...>

        <host host-name="www.foo.com">
    </cluster>
</resin>

<secure>

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 {
  r_boolean-Type
}

<security-constraint>

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
ATTRIBUTE	DESCRIPTION
auth-constraint	Defines a security condition based on a logged-in user's role
constraint	Defines a custom security condition
ip-constraint	Defines a security condition based the remote IP address
role-name	Defines role-name requirement
url-pattern	URL pattern to match the security constraint
user-data-constraint	Defines SSL or non-SSL requirements
web-resource-collection	URL patterns and HTTP methods defining the constraint

<security-constraint> schema

element security-constraint {
  auth-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="http://caucho.com/ns/resin">

<security-constraint>
  <web-resource-collection>
    <url-pattern>/*</url-pattern>
  </web-resource-collection>
  <auth-constraint role-name='user'>
</security-constraint>

</web-app>

<servlet>

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
ATTRIBUTE	DESCRIPTION
init	Resin-IoC initialization
init-param	Initialization parameters
load-on-startup	Initializes the servlet when the server starts.
protocol	Protocol configuration for Resin remoting.
run-at	Times to execute the servlet automatically.
servlet-name	The servlet's name (alias)
servlet-class	The servlet's class (In Resin, defaults to servlet-name)

<servlet> schema

element servlet {
  servlet-name
  < (servlet-class | jsp-file)
  < init*
  < init-param*
  < load-on-startup?
  < protocol?
  < run-as?
  < run-at?
}

Example: WEB-INF/resin-web.xml

<web-app xmlns="http://caucho.com/ns">

  <servlet>
    <servlet-name>hello</servlet-name>
    <servlet-class>test.HelloWorld</servlet-class>
    <init-param>
      <param-name>title</param-name>
      <param-value>Hello, World</param-value>
    </init-param>
  </servlet>

  <!-- using Resin shortcut syntax -->
  <servlet servlet-name='cron'
           servlet-class='test.DailyChores'>
    <init-param title='Daily Chores'/>
    <load-on-startup/>
    <run-at>3:00</run-at>
  </servlet>

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

</web-app>

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="http://caucho.com/ns/resin">
  <servlet servlet-name='foo-a'>
    <servlet-class>test.FooServlet</servlet-class>
    <init-param name='foo-a sample'/>
  </servlet>

  <servlet servlet-name='foo-b'>
    <servlet-class>test.FooServlet</servlet-class>
    <init-param name='foo-b sample'/>
  </servlet>
</web-app>

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-class="com.caucho.servlets.DirectoryServlet"/>

  <servlet servlet-name="file"
           servlet-class="com.caucho.servlets.FileServlet"/>

  <servlet servlet-name="jsp"
           servlet-class="com.caucho.jsp.JspServlet"/>

  <servlet servlet-name="xtp"
           servlet-class="com.caucho.jsp.XtpServlet"/>

<servlet servlet-name="j_security_check"
         servlet-class="com.caucho.server.security.FormLoginServlet"/>

<servlet-mapping>

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
ATTRIBUTE	DESCRIPTION
init	Resin-IoC configuration of the servlet.
protocol	Defines the optional remoting protocol.
servlet-class	The servlet-mapping can define the servlet directly as a shortcut.
servlet-name	The servlet name
url-pattern	A pattern matching the url: /foo/, /foo, or .foo
<url-regexp>	A regular expression matching the portion of the url that follows the context path

<servlet-mapping> schema

element servlet-mapping {
  init?
  & protocol?
  & servlet-class?
  & servlet-name?
  < url-pattern*
  < url-regexp*
}

Example: WEB-INF/resin-web.xml <servlet-mapping>

<web-app xmlns="http://caucho.com/ns/resin">

  <servlet>
    <servlet-name>hello</servlet-name>
    <servlet-class>test.HelloWorld</servlet-class>
  </servlet>

  <servlet-mapping>
    <url-pattern>/hello.html</url-pattern>
    <servlet-name>hello</servlet-name>
  </servlet-mapping>

  <!-- resin shortcut syntax -->
  <servlet-mapping url-pattern='*.xtp'
                   servlet-name='com.caucho.jsp.XtpServlet'/>

</web-app>

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="http://caucho.com/ns/resin">

  <!-- 
    used with urls like 
    http://localhost:8080/servlets/test.HelloServlet 
  -->
  <servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/>

</web-app>

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

<cluster>

<web-app-default>
  <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"/>
</web-app-default>
</cluster>

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
ATTRIBUTE	DESCRIPTION
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)

<servlet-regexp>

Maps URL by regular expressions to custom servlets.

<servlet-regexp> schema

element servlet-regexp {
  init?
  & servlet-class?
  & servlet-name?
  & url-regexp
}

<servlet-regexp url-regexp="/([^.]*).do"
                servlet-class="qa.\${regexp[1]}Servlet">
  <init a="b"/>
</servlet-regexp>

<session-config>

<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
ATTRIBUTE	DESCRIPTION	DEFAULT
always-load-session	Reload data from the store on every request	false
always-save-session	Save session data to the store on every request	false
enable-cookies	Enable cookies for sessions	true
enable-url-rewriting	Enable URL rewriting for sessions	true
cookie-version	Version of the cookie spec for sessions	1.0
cookie-domain	Domain for session cookies	none
cookie-domain-regexp	Regex for cookies-domain for multi-domain webapps	none
cookie-max-age	Max age for persistent session cookies	none
cookie-length	Maximum length of the cookie
ignore-serialization-errors	When persisting a session, ignore any values which don't implement java.io.Serializable	true
invalidate-after-listener	If true, invalidate the sessions after the session listeners have been called
reuse-session-id	Reuse the session id even if the session has timed out. A value of false defeats single signon capabilities. (resin 2.0.4)	true
session-max	Maximum active sessions	8192
session-timeout	The session timeout in minutes, 0 means never timeout.	30 minutes
serialization-type	Use one of "java" or "hessian" for serialization, hessian is significantly faster and smaller (resin 3.1.2)	java
serialize-collection-type	For hessian serialization, ignore the collection type when serializing lists (disable for some Hibernate lists)	true
save-mode	When to save sessions, one of "before-headers", "after-request", or "on-shutdown"	after-request
use-persistent-store	Uses the current persistent-store to save sessions. (resin 3.0.8)	none

<session-config> schema

element session-config {
  always-load-session?
  & always-save-session?
  & cookie-append-server-index?
  & cookie-domain?
  & cookie-domain-regexp?
  & 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'>

  <session-config>
     <!-- 2 hour timeout -->
     <session-timeout>120</session-timeout>
     <session-max>4096</session-max>
  </session-config>

</web-app>

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

<shutdown-wait-max>

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 {
  r_period-Type
}

<statistics-enable>

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 {
  r_boolean-Type
}

<strict-mapping>

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 {
  r_boolean-Type
}

Example: enabling strict-mapping in resin-web.xml

<web-app xmlns="http://caucho.com/ns/resin">
  <strict-mapping>true</strict-mapping>
</web-app>

<user-data-constraint>

child of <security-constraint>

Restricts access to secure transports, such as SSL

<user-data-constraint> Attributes
ATTRIBUTE	DESCRIPTION
transport-guarantee	Required transport properties. NONE, INTEGRAL, and CONFIDENTIAL are allowed values.

<user-data-constraint> schema

element user-data-constraint {
  transport-guarantee
}

<web-app>

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
ATTRIBUTE	DESCRIPTION	DEFAULT
active-wait-time	how long a thread should wait for the web-app to initialize before returning a 503-busy.	15s
archive-path	Specifies the location of the web-app's .war file.	n/a
context-path	Specifies the URL prefix for the web-app.	the id value
id	The url prefix selecting this application.	n/a
redeploy-mode	'automatic' or 'manual', see <redeploy-mode>	automatic
redeploy-check-interval	how often to check the .war archive for redeployment	60s
root-directory	The 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-mode>	automatic
startup-priority	specifies a priority for web-app startup to force an ordering between webapps	-1
url-regexp	A 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'>

  ...

</host>

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='/~([^/]*)'
           root-directory='/home/$1/public_html'>

    ...

  </web-app>

</host>

<web-app-default>

child of <cluster>

<web-app-default> defines default values for any web-app in the cluster.

Example: web-app-default

<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">

        <web-app-default>
            <servlet servlet-name="resin-php"
                     servlet-class="com.caucho.quercus.servlet.QuercusServlet"/>

            <servlet-mapping url-pattern="*.php"
                             servlet-name="resin-php"/>
        </web-app-default>

        <host id="">
          ...
    </cluster>
</resin>

<web-app-deploy>

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
ATTRIBUTE	DESCRIPTION	DEFAULT
archive-directory	directory containing the .war files	value of path
dependency-check-interval	How often to check the .war files for a redeploy	60s
expand-cleanup-fileset	defines the files which should be automatically deleted when an updated .war expands	all files
expand-directory	directory where wars should be expanded	value of path
expand-prefix	prefix string to use when creating the expansion directory, e.g. _war_
expand-preserved-fileset	defines the files which should be kept when an updated .war expands	all files
expand-suffix	prefix string to use when creating the expansion directory, e.g. .war
path	The path to the webapps directory	required
redeploy-mode	"automatic" or "manual"	automatic
require-file	additional files to use for dependency checking for auto restart
startup-mode	"automatic", "lazy" or "manual"	automatic
url-prefix	url-prefix added to all expanded webapps	""
versioning	if true, use the web-app's numeric suffix as a version	false
web-app-default	defaults to be applied to expanded web-apps
web-app	overriding configuration for specific web-apps

<web-app-deploy> schema

element web-app-deploy {
  archive-directory?
  expand-cleanup-fileset?
  expand-directory?
  expand-prefix?
  expand-preserve-fileset?
  expand-suffix?
  path?
  redeploy-check-interval?
  redeploy-mode?
  require-file*
  startup-mode?
  url-prefix?
  versioning?
  web-app-default*
  web-app*
}

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="http://caucho.com/ns/resin">
<cluster id="">
<host id="">

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

</host>
</cluster>
</resin>

versioning

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.

The expand-preserve-fileset attribute lets you keep files for a redeployment, which can improve restart times. Normally, Resin will delete all files for an update, including the compiled files for JSP, which forces Resin to recompile JSP files, even if they haven't changed in the update. If you add the expand-preserve-fileset, Resin will only recompile the JSP files that have changed.

<web-resource-collection>

child of <security-constraint>

Specifies a collection of areas of the web site for security purposes. See Resin security for an overview.

<web-resource-collection> Attributes
ATTRIBUTE	DESCRIPTION
web-resource-name	a name for a web resource collection
description
url-pattern	url patterns describing the resource
http-method	HTTP methods to be restricted.
method

<web-resource-collection> schema

element web-resource-collection {
  url-method*
  & http-method*
  & web-resource-name?
}

<welcome-file-list>

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 {
  string
  | welcome-file*
}

Example: WEB-INF/resin-web.xml

<web-app xmlns="http://caucho.com/ns/resin">
  <welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>index.xtp</welcome-file>
    <welcome-file>home.xtp</welcome-file>
  </welcome-file-list>
</web-app>

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

Example: WEB-INF/resin-web.xml

<web-app xmlns="http://caucho.com/ns/resin">
  <welcome-file-list>
    index.jsp, index.xtp, home.xtp
  </welcome-file-list>
</web-app>

default in $RESIN_HOME/conf/app-default.xml is index.xtp, index.jsp, index.html.