<document>
<parents>web-app-default, web-app</parents>

Specifies Expires times for cacheable pages.

cache-mapping is intended to provide Expires times for pages that have Last-Modified or ETags specified, but do not wish to hard-code the Expires timeout in the servlet. For example, Resin's FileServlet relies on cache-mapping to set the expires times for static pages.

url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the url
expiresA time interval.

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

<deftable>
SuffixMeaning
sseconds
mminutes
hhours
Ddays
</deftable>

- 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 id='/'> <cache-mapping url-pattern='/*' expires='10'/> <cache-mapping url-pattern='*.gif' expires='15m'/> </web-app> <parents>web-app-default, web-app</parents>

Specifies configuration files for the web-app.

The use of files like WEB-INF/web.xml and WEB-INF/resin-web.xml are configured using <config-file>. You can add application-specific configuration files using the <config-file> tag.

Configuration files will be read and applied in the order they are specified.

... <config-file>WEB-INF/web.xml</config-file> <config-file>WEB-INF/resin-web.xml</config-file> ... <parents>host, web-app</parents>

Specifies ear expansion.

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

pathThe path to the deploy directoryrequired
expand-pathdirectory where ears should be expandedvalue of path
<parents>web-app-default, web-app</parents>

Configures JSP behavior.

auto-compileAutomatically compile changed JSP filestrue
el-ignoredIgnore EL expressions in JSP textfalse
fast-jstlOptimize JSTL JSP compilationtrue
ignore-el-exceptionIgnore exceptions generated in EL expressionstrue
is-xmlDefault JSP pages to use XML syntaxfalse
precompileTry to load precompiled JSP pagestrue
recompile-on-errorRecompile the JSP file when an Error occurs in loadingfalse
require-sourceReturn 404 when JSP source is deletedfalse
dependency-check-intervalHow often to check the jsp for changes, -1 disablesinherited
sessionCreates sessions for each JSP pagetrue
velocity-enabledEnable Velocity statementsfalse

The class that corresponds to <jsp> is

<parents>web-app-default, 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.

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.

<parents>web-app-default, 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.

url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the url
real-pathThe prefix of the real path. When used with url-regexp, allows substitution variables like $1.
<example> <web-app id='/'> <path-mapping url-pattern='/resin/*' real-path='e:\resin'/> <path-mapping url-regexp='/~([^/]*)' real-path='e:\home\$1'/> </web-app>

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

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

<example> <web-app> <strict-mapping>true</strict-mapping> </web-app> <parents>server, host-default, host</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-default, host, WEB-INF/web.xml, WEB-INF/resin-web.xml</parents>

web-app configures a web application.

idThe url prefix selecting this application.n/a
url-regexpA regexp to select this application.n/a
document-directoryThe document 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
redeploy-mode`automatic' or `manual', see Startup and Redeploy Mode automatic

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

path The path to the webapps directory required
url-prefix url-prefix added to all expanded webapps ""
expand-path directory where wars should be expanded value of path
lazy-init true if web-apps should only be initialized when first used false
versioning if true, versioned applications are served according to the base-name, e.g. webapps/foo-1.1 is served as /foo. false
web-app-default defaults to be applied to expaned web-apps
web-app overriding configuration for specific web-apps

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.

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

Resin implements the Servlet 2.4 specification.

<parents>web-app</parents>

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

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

Defines a filter alias for later mapping.

filter-nameThe filter's name (alias)
filter-classThe filter's class (defaults to filter-name), which extends
init-paramInitialization parameters, see FilterConfig.getInitParameter(String).

The following example defines a filter alias 'image'

<example> <web-app id='/'> <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.

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

filter-nameThe filter name
url-patternA pattern matching the url: /foo/*, /foo, or *.foo
dispatcher
url-regexpA regular expression matching the url
filter-nameThe filter name can use replacement vars from url-regexp like $1. It can also specify a class name directly like test.HelloWorldn/a
<example> <web-app> <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>

Defines a servlet alias for later mapping using .

servlet-nameThe servlet's name (alias)
servlet-classThe servlet's class (In Resin, defaults to servlet-name)
init-paramInitialization parameters
load-on-startupInitializes the servlet when the server starts.
run-atTimes to execute the servlet automatically, A Resin extension.
<web-app id='/'> <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> <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.

servlet-nameThe servlet namen/a
url-patternA pattern matching the url: /foo/*, /foo, or *.foon/a
url-regexpA regular expression matching the urln/a
servlet-nameThe servlet name can use replacement vars from url-regexp like $1. It can also specify a class name directly like test.HelloWorldn/a
<web-app id='/'> <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>

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 id='/'> <!-- 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.

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

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.

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

Session configuration parameters.

session-timeoutThe session timeout in minutes, 0 means never timeout.30 minutes

Resin add's a number of session-config tags.

session-maxMaximum active sessions4096
enable-cookiesEnable cookies for sessions. (resin 1.1)true
enable-url-rewritingEnable URL rewriting for sessions. (resin 1.1)true
cookie-versionVersion of the cookie spec for sessions. (resin 1.2)1.0
cookie-domainDomain for session cookies. (resin 1.2)none
cookie-max-ageMax age for persistent session cookies. (resin 2.0)none
cookie-lengthMaximum length of the cookie. (resin 2.1.1)Integer.MAX_VALUE
file-storePersistent sessions using a file store. (resin 1.2)none
use-persistent-storeUses the current persistent-store to save sessions. (resin 3.0.8)none
always-load-sessionReload data from the store on every request. (resin 1.2)false
always-save-sessionSave session data to the store on every request. (resin 1.2)false
save-only-on-shutdownOnly save session when the application shuts down. (resin 1.2.3)false
reuse-session-idReuse the session id even if the session has timed out. (resin 2.0.4)true
ignore-serialization-errorsWhen persisting a session, ignore any values which don't implement java.io.Serializablefalse
invalidate-after-listener. (resin 3.0)

By default, both `enable-cookies` and `enable-url-rewriting` are true. To force url rewriting, you would create a configuration like:

<example> <web-app id='/'> <session-config enable-cookies='false' enable-url-rewriting='true'/> </web-app>

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

<parents>web-app-default, web-app</parents>

Maps url patterns to mime-types.

extensionurl extension
mime-typethe mime-type
<example> <web-app id='/'> <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-default, web-app</parents> <default>in $RESIN_HOME/conf/app-default.xml is index.xtp, index.jsp, index.html.</default>

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.

<example> <web-app id='/'> <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-app id='/'> <welcome-file-list> index.jsp, index.xtp, home.xtp </welcome-file-list> </web-app> <parents>web-app-default, web-app</parents>
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

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> <error-page> <error-code>404</error-code> <location>/file_not_found.jsp</location> </error-page> </web-app> <web-app id='/foo'> <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> <deftable>
AttributeType
javax.servlet.error.status_codejava.lang.Integer
javax.servlet.error.messagejava.lang.String
javax.servlet.error.request_urijava.lang.String
javax.servlet.error.servlet_namejava.lang.String
javax.servlet.error.exceptionjava.lang.Throwable
javax.servlet.error.exception_typejava.lang.Class
<parents>web-app-default, 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.

Security constraints can also be custom classes.

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

Specifies a collection of areas of the web site.

web-resource-namea name for a web resource collection
description
url-patternurl patterns describing the resource
http-methodHTTP methods to be restricted.
method
<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.

role-nameRoles which are allowed to access the resource.
<parents>security-constraint</parents>

Restricts access to secure transports, such as SSL

transport-guaranteeRequired transport properties. NONE, INTEGRAL, and CONFIDENTIAL are allowed values.
<parents>security-constraint</parents>

Defines a custom constraint.

resin:typeA class that extends
initinitialization parameters, set in the object using Bean-style setters and getters
<parents>web-app-default, web-app</parents> <default>no authentication</default>
auth-methodAuthentication method, either BASIC for HTTP Basic Authentication, FORM for form based authentication, or DIGEST for HTTP Digest Authentication.
realm-nameThe realm name to use in HTTP authentication
form-login-configConfiguration for form login, see
typeDefines a custom class which extends `com.caucho.server.security.AbstractLogin`
initInitialization for the custom login class

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

HTTP digest authentication is discussed in Digest Passwords.

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

form-login-pageThe page to be used to prompt the user loginnone
form-error-pageThe error page for unsuccessful loginnone
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

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.

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.

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

<example> <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-default, web-app</parents> <parents>web-app-default, web-app</parents>
</document>