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


 

Resin Documentation

home company docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web 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>.

See Also

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

<access-log>

child of <web-app>

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

<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-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.conf explicit archive location
<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>

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

ATTRIBUTEDESCRIPTION
role-nameRoles which are allowed to access the resource.
<auth-constraint> schema
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.

Example: WEB-INF/resin-web.xml auth constraints
<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>

<cache-mapping>

child of <web-app>

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

See caching for more information.

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

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

ATTRIBUTEDESCRIPTIONDEFAULT
expiresA time interval to be used for the HTTP Expires header.
max-ageA time interval to be used for the "Cache-Control max-age=xxx" header. max-age affects proxies and browsers.
s-max-ageA time interval to be used for the "Cache-Control s-max-age=xxx" header. s-max-age affects proxy caches (including Resin), but not browsers.
url-patternA pattern matching the url:/foo/*, /foo, or *.foo
url-regexpA regular expression matching the url

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

SUFFIXMEANING
sseconds
mminutes
hhours
Ddays
<cache-mapping> schema
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.
Example: cache-mapping in resin-web.xml
<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.

ATTRIBUTEDESCRIPTION
resin:typeA class that extends AbstractConstraint
initinitialization 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
ATTRIBUTEDESCRIPTION
param-nameNamed parameter
param-valueParameter value
fooParameter name
<context-param> schema
element context-param {
  (param-name, param-value)*
  | (attribute * { string })*
  | (element * { string })*
}
Example: context-param in resin-web.xml
<web-app xmlns="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 all Cookies generated from the web-app. The Http-Only attribute can add security to a website by not forwarding HTTP cookies to SSL HTTPS requests.

<cookie-http-only> schema
element cookie-http-only {
  r_boolean-Type
}
Example: <cookie-http-only> in resin.conf
<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>

<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
ATTRIBUTEDESCRIPTIONDEFAULT
archive-pathThe path to the directory containing ear filespath
ear-defaultresin.conf default configuration for all ear files, e.g. configuring database, JMS or EJB defaults.
expand-cleanup-filesetSpecifies the files which should be automatically deleted when a new .ear version is deployed.
expand-directorydirectory where ears should be expandedvalue of path
expand-prefixautomatic prefix of the expanded directory_ear_
expand-suffixautomatic suffix of the expanded directory
lazy-initif true, the ear file is only started on first accessfalse
pathThe path to the deploy directoryrequired
redeploy-mode"automatic" or "manual". If automatic, detects new .ear files automatically and deploys them.automatic
url-prefixoptional URL prefix to group deployed .ear files
<ear-deploy> schema
element ear-deploy {
  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>
ATTRIBUTEDESCRIPTION
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
Request attributes for error handling
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
<error-page> schema
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.

Example: 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>
Example: Catching Exceptions
<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:

Example: /file_not_found.jsp
<%@ 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>

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.

ATTRIBUTEDESCRIPTION
filter-nameThe filter's name (alias)
filter-classThe filter's class (defaults to filter-name), which extends javax.servlet.Filter
initResin-IoC initialization configuration, see Resin-IoC
init-paramInitialization parameters, see FilterConfig.getInitParameter
<filter> schema
element filter {
  filter-name
  & filter-class
  & init*
  & init-param*
}

The following example defines a filter alias 'image'

Example: WEB-INF/resin-web.xml
<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-INF/resin-web.xml
<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>

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

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

<form-login-config> attributes
ATTRIBUTEDESCRIPTIONDEFAULT
form-login-pageThe page to be used to prompt the user login
form-error-pageThe error page for unsuccessful login
internal-forwardUse an internal redirect on success instead of a sendRedirectfalse
form-uri-priorityIf true, the form's j_uri will override a stored URIfalse

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.

ATTRIBUTEDESCRIPTION
j_security_checkThe form's mandatory action
j_usernameThe user name
j_passwordThe password
j_uriOptional Resin extension for the successful display page.
j_use_cookie_authOptional Resin extension to allow cookie login.
<form-login-config> schema
element form-login-config {
  form-login-page,
  form-error-page,
  internal-forward,
  form-uri-priority
}

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

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>

<idle-time>

child of <web-app>

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

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

<idle-time> schema
element idle-time {
  r_period-Type
}

<jsp>

child of <web-app>

Configures JSP behavior.

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

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

<jsp-config> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
url-patternselects the URLs which this jsp-config applies to
el-ignoredIf true, EL expressions are ignoredfalse
page-encodingDefines the default page encoding for the JSP fileISO-8859-1
scripting-invalidIf true, Java scripting is forbidded in the JSP pagefalse
trim-directive-whitespacesIf true, extra whitespace is trimmed around JSP directivesfalse
is-xmlIf true, for XML syntax for JSP pagesfalse
include-preludeIncludes JSP fragments before the JSP page as headers
include-codaIncludes JSP fragments before the JSP page as footers
<jsp-config> schema
element jsp-config {
  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> Attributes
ATTRIBUTEDESCRIPTION
listener-classclassname of the listener implementation
initIoC initialization of the listener
listener interfaces
INTERFACEDESCRIPTION
javax.servlet.ServletContextListenerCalled when the web-app starts and stops
javax.servlet.ServletContextAttributeListenerCalled when the web-app attributes change
javax.servlet.ServletRequestListenerCalled when the request starts and stops
javax.servlet.ServletRequestAttributeListenerCalled when request attributes change
javax.servlet.http.HttpSessionListenerCalled when HTTP sessions start or stop
javax.servlet.http.HttpSessionAttributeListenerCalled when HTTP sessions attributes change
javax.servlet.http.HttpSessionActivationListenerCalled when HTTP sessions passivate or activate
<listener> 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
ATTRIBUTEDESCRIPTION
auth-methodAuthentication method, either BASIC for HTTP Basic Authentication, FORM for form based authentication, or DIGEST for HTTP Digest Authentication.
authenticatorSpecifies the authenticator to use to lookup users and passwords.
classDefines a custom class which extends com.caucho.server.security.AbstractLogin
form-login-configConfiguration for form login.
initInitialization for the custom login class
realm-nameThe realm name to use in HTTP authentication

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

HTTP digest authentication is discussed in Digest Passwords.

<login-config> schema
element login-config {
  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
ATTRIBUTEDESCRIPTION
extensionurl extension
mime-typethe 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
ATTRIBUTEDESCRIPTIONDEFAULT
upload-maxmaximum size of an upload request (in kb).no limit

If the upload is larger than the limit or if multipart-form processing is disabled, Resin will not parse the request and will set an error message in the "caucho.multipart.form.error" request attribute. The "caucho.multipart.form.error.size" will contain the attempted upload size.

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

By default, multipart-form is disabled.

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

  & real-path
}
Example: resin-web.xml aliasing paths
<web-app xmlns="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 AbstractProtocolServletFactory interface and can register a URI alias to simplify configuration.

<protocol> Attributes
ATTRIBUTEDESCRIPTION
classClassname of the protocol driver implementing ProtocolServletFactory
initOptional IoC initialization for the protocol driver
uriProtocol configuration shortcut
Current drivers
URI SCHEMEDESCRIPTION
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?
}
Example: Hessian service in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin">

  <servlet-mapping url-pattern="/hello">
                    servlet-class="example.MyHello">
    <protocol uri="hessian:"/>
  </servlet-mapping>

</web-app>

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

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

Resource Tags

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

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.

Example: web-app database in resin-web.xml
<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:

Example: IoC bean in resin-web.xml
<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>

<rewrite-dispatch>

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

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

Example: Mediawiki dispatch in resin-web.xml
<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>

<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
ATTRIBUTEDESCRIPTION
real-pathspecifies the URL to real-path mapping
regexpa regular expression matching a URL
replacementspecifies a replacement pattern for URL to URL rewriting
rewriterewrites a URL to another URL as a preprocessing-step
targetspecifies the target for URL to real-path mapping
<rewrite-real-path> schema
element rewrite-real-path {
  element rewrite {
    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>

<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
ATTRIBUTEDESCRIPTION
auth-constraintDefines a security condition based on a logged-in user's role
constraintDefines a custom security condition
ip-constraintDefines a security condition based the remote IP address
role-nameDefines role-name requirement
url-patternURL pattern to match the security constraint
user-data-constraintDefines SSL or non-SSL requirements
web-resource-collectionURL patterns and HTTP methods defining the constraint
<security-constraint> content
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 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.

<servlet> Attributes
ATTRIBUTEDESCRIPTION
initResin-IoC initialization
init-paramInitialization parameters
load-on-startupInitializes the servlet when the server starts.
protocolProtocol configuration for Resin remoting.
run-atTimes to execute the servlet automatically.
servlet-nameThe servlet's name (alias)
servlet-classThe servlet's class (In Resin, defaults to servlet-name)
<servlet> schema
element servlet {
  servlet-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
ATTRIBUTEDESCRIPTION
initResin-IoC configuration of the servlet.
protocolDefines the optional remoting protocol.
servlet-classThe servlet-mapping can define the servlet directly as a shortcut.
servlet-nameThe servlet name
url-patternA pattern matching the url: /foo/*, /foo, or *.foo
url-regexpA regular expression matching the portion of the url that follows the context path
<servlet-mapping> schema
element servlet-mapping {
  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</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 context path. 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.

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

<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
ATTRIBUTEDESCRIPTIONDEFAULT
always-load-sessionReload data from the store on every requestfalse
always-save-sessionSave session data to the store on every requestfalse
enable-cookiesEnable cookies for sessionstrue
enable-url-rewritingEnable URL rewriting for sessionstrue
cookie-versionVersion of the cookie spec for sessions1.0
cookie-domainDomain for session cookiesnone
cookie-max-ageMax age for persistent session cookiesnone
cookie-lengthMaximum length of the cookie
ignore-serialization-errorsWhen persisting a session, ignore any values which don't implement java.io.Serializablefalse
invalidate-after-listenerIf true, invalidate the sessions after the session listeners have been called
reuse-session-idReuse the session id even if the session has timed out. A value of false defeats single signon capabilities. (resin 2.0.4)true
session-maxMaximum active sessions4096
session-timeoutThe session timeout in minutes, 0 means never timeout.30 minutes
serialization-typeUse one of "java" or "hessian" for serialization, hessian is significantly faster and smaller (resin 3.1.2)java
save-modeWhen to save sessions, one of "before-headers", "after-request", or "on-shutdown"after-request
use-persistent-storeUses the current persistent-store to save sessions. (resin 3.0.8)none
<session-config> schema
element session-config {
  always-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.

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

<shutdown-wait-max>

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

default 15s
<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-constraints> Attributes
ATTRIBUTEDESCRIPTION
transport-guaranteeRequired 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.

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

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.

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

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

<host id=''>

  <web-app url-regexp='/~([^/]*)'
           document-directory='/home/$1/public_html'>

    ...

  </web-app>

</host>

<web-app-default>

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

Establishes the defaults for a <web-app>.

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.

<host>
  <web-app-default>
    <servlet servlet-name='test'
             servlet-class='test.MyServlet'/>

    <servlet-mapping url-pattern='*.text' servlet-class='test'/>
  </web-app-default>
</host>

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

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 <document-directory> is used to match web-apps.

Example: resin.conf overriding web.xml
<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>

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.

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

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

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).
Leading companies worldwide with demand for reliability and high performance web applications including SalesForce.com, CNET, DZone and many more are powered by Resin.

home company docs 
app server