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


 

Resin Documentation

home company blog 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>.

<access-log>

<access-log> configures the access log file.

As a child of <web-app>, overrides the definition in the <host> that the web-app is deployed in. As a child of <host>, overrides the definition in the <server> that the host is in.

The default archive format is

path + ".%Y%m%d" or
  path + ".%Y%m%d.%H" if rollover-period < 1 day.

The access log formatting variables follow the Apache variables:

format patterns
PATTERNDESCRIPTION
%bresult content length
%Dtime taken to complete the request in microseconds (since 3.0.16)
%hremote IP addr
%{xxx}irequest header xxx
%{xxx}oresponse header xxx
%{xxx}ccookie value xxx
%nrequest attribute
%rrequest URL
%sstatus code
%Srequested session id
%{xxx}trequest date with optional time format string.
%Ttime taken to complete the request in seconds
%uremote user
%Urequest URI
%vname of the virtual host serving the request

The default format is:

default access log format
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

resin:type allows for custom logging. Applications can extend a custom class from com.caucho.http.log.AccessLog. Resin-IoC initialization can be used to set bean parameters in the custom class.

<access-log> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
pathOutput path for the log entries, see "Log Paths".required
path-formatSelects a format for generating path names. The syntax is the same as for archive-format.optional
archive-formatthe format for the archive filename when a rollover occurs, see Rollovers. see below
auto-flushtrue to flush the memory buffer with each request. false
auto-flush-timesets time interval for flushing the memory buffers 60s
excludeaccess logging exclude patterns for request URIs. Access to matching URIs does not get logged.none
formatAccess log format.see above
hostname-dns-lookuplog the dns name instead of the IP address (has a performance hit).false
rollover-periodhow often to rollover the log. Specify in days (15D), weeks (2W), months (1M), or hours (1h). See "Rollovers". none
rollover-sizemaximum size of the file before a rollover occurs, in bytes (50000), kb (128kb), or megabytes (10mb). See "Rollovers". 1mb
rollover-countmaximum number of rollover files before the oldest ones get overwritten. See "Rollovers". 1mb
resin:typea class extending com.caucho.server.log.AccessLog for custom logging com.caucho.server.log.AccessLog
initResin-IoC initialization for the custom classn/a
<access-log> schema
element access-log {
  path?
  & path-format?
  & archive-format?
  $amp;auto-flush?
  & auto-flush-time?
  & exclude*
  & format?
  & hostname-dns-lookup?
  & rollover-period?
  & rollover-size?
  & rollover-count?
  & resin:type?
  & init?
}
Example: <access-log> in host configuration
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">

  <host id="">
    <access-log path='log/access.log'>
      <rollover-period>2W</rollover-period>
    </access-log>
  </host>
</cluster>
</resin>
Example: custom access log
<resin xmlns="http://caucho.com/ns/resin">

<cluster id="app-tier">

  <host id='foo.com'>

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

</cluster>
</resin>

<active-wait-time>

child of <web-app>

<active-wait-time> sets a 503 busy timeout for requests trying to access a restarting web-app. If the timeout expires before the web-app complete initialization, the request will return a 503 Busy HTTP response.

<active-wait-time> schema
element active-wait-time {
  r_period-Type
}

<allow-forward-after-flush>

child of <web-app>

The <allow-forward-after-flush> flag configures whether IllegalStateExcdeption is thrown when using forward() method after response has been committed. Flag configures behavior of servlet and jsp.

<allow-forward-after-flush> schema
element allow-forward-after-flush {
  r_boolean-Type
}

<allow-servlet-el>

child of <web-app>

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

<allow-servlet-el> schema
element allow-servlet-el {
  r_boolean-Type
}

<archive-path>

child of <web-app>

<archive-path> configures the location of the web-app's .war file. In some configurations, the .war expansion might not use the webapps/ directory, but will still want automatic war expantion.

<archive-path> schema
element archive-path {
  r_path-Type
}
Example: resin.xml explicit archive location
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <host id="">

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

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

<auth-constraint>

Requires that authenticated users fill the specified role. In Resin's JdbcAuthenticator, normal users are in the "user" role. Think of a role as a group of users.

The roles are defined by the authenticators (see Resin security). When using Resin's <resin:AdminAuthenticator> as a default, the role name is resin-admin. (See Resin management.)

<auth-constraint> Attributes
ATTRIBUTEDESCRIPTION
role-nameRoles which are allowed to access the resource.
<auth-constraint> schema
element auth-constraint {
  description*,

  role-name*
}

<cache-mapping>

child of <web-app>

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

See proxy-cache for more information.

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

<cache-mapping> does not automatically make dynamic (non-static) pages cacheable. Your servlets must already set the ETag (or Last-Modified) header to activate <cache-mapping>. For static resources, Resin's FileServlet sets the ETag header.

  • cache-mapping requires an enabled <proxy-cache>. If the cache is disabled, cache-mapping will be ignored.
  • cache-mapping does not automatically make a page cacheable. Only cacheable pages are affected by cache-mapping, i.e. pages with an ETag or Last-Modified.

The time intervals default to seconds, but will allow other <time intervals>.

<cache-mapping> Attributes
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-regexp>A regular expression matching the url
<cache-mapping> schema
element cache-mapping {
  (url-pattern | url-regexp)
  & expires?
  & max-age?
  & s-max-age?
}
Example: caching .gif files for 15 minutes
<web-app xmlns="http://caucho.com/ns/resin">

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

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

</web-app>

<constraint>

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

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

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

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

</cluster>
</resin>

<ear-deploy>

child of <host>,<web-app>

Specifies ear expansion.

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

<ear-deploy> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
archive-directoryThe path to the directory containing ear filespath
ear-defaultresin.xml default configuration for all ear files, e.g. configuring database, JMS or EJB defaults.
expand-cleanup-filesetSpecifies the files which should be automatically deleted when a new .ear version is deployed.
expand-directorydirectory where ears should be expandedvalue of path
expand-prefixautomatic prefix of the expanded directory_ear_
expand-suffixautomatic suffix of the expanded directory
lazy-initif true, the ear file is only started on first accessfalse
pathThe path to the deploy directoryrequired
redeploy-mode"automatic" or "manual". If automatic, detects new .ear files automatically and deploys them.automatic
url-prefixoptional URL prefix to group deployed .ear files
<ear-deploy> schema
element ear-deploy {
  path
  & archive-directory?
  & ear-default?
  & expand-cleanup-fileset?
  & expand-directory?
  & expand-path?
  & expand-prefix?
  & expand-suffix?
  & lazy-init?
  & redeploy-mode?
  & require-file*
  & url-prefix?
}

<error-page>

child of <web-app>

Allows applications to customize the response generated for errors. By default, Resin returns a 500 Servlet Error and a stack trace for exceptions and a simple 404 File Not Found for error pages. With <error-page>, you may specify a handler page for these errors.

The handler page has several request attributes set so that it may log, display, or otherwise use information about the error that occured. The following table describes the available attributes.

Request attributes for error handling
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> Attributes
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
<error-page> schema
element error-page {
  (error-code | exception-type)?
  & location
}
Catching File Not Found
<web-app xmlns="http://caucho.com/ns/resin">
  <error-page>
    <error-code>404</error-code>
    <location>/file_not_found.jsp</location>
  </error-page>
</web-app>
Catching Exceptions
<web-app xmlns="http://caucho.com/ns/resin">
   <error-page exception-type="java.lang.NullPointerException"
               location="/nullpointer.jsp"/>
</web-app>
Using request attributes to obtain information about the request that caused the error
<%@ page session="false" isErrorPage="true" %>

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

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

<filter>

child of <web-app>

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

<filter> Attributes
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*
}
Defining a filter name 'image'
<web-app xmlns="http://caucho.com/ns/resin">

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

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

</web-app>
init-param shortcut syntax
<web-app id='/'>

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

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

</web-app>

<filter-mapping>

child of <web-app>

Maps url patterns to filters. filter-mapping has two children, url-pattern and filter-name. url-pattern selects the urls which should execute the filter.

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

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

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

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

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

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

<form-login-config>

Configures authentication using forms. The login form has specific parameters that the servlet engine's login form processing understands. If the login succeeds, the user will see the original page. If it fails, she will see the error page.

The form itself must have the action j_security_check. It must also have the parameters j_username and j_password. Optionally, it can also have j_uri and j_use_cookie_auth. j_uri gives the next page to display when login succeeds. j_use_cookie_auth allows Resin to send a persistent cookie to the user to make following login easier.

j_use_cookie_auth gives control to the user whether to generate a persistent cookie. It lets you implement the "remember me" button. By default, the authentication only lasts for a single session.

<form-login-config> Attributes
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
Special form input names
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
}
Example: login.html
<form action='j_security_check' method='POST'>
<table>
<tr><td>User:<td><input name='j_username'>
<tr><td>Password:<td><input name='j_password'>
<tr><td colspan=2>hint: the password is 'quidditch'
<tr><td><input type=submit>
</table>
</form>

<jsp>

child of <web-app>

Configures JSP behavior.

<jsp> Attributes
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
ignore-el-exceptionIgnore exceptions generated in EL expressions. For debugging, set to falsetrue
is-xmlDefault JSP pages to use XML syntaxfalse
page-encodingSets the default page encodingISO-8859-1
precompileTry to load precompiled JSP pagestrue
print-null-as-blankIf true, expressions evaluating to null are not printedfalse
recompile-on-errorRecompile the JSP file when an Error occurs in loadingfalse
recycle-tagsReuse tag instances when possible for performancetrue
require-sourceReturn 404 when JSP source is deletedfalse
scriping-invalidDisables all Java scripting and expression in JSP pagesfalse
sessionCreates sessions for each JSP pagetrue
static-page-generates-classIf true, JSPs with no active content still generate a .classtrue
tld-dirrestricts the directory to scan for .tld files, improving startup performanceWEB-INF
tld-file-setadds an ant-style pattern for .tld scanningWEB-INF
trim-directive-whitespaceif true, trims whitespace around JSP directivesfalse
validate-taglib-schemaif true, validate .tld files against the .tld schema. Set to false to handle invalid .tld filestrue
velocity-enabledif true, velocity-style tags are allowedfalse
character-encodingSets JSP response character encoding; overrides character encoding defined at web-app level
<jsp> schema
element jsp {
  auto-compile
  & deferred-syntax-allowed-as-literal?
  & dependency-check-interval?
  & el-ignored?
  & fast-jstl?
  & ide-hack?
  & ignore-el-exception?
  & is-xml?
  & page-encoding?
  & precompile?
  & print-null-as-blank?
  & recompile-on-error?
  & recycle-tags?
  & require-source?
  & scripting-invalid?
  & session?
  & static-page-generates-class?
  & tld-dir?
  & tld-file-set?
  & trim-directive-whitespaces?
  & validate-taglib-schema?
  & velocity-enabled?
}

<jsp-config>

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

<jsp-config> Attributes
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 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> Attributes
ATTRIBUTEDESCRIPTION
listener-classclassname of the listener implementation
initIoC initialization of the listener
<listener> schema
element listener {
  listener-class,
  init?
}

<login-config>

child of <web-app>
default no authentication

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

See also: Resin security for an overview.

<login-config> Attributes
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-regexp>A 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>

<protocol> configures a remoting protocol for a Java bean. The bean is configured with the <servlet> and <servlet-mapping> tags, since it will process HTTP URL requests.

Protocol drivers extend the com.caucho.remote.server.AbstractProtocolServletFactory interface and can register a URI alias to simplify configuration.

<protocol> Attributes
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?
}

<redeploy-check-interval>

child of <web-app>
default 60s

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

<redeploy-check-interval> schema
element redeploy-check-interval {
  r_period-Type
}

<redeploy-mode>

child of <web-app>
default automatic

<redeploy-mode> specifies how Resin handles updates to web-apps and .war files. By default, Resin restarts web-apps when classes or configuration files change.

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

<rewrite-real-path>

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

<root-directory>

<root-directory> specifies the base directory for the contexts. All EL-style directory paths are relative to the root-directory.

<root-directory> schema
element root-directory {
  r_path-Type
}
Example: cluster root-directory
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <root-directory>/var/resin/app-tier</root-directory>

        <server id="a" ...>

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

<secure>

child of <web-app>

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

<secure> schema
element secure {
  r_boolean-Type
}

<security-constraint>

child of <web-app>

Specifies protected areas of the web site. Sites using authentication as an optional personalization feature will typically not use any security constraints. See Resin security for an overview.

Security constraints can also be custom classes.

See Resin security for an overview of security issues and configuration.

<security-constraint> Attributes
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> schema
element security-constraint {
  auth-constraint*
  & constraint*
  & ip-constraint*
  & role-name*
  & user-data-constraint*
  & url-pattern?
  & web-resource-collection*
}
Example: 'user' role required in WEB-INF/resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin">

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

</web-app>

<servlet>

Defines a servlet to process HTTP URL requests. The servlet class can either implement javax.servlet.Servlet to handle the HTTP request directly or it can use a remoting protocol like Hessian to handle remoting requests.

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

<servlet> Attributes
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-regexp>A regular expression matching the portion of the url that follows the context path
<servlet-mapping> schema
element servlet-mapping {
  init?
  & protocol?
  & servlet-class?
  & servlet-name?
  < url-pattern*
  < url-regexp*
}
Example: WEB-INF/resin-web.xml <servlet-mapping>
<web-app xmlns="http://caucho.com/ns/resin">

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

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

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

</web-app>

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

Warning Enabling the invoker servlet can create a security hole in your application. Any servlet in the classpath, perhaps even one in a .jar that you are unaware of, could be invoked.
Example: WEB-INF/resin-web.xml servlet invoker
<web-app xmlns="http://caucho.com/ns/resin">

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

</web-app>

There are a number of mappings to servlets that are usually available to a Resin application, as defined in $RESIN_HOME/conf/app-default.xml.

Example: servlet-mappings in $RESIN_HOME/conf/app-default.xml
<cluster>

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

  <servlet-mapping url-pattern="/servlet/*" servlet-name="invoker"/>
  <servlet-mapping url-pattern="/" servlet-name="file"/>
</web-app-default>
</cluster>

The plugins use servlet-mapping to decide which URLs to send to Resin. The following servlet-name values are used by the plugins:

servlet-name values used by plugins
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-domain-regexpRegex for cookies-domain for multi-domain webappsnone
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.Serializabletrue
invalidate-after-listenerIf true, invalidate the sessions after the session listeners have been called
reuse-session-idReuse the session id even if the session has timed out. A value of false defeats single signon capabilities. (resin 2.0.4)true
session-maxMaximum active sessions4096
session-timeoutThe session timeout in minutes, 0 means never timeout.30 minutes
serialization-typeUse one of "java" or "hessian" for serialization, hessian is significantly faster and smaller (resin 3.1.2)java
serialize-collection-typeFor hessian serialization, ignore the collection type when serializing lists (disable for some Hibernate lists)true
save-modeWhen to save sessions, one of "before-headers", "after-request", or "on-shutdown"after-request
use-persistent-storeUses the current persistent-store to save sessions. (resin 3.0.8)none
<session-config> schema
element session-config {
  always-load-session?
  & always-save-session?
  & cookie-append-server-index?
  & cookie-domain?
  & cookie-domain-regexp?
  & cookie-length?
  & cookie-max-age?
  & cookie-port?
  & cookie-secure?
  & cookie-version?
  & enable-cookies?
  & enable-url-rewriting?
  & ignore-serialization-errors?
  & invalidate-after-listener?
  & reuse-session-id?
  & save-mode?
  & save-on-shutdown?
  & serialization-type?
  & session-max?
  & session-timeout?
  & use-persistent-store?
}

The session-timeout and session-max are usually used together to control the number of sessions. Sessions are stored in an LRU cache. When the number of sessions in the cache fills up past session-max, the oldest sessions are recovered. In addition, sessions idle for longer than session-timeout are purged.

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

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

</web-app>

cookie-length is used to limit the maximum length for the session's generated cookie for special situations like WAP devices. Reducing this value reduces the randomness in the cookie and increases the chance of session collisions.

reuse-session-id defaults to true so that Resin can share the session id amongst different web-apps.

The class that corresponds to <session-config> is com.caucho.server.session.SessionManager

<shutdown-wait-max>

child of <server>

<shutdown-wait-max> configures the maximum time the server will wait for the graceful shutdown before forcing an exit.

default 60s
<shutdown-wait-max> schema
element shutdown-wait-max {
  r_period-Type
}

<statistics-enable>

default false

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

<statistics-enable> schema
element statistics-enable {
  r_boolean-Type
}

<strict-mapping>

default false, allowing /foo/bar.jsp/foo.

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

<strict-mapping> schema
element strict-mapping {
  r_boolean-Type
}
Example: enabling strict-mapping in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin">
  <strict-mapping>true</strict-mapping>
</web-app>

<user-data-constraint>

Restricts access to secure transports, such as SSL

<user-data-constraint> 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.

When specified by id, the application will be initialized on server start. When specified by <url-regexp>, the application will be initialized at the first request. This means that load-on-startup servlets may start later than expected for url-regexp applications.

<web-app> Attributes
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 <redeploy-mode>automatic
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-mode>automatic
startup-priorityspecifies a priority for web-app startup to force an ordering between webapps -1
url-regexpA regexp to select this application.n/a

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

<host id=''>
  <web-app id='/apache' root-directory='/usr/local/apache/htdocs'>

  ...

</host>

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

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

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

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

<host id=''>

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

    ...

  </web-app>

</host>

<web-app-default>

child of <cluster>

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

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

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

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

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

<web-app-deploy>

child of <host>,<web-app>

Specifies war expansion.

web-app-deploy can be used in web-apps to define a subdirectory for war expansion. The tutorials in the documentation use web-app-deploy to allow servlet/tutorial/helloworld to be an independent war file.

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

Example: resin.xml overriding web.xml
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">
<host id="">

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

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

versioning

The versioning attribute of the <web-app-deploy> tag improves web-app version updates by enabling a graceful update of sessions. The web-apps are named with numeric suffixes, e.g. foo-10, foo-11, etc, and can be browsed as /foo. When a new version of the web-app is deployed, Resin continues to send current session requests to the previous web-app. New sessions go to the new web-app version. So users will not be aware of the application upgrade.

<web-resource-collection>

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.