<document>
<localtoc/>

- Resources tags for beans, components, databases, @Stateless and @Stateful EJBs, JMS queues, etc.
- Security for a full description of Resin's authentication and authorization.
- Rewrite tags for Resin's rewrite-dispatch rewriting.

<parents>web-app</parents>

<access-log> configures a HTTP access log for an indivitual web-app. See access-log in the <host> tag for more information.

<parents>web-app</parents>

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

element active-wait-time { r_period-Type } <parents>web-app</parents>

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

element allow-servlet-el { r_boolean-Type } <parents>web-app</parents>

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

element archive-path { r_path-Type } <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> <host id=""> <web-app id="/foo" root-directory="/var/www/foo" archive-path="/var/www/wars/foo.war"/> </host> </cluster> </resin> <parents>security-constraint</parents>

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 <management> authentication as a default, the role name is resin-admin. (See Resin management.)

Attribute Description
role-name Roles which are allowed to access the resource.
element auth-constraint { description*, role-name* }

The following example protects the /admin subdirectory of a web-app by requiring a user to logon with Resin's <management> users, i.e. using the same requirement as /resin-admin.

<web-app xmlns="http://caucho.com/ns/resin"> <login uri="basic:"/> <security-constraint url-pattern="/admin/*"> <auth-constraint role-name="resin-admin"/> </security-constraint> </web-app> <parents>web-app</parents>

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

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

The time interval defaults to seconds, but will allow other periods:

<deftable>
Suffix Meaning
s seconds
m minutes
h hours
D days
</deftable> element cache-mapping { (url-pattern | url-regexp) & expires? & max-age? & s-max-age? }

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

<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> <parents>security-constraint</parents>

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

Attribute Description
resin:type A class that extends AbstractConstraint
init initialization parameters, set in the object using Bean-style setters and getters
element constraint { class & init? } <parents>web-app</parents>

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

Attribute Description
param-name Named parameter
param-value Parameter value
Parameter name
element context-param { (param-name, param-value)* | (attribute * { string })* | (element * { string })* } <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> <parents>web-app</parents>

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.

element cookie-http-only { r_boolean-Type } <resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> <host id="www.foo.com"> <web-app id="" root-directory="/var/www/foo"> <cookie-http-only>true</cookie-http-only> <web-app id=""> </host> <host id="www.foo.com:443"> <web-app id="" root-directory="/var/www/foo-secure"> <secure/> <web-app id=""> </host> </cluster> </resin> <parents>host, web-app</parents>

Specifies ear expansion.

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

Attribute Description Default
archive-path The path to the directory containing ear files path
ear-default resin.conf 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
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? } <parents>web-app</parents>
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
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
element error-page { (error-code | exception-type)? & location }

By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages. Applications can customize the response generated for errors.

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

The error page can use 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>

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

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
element filter { filter-name & filter-class & init* & init-param* }

The following example defines a filter alias '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>

The full Servlet 2.3 syntax for init-param is supported as well as a simple shortcut.

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

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 servlet class directly or it can specify a servlet alias defined by `filter`.

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 <g>context path</g>
element filter-mapping { (url-pattern | url-regexp | servlet-name)+ & filter-name & dispatcher* } <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>

`url-regexp` matches the portion of the url that follows the <g>context path</g>. A webapp in `webapps/ROOT`, and a url `http://localhost/foo/hello.html` will have a value of `"/foo/hello.html"` for the purposes of the regular expression match. A webapp in `webapps/baz` and a url `http://localhost/baz/hello.html` will have a url of `"/hello.html"` for the purposes of the regular expression match, because "/baz" is the context path.

<parents>login-config</parents>

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.

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

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.

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.
element form-login-config { form-login-page, form-error-page, internal-forward, form-uri-priority }

The following is an example of a servlet-standard login page:

<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> <parents>web-app</parents>

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.

element idle-time { r_period-Type } <parents>web-app</parents>

Configures JSP behavior.

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
fast-jsf Optimize JSF 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
element jsp { auto-compile & deferred-syntax-allowed-as-literal? & dependency-check-interval? & el-ignored? & fast-jsf? & 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.

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
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* } <default>false</default>

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

element lazy-servlet-validate { r_boolean-Type }

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

Attribute Description
listener-class classname of the listener implementation
init IoC initialization of the listener
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
element listener { listener-class, init? } <parents>web-app</parents> <default>no authentication</default>

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

See also: Resin security for an overview.

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.

element login-config { class? & auth-method? & authenticator? & form-login-config? & init? & realm-name? <parents>web-app</parents>

Maps url patterns to mime-types.

Attribute Description
extension url extension
mime-type the mime-type
element mime-mapping { extension, mime-type } <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

<parents>web-app</parents>

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.

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.

element multipart-form { enable? & upload-max? } <parents>web-app</parents>

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

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 <g>context path</g>
real-path The prefix of the real path. When used with url-regexp, allows substitution variables like $1.
element path-mapping { (url-pattern | url-regexp) & real-path } <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> <parents>servlet, servlet-mapping</parents>

<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 AbstractProtocolServletFactory interface and can register a URI alias to simplify configuration.

Attribute Description
class Classname of the protocol driver implementing ProtocolServletFactory
init Optional IoC initialization for the protocol driver
uri Protocol configuration shortcut
URI scheme Description
burlap: The burlap XML protocol
cxf: The CXF SOAP implementation
hessian: The Hessian protocol
xfire: The XFire SOAP implementation
element protocol { (class | uri) & init? } <web-app xmlns="http://caucho.com/ns/resin"> <servlet-mapping url-pattern="/hello"> servlet-class="example.MyHello"> <protocol uri="hessian:"/> </servlet-mapping> </web-app> <parents>web-app</parents> <default>60s</default>

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

element redeploy-check-interval { r_period-Type } <parents>web-app</parents> <default>automatic</default>

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

<deftable>
Mode Description
automatic checks for redeployment and auto-redeploy if modified
manual does not check for redeployment. Only checks if manual (JMX)
element redeploy-mode { automatic | manual } <parents>cluster, host, web-app</parents>

See the Resource tag documentation for a full list of resources available to the web-app.

All resource tags are available to the <web-app>, like databases, IoC beans and components, EJB stateful, stateless and message beans, JMS queues, remote clients, etc.

<web-app xmlns="http://caucho.com/ns/resin"> <database jndi-name="jdbc/test"> <driver type="org.postgresql.Driver"> <url>jdbc:postgresql://localhost/test</url> <user>caucho</user> </driver> </database> </web-app>

Or IoC-configured Beans:

<web-app xmlns="http://caucho.com/ns/resin"> <bean jndi-name="jdbc/test" type="example.Theater> <init name="Balboa Theater"> <movie title="Attack of the Killer Tomatoes"/> <movie title="Snakes on a Plane"/> <movie title="Casablanca"/> </init> </bean> </web-app> <parents>cluster, host, web-app</parents>

<rewrite-dispatch> defines a set of rewriting rules for dispatching and forwarding URLs. Applications can use these rules to redirect old URLs to their new replacements.

See rewrite-dispatch for more details.

<web-app xmlns="http://caucho.com/ns/resin"> <rewrite-dispatch> <dispatch regexp="\.(php|gif|css|jpg|png)"/> <forward regexp="^" target="/index.php"/> </rewrite-dispatch> </web-app> <parents>cluster, host, web-app</parents>

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

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
element rewrite-real-path { element rewrite { regexp & replacement }* & element rewrite { regexp & target }* } <web-app xmlns="http://caucho.com/ns/resin"> <rewrite-real-path> <real-path regexp="^/foo" target="/bar"/> </rewrite-real-path> </web-app> <parents>web-app</parents>

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

element secure { r_boolean-Type } <parents>web-app</parents>

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.

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
element security-constraint { auth-constraint* & constraint* & ip-constraint* & role-name* & user-data-constraint* & url-pattern? & web-resource-collection* } <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>

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 SOAP or Hessian to handle remoting requests.

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

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

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

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

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.

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 <g>context path</g>
element servlet-mapping { init? & protocol? & servlet-class? & servlet-name? < url-pattern* < url-regexp* } <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</servlet-class> <servlet-name>hello</servlet-class> </servlet-mapping> <!-- resin shortcut syntax --> <servlet-mapping url-pattern='*.xtp' servlet-name='com.caucho.jsp.XtpServlet'/> </web-app>

`url-regexp` matches the portion of the url that follows the <g>context path</g>. A webapp in `webapps/ROOT`, and a url `http://localhost/foo/hello.html` will have a value of `"/foo/hello.html"` for the purposes of the regular expression match. A webapp in `webapps/baz` and a url `http://localhost/baz/hello.html` will have a url of `"/hello.html"` for the purposes of the regular expression match, because "/baz" is the context path.

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

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

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

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)

Maps URL by regular expressions to custom servlets.

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

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

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-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 false
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 4096
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
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
element session-config { always-load-session? & 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.

<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

The maximum time Resin will wait for requests to finish before closing the web-app.

<default>15s</default> element shutdown-wait-max { r_period-Type } <default>false</default>

<statistics-enable> enables more detailed statistics for the `WebAppMXBean` administration. The statistics gathering is disabled by default for performance reasons.

element statistics-enable { r_boolean-Type } <default>false, allowing /foo/bar.jsp/foo.</default>

Forces servlet-mapping to follow strict Servlet 2.2, disallowing PATH_INFO. Value is true or false.

element strict-mapping { r_boolean-Type } <web-app xmlns="http://caucho.com/ns/resin"> <strict-mapping>true</strict-mapping> </web-app> <parents>security-constraint</parents>

Restricts access to secure transports, such as SSL

Attribute Description
transport-guarantee Required transport properties. NONE, INTEGRAL, and CONFIDENTIAL are allowed values.
element user-data-constraint { transport-guarantee } <parents>host, web-app</parents>

web-app configures a web application.

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 Startup and 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 of the containing . Can use regexp replacement variables. A relative path constricted with the id or the regexp match
startup-mode 'automatic', 'lazy', or 'manual', see Startup and Redeploy 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

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.

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

<example> <host id=''> <web-app id='/apache' document-directory='/usr/local/apache/htdocs'> ... </host>

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

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

When the web-app is specified with a url-regexp, document-directory can use replacement variables ($2).

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

<example> <host id=''> <web-app url-regexp='/~([^/]*)' document-directory='/home/$1/public_html'> ... </web-app> </host> <parents>cluster, host, web-app</parents>

Establishes the defaults for a .

When initializing a web-app, all the tags in the web-app-defaults sections configure the web-app. In other words, the web-app-default value is essentially a macro that is cut-and-pasted before the web-app configuration.

web-app-default is used for defining server-wide behavior, like *.jsp handling, and for host-wide behavior.

<example> <host> <web-app-default> <servlet servlet-name='test' servlet-class='test.MyServlet'/> <servlet-mapping url-pattern='*.text' servlet-class='test'/> </web-app-default> </host> <parents>host, web-app</parents>

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.

Attribute Description Default
archive-directory directory containing the .war files value of path
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-suffix prefix string to use when creating the expansion directory, e.g. .war
path The path to the webapps directory required
redeploy-check-interval How often to check the .war files for a redeploy 60s
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 expaned web-apps
web-app overriding configuration for specific web-apps
element web-app-deploy { archive-directory? expand-cleanup-fileset? expand-directory? expand-prefix? expand-suffix? path? redeploy-check-interval? redeploy-mode? require-file* startup-mode? url-prefix? versioning? web-app-default* web-app* }

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

<resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> <host id=""> <web-app-deploy path="webapps"> <web-app context-path="/wiki" document-directory="wiki"> <context-param database="jdbc/wiki"> </web-app> </web-app-deploy> </host> </cluster> </resin>

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.

<parents>security-constraint</parents>

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

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
element web-resource-collection { url-method* & http-method* & web-resource-name? } <parents>web-app</parents>

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.

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

<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.</default>
</document>