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


 

Resin Documentation

home company blog wiki docs 
app server web server 
health cloud java ee pro 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

references


Complete reference documentation

  1. AbstractAuthenticator
  2. <accept-listen-backlog>
  3. <accept-thread-max>
  4. <accept-thread-min>
  5. <access-log>
  6. <active-wait-time>
  7. <address>
  8. <allow-forward-after-flush>
  9. <allow-servlet-el>
  10. <archive-path>
  11. <auth-constraint>
  12. <authenticator>
  13. <bean>
  14. <cache>
  15. <cache-mapping>
  16. <case-insensitive>
  17. <character-encoding>
  18. <class-loader>
  19. <close-dangling-connections>
  20. <cluster>
  21. <cluster-default>
  22. <cluster-port>
  23. <compiling-loader>
  24. <connection>
  25. <connection-error-page>
  26. <connection-wait-time>
  27. <constraint>
  28. <context-param>
  29. <cookie-http-only>
  30. cron trigger syntax
  31. <development-mode-error-page>
  32. <database>
  33. <database-default>
  34. <dependency>
  35. <dependency-check-interval>
  36. <driver>
  37. <ear-default>
  38. <ear-deploy>
  39. <ejb-message-bean>
  40. <ejb-server>
  41. <ejb-stateful-bean>
  42. <ejb-stateless-bean>
  43. <environment-system-properties>
  44. <env-entry>
  45. <error-page>
  46. <expand-cleanup-fileset>
  47. <fileset>
  48. <filter>
  49. <filter-mapping>
  50. <form-login-config>
  51. <group-name>
  52. <health:ActionSequence>
  53. <health:And>
  54. <health:AnomalyAnalyzer>
  55. <health:CallJmxOperation>
  56. <health:ConnectionPoolHealthCheck>
  57. <health:CpuHealthCheck>
  58. <health:DumpHeap>
  59. <health:DumpHprofHeap>
  60. <health:DumpJmx>
  61. <health:DumpThreads>
  62. <health:ExecCommand>
  63. <health:ExprHealthCheck>
  64. <health:FailSafeRestart>
  65. <health:HealthSystem>
  66. <health:HealthSystemHealthCheck>
  67. <health:HeartbeatHealthCheck>
  68. <health:HttpStatusHealthCheck>
  69. <health:IfCron>
  70. <health:IfExpr>
  71. <health:IfHealthCritical>
  72. <health:IfHealthEvent>
  73. <health:IfHealthFatal>
  74. <health:IfHealthOk>
  75. <health:IfHealthUnknown>
  76. <health:IfHealthWarning>
  77. <health:IfMessage>
  78. <health:IfNotRecent>
  79. <health:IfRecovered>
  80. <health:IfRechecked>
  81. <health:IfUptime>
  82. <health:JmxDeltaMeter>
  83. <health:JmxMeter>
  84. <health:JvmDeadlockHealthCheck>
  85. <health:LicenseHealthCheck>
  86. <health:MemoryPermGenHealthCheck>
  87. <health:MemoryTenuredHealthCheck>
  88. <health:Nand>
  89. <health:Nor>
  90. <health:Not>
  91. <health:OnAbnormalStop>
  92. <health:OnRestart>
  93. <health:OnStart>
  94. <health:OnStop>
  95. <health:Or>
  96. <health:PdfReport>
  97. <health:Restart>
  98. <health:ScoreboardReport>
  99. <health:SetJmxAttribute>
  100. <health:SendMail>
  101. <health:SetJmxAttribute>
  102. <health:Snapshot>
  103. <health:StartProfiler>
  104. <health:TransactionHealthCheck>
  105. <home-cluster>
  106. <host>
  107. <host-alias>
  108. <host-alias-regexp>
  109. <host-default>
  110. <host-deploy>
  111. <host-name>
  112. <http>
  113. <idle-time>
  114. <ignore-client-disconnect>
  115. <invocation-cache-size>
  116. <invocation-cache-max-url-length>
  117. <javac>
  118. <jndi-link>
  119. <jpa-persistence>
  120. <jpa-persistence-unit>
  121. <jsp>
  122. <jsp-config>
  123. <jvm-arg>
  124. <jvm-classpath>
  125. <keepalive-max>
  126. <keepalive-select-enable>
  127. <keepalive-select-thread-timeout>
  128. <keepalive-timeout>
  129. <lazy-servlet-validate>
  130. <library-loader>
  131. <listener>
  132. <load-balance-connect-timeout>
  133. <load-balance-recover-time>
  134. <load-balance-idle-time>
  135. <load-balance-warmup-time>
  136. <load-balance-weight>
  137. <login-config>
  138. <log-handler>
  139. <logger>
  140. Log format string
  141. <mail>
  142. <max-active-time>
  143. <max-close-statements>
  144. <max-connections>
  145. <max-create-connections>
  146. <max-idle-time>
  147. <max-overflow-connections>
  148. <max-pool-time>
  149. <max-uri-length>
  150. <memory-free-min>
  151. <mime-mapping>
  152. <multipart-form>
  153. <path-mapping>
  154. <password>
  155. <ping>
    1. Mail notification when ping fails
  156. <ping>
  157. <ping-table>
  158. <ping-query>
  159. <ping-interval>
  160. <port>
  161. <port-default>
  162. <prepared-statement-cache-size>
  163. <protocol>
  164. <redeploy-check-interval>
  165. <redeploy-mode>
  166. <rewrite-real-path>
  167. <rewrite-vary-as-private>
  168. <root-directory>
  169. <reference>
  170. <remote-client>
  171. <resin>
  172. <resin-system-auth-key>
  173. <resin:AdminAuthenticator>
  174. <resin:Allow>
  175. <resin:And>
  176. <resin:BasicLogin>
  177. <resin:ByteStreamCache>
  178. <resin:choose>
  179. <resin:ClusterCache>
  180. <resin:ClusterQueue>
  181. <resin:ClusterSingleSignon>
  182. <resin:DatabaseAuthenticator>
  183. <resin:Deny>
  184. <resin:DigestLogin>
  185. <resin:Dispatch>
  186. <resin:ElasticCloudService>
  187. <resin:FastCgiPort>
  188. <resin:FastCgiProxy>
  189. <resin:FileQueue>
  190. <resin:FileTopic>
  191. <resin:Forbidden>
  192. <resin:FormLogin>
  193. <resin:Forward>
  194. <resin:GlobalCache>
  195. <resin:HttpProxy>
  196. <resin:if>
  197. <resin:IfAuthType>
  198. <resin:IfCookie>
  199. <resin:IfCron>
  200. <resin:IfFileExists>
  201. <resin:IfHeader>
  202. <resin:IfLocale>
  203. <resin:IfLocalPort>
  204. <resin:IfMBeanEnabled>
  205. <resin:IfMethod>
  206. <resin:IfNetwork>
  207. <resin:IfQueryParam>
  208. <resin:IfRemoteUser>
  209. <resin:IfSecure>
  210. <resin:IfUserInRole>
  211. <resin:import>
  212. <resin:JaasAuthenticator>
  213. <resin:JmsConnectionFactory>
  214. <resin:JmxService>
  215. <resin:LdapAuthenticator>
    1. jndi-env
  216. <resin:LoadBalance>
  217. <resin:LogService>
  218. <resin:MemoryQueue>
  219. <resin:MemorySingleSignon>
  220. <resin:MemoryTopic>
  221. <resin:message>
  222. <resin:MovedPermanently>
  223. <resin:Not>
  224. <resin:NotAnd>
  225. <resin:NotOr>
  226. <resin:Or>
  227. <resin:otherwise>
  228. <resin:PingMailer>
  229. <resin:PingThread>
  230. <resin:ProjectJarRepository>
  231. <resin:PropertiesAuthenticator>
  232. <resin:Redirect>
  233. <resin:RemoteAdminService>
  234. <resin:ScheduledTask>
  235. <resin:SendError>
  236. <resin:set>
  237. <resin:SetHeader>
  238. <resin:SetRequestSecure>
  239. <resin:SetVary>
  240. <resin:StatService>
  241. <resin:when>
  242. <resin:XaLogService>
  243. <resin:XmlAuthenticator>
  244. <resin:XmlRoleMap>
  245. RequestPredicate
  246. <resource>
  247. <resource-ref>
  248. <save-mode>
  249. <save-allocation-stack-trace>
  250. <scheduled-task>
  251. <secure>
  252. <secure-host-name>
  253. <security-constraint>
  254. <security-manager>
  255. <security-provider>
  256. <server>
    1. EL variables and functions
  257. <server-default>
  258. <server-header>
  259. <servlet>
  260. <servlet-hack>
  261. <servlet-mapping>
  262. <servlet-regexp>
  263. ServletRequestPredicate
  264. <session-cookie>
  265. <session-config>
  266. <session-url-prefix>
  267. <shutdown-wait-max>
  268. <simple-loader>
  269. <socket-timeout>
  270. <spy>
  271. <ssl-session-cookie>
  272. <startup-mode>
  273. <stat-service>
  274. <statistics-enable>
  275. <stderr-log>
  276. <stdout-log>
  277. <strict-mapping>
  278. <system-property>
  279. Time intervals
  280. <temp-dir>
  281. <thread-idle-max>
  282. <thread-idle-min>
  283. <thread-max>
  284. <transaction-timeout>
  285. <tree-loader>
  286. <url-character-encoding>
  287. <url-regexp>
  288. <user-data-constraint>
  289. <user-name>
  290. Variables: java
  291. Variables: resin
  292. Variables: system
  293. <watchdog>
  294. <watchdog-arg>
  295. <watchdog-manager>
  296. <watchdog-port>
  297. <web-app>
  298. <web-app-default>
  299. <web-app-deploy>
    1. Overriding web-app-deploy configuration
    2. versioning
  300. <web-resource-collection>
  301. <welcome-file-list>
  302. <work-dir>

AbstractAuthenticator

While this case is rare, it may sometimes be useful to create your own Resin custom authenticator (for example to use a legacy resource as an authentication store). The Resin security framework provides an abtract base class (com.caucho.security.AbstractAuthenticator) that you can extend to do this.

The following is a simple example that you can use a starting point for your application:

WEB-INF/resin-web.xml - Custom Authenticator Configuration
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:foo="urn:java:com.caucho.foo">
  ...
  <foo:MyAuthenticator>
    <foo:foo>bar</foo:foo>
  </foo:MyAuthenticator>
  ...
</web-app>
MyAuthenticator.java
package com.foo;

import com.caucho.security.AbstractAuthenticator;
import com.caucho.security.PasswordUser;

public class MyAuthenticator extends AbstractAuthenticator {
  private PasswordUser _user;

  public MyAuthenticator()
  {
    _user = new PasswordUser("harry", "quidditch",
                             new String[] { "user" });
  }

  public PasswordUser getUser(String userName)
  {
    if (userName.equals(_user.getName()))
      return _user;
    else
      return null;
  }
}

<accept-listen-backlog>

default 4000

<accept-listen-backlog> configures operating system TCP listen queue size for the port.

When a browser connects to a server, the server's operating system handles the TCP initialization before handing the socket to the server's application. The operating system will hold the opened connections in a small queue, until the application is ready to receive them. When the queue fills up, the operating system will start refusing new connections.

<accept-thread-max>

default 10

<accept-thread-max> configures the maximum number of threads listening for new connections on this port. <accept-thread-max> works with <accept-thread-min> to handle spiky loads without creating and destroying too many threads.

Socket connections are associated with a thread which handles the request. In Resin, a number of threads wait to accept a new connection and then handle the request. <accept-thread-max> specifies the maximum number of threads which are waiting for a new connection.

Larger values handle spiky loads better but require more threads to wait for the connections. Smaller values use less threads, but may be slower handling spikes.

<accept-thread-min>

<accept-thread-min> configures the minimum number of threads listening for new connections on this port <accept-thread-min> works with <accept-thread-max> to handle spiky loads without creating and destroying too many threads.

Socket connections are associated with a thread which handles the request. In Resin, a number of threads wait to accept a new connection and then handle the request. <accept-thread-min> specifies the minimum number of threads which are waiting for a new connection. If many connections appear rapidly with a small value of <accept-thread-min>, the application may pause until a new thread is available for the new connection.

Larger values handle spiky loads better but require more threads to wait for the connections. Smaller values use less threads, but may be slower handling spikes.

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

<address>

child of server
default 127.0.0.1

The server <address> defines the IP interface for Resin cluster communication and load balancing. It will be an internal IP address like 192.168.* for a clustered configuration or 127.* for a single-server configuration. No wild cards are allowed because the other cluster servers and load balancer use the address to connect to the server.

server address
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
      <http port="80"/>
    </server-default>

    <server id="web-a" address="192.168.1.1" port="6800"/>
    <server id="web-b" address="192.168.1.2" port="6800"/>

    ...
  </cluster>

  <cluster id="app-tier">
    <server id="app-a" address="192.168.2.11" port="6800"/>
    <server id="app-b" address="192.168.2.12" port="6800"/>

    ...
  </cluster>
</resin>

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

<authenticator>

The <authenticator> tag as been replaced by CDI-style authenticator configuration. It exists only for backward compatibility. To upgrade, see the authenticator-specific tags like resin:XmlAuthenticator.

The new name will be the old class="..." name. So class="com.caucho.security.XmlAuthenticator" becomes <resin:XmlAuthenticator>.

XmlAuthenticator in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:XmlAuthenticator password-digest="none">
    <resin:user name="Harry Potter" password="quidditch" group="user,gryffindor"/>
    <resin:user name="Draco Malfoy" password="pureblood" group="user,slytherin"/>
  </resin:XmlAuthenticator>
  ...
</web-app>  

<bean>

The <bean> tag as been replaced by CDI-style configuration. It exists only for backward compatibility.

The new tag name will be the old class="..." name and the XML prefix will be the package. So class="com.mycom.FooBean" becomes <mycom:FooBean xmlns:mycom="urn:com.mycom">.

MyBean in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"
            xmlns:mypkg="urn:java:com.mycom.mypkg">
  ...
  <mypkg:MyBean resin:JndiName="java:comp/env/my-name">
    <my-attribute>my-value</my-attribute>
  </mypkg:MyBean>
  ...
</web-app>  

<cache>

child of cluster

<cache> configures the proxy cache (requires Resin Professional). The proxy cache improves performance by caching the output of servlets, jsp and php pages. For database-heavy pages, this caching can improve performance and reduce database load by several orders of magnitude.

The proxy cache uses a combination of a memory cache and a disk-based cache to save large amounts of data with little overhead.

Management of the proxy cache uses the ProxyCacheMXBean.

<cache> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
pathPath to the persistent cache files.resin-data/
disk-sizeMaximum size of the cache saved on disk.1024M
enableEnables the proxy cache.true
enable-rangeEnables support for the HTTP Range header.true
entriesMaximum number of pages stored in the cache.8192
max-entry-sizeLargest page size allowed in the cache.1M
memory-sizeMaximum heap memory used to cache blocks.16M
rewrite-vary-as-privateRewrite Vary headers as Cache-Control: private to avoid browser and proxy-cache bugs (particularly IE).false
<cache> schema
element cache {
  disk-size?
  & enable?
  & enable-range?
  & entries?
  & path?
  & max-entry-size?
  & memory-size?
  & rewrite-vary-as-private?
}
Example: enabling proxy cache
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <cache entries="16384" disk-size="2G" memory-size="256M"/>

        <server id="a" address="192.168.0.10"/>

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

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

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

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-regexpA regular expression matching the url
<cache-mapping> schema
element cache-mapping {
  (url-pattern | url-regexp)
  & expires?
  & max-age?
  & s-max-age?
}
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>

<case-insensitive>

default true on Windows, false on Unix.

<case-insensitive> specifies whether the environment context is case sensitive or insensitive.

Because some operating systems are case-insensitive, it is important for security reasons for Resin to behave differently for case-sensitive and case-insensitive directories. For example, when case-insensitive is true, url-patterns will match in a case-insensitive manner, so TEST.JSP will work like test.jsp.

<case-insensitive> schema
r_case-insensitive = element case-insensitive {
  r_boolean-Type
}

<character-encoding>

default The default value is ISO-8859-1.

<character-encoding> specifies the default character encoding for the environment.

<character-encoding> schema
r_character-encoding = element character-encoding {
  string
}
Example: utf-8 as default character encoding
<resin xmlns="http://caucho.com/ns/resin">
  <character-encoding>utf-8</character-encoding>
  ...

</resin>

<class-loader>

<class-loader> configures a dynamic classloader for the current environment.

Each environment (<cluster>, <host>, <web-app>) etc, can add dynamic classloaders. The environment will inherit the parent classloaders. Each <class-loader> is comprised of several implementing loader items: library-loader for WEB-INF/lib, compiling-loader for WEB-INF/classes.

For web-apps, the classloaders generally belong in a <prologue> section, which ensures that Resin evaluates them first. The evaluation order is particularly important in cases like resin-web.xml vs web.xml, because the resin-web.xml is evaluated after the web.xml.

<class-loader> Attributes
ELEMENTDESCRIPTION
<compiling-loader>Automatically compiles sources code to classes. It its the default loader for WEB-INF/classes.
<library-loader>Loads jar files from a directory. It is the default loader for WEB-INF/lib.
<simple-loader>Loads classes from a directory, but does not compile them automatically.
<tree-loader>Loads jar files from a directory, recursively searching subdirectories.
<class-loader> schema
r_class-loader = element class-loader {
  r_compiling-loader*

  & r_library-loader*

  & r_simple-loader*

  & r_tree-loader*
}
Example: WEB-INF/resin-web.xml defined <class-loader>
<web-app xmlns="http://caucho.com/ns/resin">
  <prologue>
    <class-loader>
      <compiling-loader path="WEB-INF/classes"/>

      <library-loader path="WEB-INF/lib"/>
    </class-loader>
  </prologue>
</web-app>

<close-dangling-connections>

child of database
default true

<close-dangling-connections> closes open connections at the end of a request and logs a warning and stack trace.

<cluster>

child of resin

<cluster> configures a set of identically-configured servers. The cluster typically configures a set of <server>s, each with some ports, and a set of virtual <host>s.

Only one <cluster> is active in any on server. At runtime, the <cluster> is selected by the <server> with id matching the -server on the command line.

<cluster> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
idThe cluster identifier.required
access-logAn access-log shared for all virtual hosts.
cacheProxy cache for HTTP-cacheable results.
connection-error-pageIIS error page to use when isapi_srun to Resin connection fails
ear-defaultdefault values for deployed ear files
error-pageCustom error-page when virtual-hosts fail to match
hostConfigures a virtual host
host-defaultConfigures defaults to apply to all virtual hosts
host-deployAutomatic host deployment based on a deployment directory
ignore-client-disconnectIgnores socket exceptions thrown because browser clients have prematurely disconnectedfalse
invocation-cache-sizeSize of the system-wide URL to servlet invocation mapping cache16384
invocation-cache-max-url-lengthMaximum URL length saved in the invocation cache256
max-uri-lengthMaximum URI length allowed in request1024
machineConfiguration for grouping <server> onto physical machines
pingPeriodic checking of server URLs to verify server activity
redeploy-mode"automatic" or "manual"automatic
resin:chooseConditional configuration based on EL expressions
resin:importImports a custom cluster.xml files for a configuration management
resin:ifConditional configuration based on EL expressions
rewrite-dispatchrewrites and dispatches URLs using regular expressions, similar to mod_rewrite
root-directoryThe root filesystem directory for the cluster${resin.root}
serverConfigures JVM instances (servers). Each cluster needs at least one server
server-defaultConfigures defaults for all server instances
server-headerConfigures the HTTP "Server: Resin/xxx" headerResin/Version
session-cookieConfigures the servlet cookie nameJSESSIONID
url-character-encodingConfigures the character encoding for URLsutf-8
url-length-maxConfigures the maximum length of an allowed URL8192
web-app-defaultConfigures defaults to apply to all web-apps in the cluster
<cluster> schema
element cluster {
  attribute id { string }
  & environment resources
  & access-log?
  & cache?
  & connection-error-page?
  & ear-default*
  & error-page*
  & host*
  & host-default*
  & host-deploy*
  & ignore-client-disconnect?
  & invocation-cache-size?
  & invocation-cache-max-url-length?
  & machine*
  & ping*
  & redeploy-mode?
  & resin:choose*
  & resin:import*
  & resin:if*
  & rewrite-dispatch?
  & root-directory?
  & server*
  & server-default*
  & server-header?
  & session-cookie?
  & url-character-encoding?
  & url-length-max?
  & web-app-default*
}
Example: cluster-default
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <server-default>
            <http port="8080"/>
        </server-default>

        <server id="a" address="192.168.0.10"/>
        <server id="b" address="192.168.0.11"/>

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

<cluster-default>

child of resin

<cluster-default> defines default cluster configuration for all clusters in the <resin> server.

Example: cluster-default
<resin xmlns="http://caucho.com/ns/resin">
    <cluster-default>
        <cache entries="16384" memory-size="64M"/>
    </cluster-default>

    <cluster id="web-tier">
        ...
    </cluster>

    <cluster id="app-tier">
        ...
    </cluster>
</resin>

<cluster-port>

child of server

<cluster-port> configures the cluster and load balancing socket, for load balancing, distributed sessions, and distributed management.

When configuring Resin in a load-balanced cluster, each Resin instance will have its own <server> configuration, which Resin uses for distributed session management and for the load balancing itself.

When configuring multiple JVMs, each <server> has a unique <server-id> which allows the -server command-line to select which ports the server should listen to.

<cluster-port> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
addresshostname of the interface to listen to*
jsse-sslconfigures the port to use JSSE for SSLnone
opensslconfigures the port to use OpenSSLnone
portport to listen torequired
read-timeouttimeout waiting to read from idle client65s
write-timeouttimeout waiting to write to idle client65s
accept-listen-backlogThe socket factory's listen backlog for receiving sockets4000
tcp-no-delaysets the NO_DELAY socket parametertrue

<compiling-loader>

child of class-loader

<compiling-loader> automatically compiles Java code into .class files before loading them.

<compiling-loader> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
argsAdditional arguments to be passed to the Java compiler. Resin 3.0
batchIf true, multiple changed *.java files will be compiled in a single batch. Resin 3.0.7true
encodingI18N encoding for the Java compiler. Since Resin 3.0
pathFilesystem path for the class loader. Since Resin 3.0required
sourceJava source directory. Since Resin 3.0value of path
require-sourceIf true, .class files without matching .java files will be deleted. Since Resin 3.0false
Example: WEB-INF/resin-web.xml <compiling-loader>
<web-app xmlns="http://caucho.com/ns/resin">
  <prologue>
    <class-loader>
      <compiling-loader path="WEB-INF/classes"
                        source="WEB-INF/src"/>
    </class-loader>
  </prologue>
</web-app>

<connection>

child of database

Initialize all java.sql.Connection objects managed by database.

<connection> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
catalogSets catalog property on java.sql.Connection object.
read-onlySets readOnly property on java.sql.Connection object.false
transaction-isolationSets transaction isolation property on java.sql.Connection object. All levels defined in java.sql.Connection.TRANSACTION_* are supported via value set: none, read-committed, read-uncommitted, repeatable-read, serializable. unspecified
<connection> schema
element connection {
  catalog?
  & read-only?
  & transaction-isolation?
}
Setting values for Connections in a pool
<web-app xmlns="http://caucho.com/ns/resin">
  <database>
    <driver type="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource">
      <url>jdbc:mysql://localhost:3306/test</url>
      <user></user>
      <password></password>
    </driver>

    <connection>
      <transaction-isolation>serializable</transaction-isolation>
      <catalog>my-catalog</catalog>
    </connection>
  </database>
</web-app>

<connection-error-page>

child of cluster

<connection-error-page> specifies an error page to be used by IIS when it can't contact an app-tier Resin. This directive only applies to IIS.

<connection-error-page> schema
element connection-error-page {
  string
}

<connection-wait-time>

child of database
default 10m

<connection-wait-time> configures the time a getConnection call should wait when then pool is full before trying to create an overflow connection.

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

cron trigger syntax

A time syntax used in a number of tags. Originally used in the Unix cron program. The wikipedia cron entry contains this descriptive chart:

cron fields
# +---------------- minute (0 - 59)
# |  +------------- hour (0 - 23)
# |  |  +---------- day of month (1 - 31)
# |  |  |  +------- month (1 - 12)
# |  |  |  |  +---- day of week (0 - 6) (Sunday=0 or 7)
# |  |  |  |  |
  *  *  *  *  *
cron patterns
PATTERNDESCRIPTION
*matches all time periods
15matches the specific time, e.g. 15 for minutes
15,45matches a list of times, e.g. every :15 and :45
*/5matches every n times, e.g. every 5 minutes
1-5matches a range of times, e.g. mon, tue, wed, thu, fri (1-5)

<development-mode-error-page>

child of cluster

<development-mode-error-page> enables browser error reporting with extra information. Because it can expose internal data, it is not generally recommended in production systems. (The information is generally copied to the log.

<database>

<database> defines a database (i.e. DataSource) resource.

The database configuration section has more details on the configuration.

<database> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
backup-driverConfigures a backup database driver. If Resin can't connect to any of the main drivers, it will use one of the. backups
close-dangling-connectionsIf an application does not close a Connection by the end of the request, Resin will close it automatically an issue a warning.true
connectionDefines initialization attributes for new connections, e.g. setting the transaction-isolation.true
connection-wait-timeWhen max-connections has been reached, how long Resin will wait for a connection to become idle before giving up.10min
driverConfigures the database driver, giving the driver's class name as well as its JDBC URL and any other configuration.required
jndi-nameThe JNDI name to register the connection's DataSource under. If the name can be relative to java:comp/env.
max-active-timeThe maximum time Resin will allow a connection to remain open before forcing a close.6 hours
max-close-statementsThe maximum number of Statements Resin will hold to automatically close when the Connection closes.256
max-connectionsThe maximum number of Connections allowed.128
max-create-connectionsThe maximum number of connection creation allowed at one time.5
max-idle-countThe maximum number of Connections in the idle pool.1024
max-idle-timeThe maximum time a connection will spend in the idle pool before closing.30s
max-overflow-connectionsThe number of extra connection creation if the number of connections exceeds to pool size.0
max-pool-timeThe total time a connection can be used before it is automatically closed instead of returned to the idle pool.24h
nameThe IoC name to save the ConnectionFactory as, used with @Named to inject the resource.
passwordThe JDBC password for the connection.
pingIf true, Resin will ping the database before returning a connection from the pool (if ping-interval is exceeded).false
ping-intervalHow often an idle connection should ping the database to ensure it is still valid.1s
ping-queryA custom query used to ping the database connection.
ping-tableA table used to ping the database connection.
prepared-statement-cache-sizeHow many PreparedStatements to save in the prepared statement cache.0
save-allocation-stack-traceIf true, saves the location of the connection allocation as a stack trace.false
spyEnables spy logging of database statements. The logging occurs with name="com.caucho.sql" and level="fine".false
transaction-timeoutSets the transaction timeout.none
userSets the authentication user.
wrap-statementsIf true, Resin wraps statements and automatically closes them on connection close.true
xaEnables automatic enlistment of Connections with any UserTransaction. Disabling <xa> means the connection are independent of transactions, useful for read-only connections.true
xa-forbid-same-rmWorkaround flag to handle certain database drivers that do not properly implement the XAResource API.false
<database> schema
database = element database {
  backup-driver*
  & close-dangling-connections?
  & connection?
  & connection-wait-time?
  & driver+
  & jndi-name?
  & max-active-time?
  & max-close-statements?
  & max-connections?
  & max-create-connections?
  & max-idle-count?
  & max-idle-time?
  & max-overflow-connections?
  & max-pool-time?
  & name?
  & password?
  & ping?
  & ping-interval?
  & ping-query?
  & ping-table?
  & prepared-statement-cache-size?
  & save-allocation-stack-trace?
  & spy?
  & transaction-timeout?
  & user?
  & wrap-statements?
  & xa?
  & xa-forbid-same-rm?
}

backup-driver = element backup-driver {
  class?
  & url?
  & element * { * }?
}

connection = element connection {
  catalog?
  & read-only?
  & transaction-isolation?
}

driver = element driver {
  class?
  & url?
  & element * { * }?
}

Example: WEB-INF/resin-web.xml database
<web-app xmlns="http://caucho.com/ns/resin">

<database jndi-name='jdbc/test_mysql'>
  <driver class="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource">
    <url>jdbc:mysql://localhost:3306/test</url>
    <user></user>
    <password></password>
  </driver>
</database>

</web-app>

<database-default>

<database-default> defines default database values to be used for any <database> definition, or runtime database creation (see DatabaseManager).

<database-default> schema
element database-default {
  r_database-Content
}
Example: WEB-INF/resin-web.xml idle-time defaults
<web-app xmlns="http://caucho.com/ns/resin">

  <database-default>
    <max-idle-time>10s</max-idle-time>
  </database-default>

</web-app>

<dependency>

<dependency> adds dependent files which should force a reload when changed, like web.xml and resin-web.xml.

<dependency> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
pathFilesystem path to the dependent file. Since Resin 3.0required
<dependency> schema
element dependency {
  string
}
Example: struts dependency
<web-app xmlns="http://caucho.com/ns/resin">
  <dependency path="WEB-INF/struts-config.xml"/>
  ...
</web-app>

<dependency-check-interval>

default 2s

<dependency-check-interval> Configures how often the environment context should be checked for changes. The default value is set low for development purposes, deployments should use something larger like 5m or 1h.

Resin automatically checks each environment for updates, generally class or configuration updates. Because these checks can take a considerable amount of time, deployment servers should use high values like 60s or more while development machines will want low values like 2s.

The interval defaults to the parent's interval. So the web-app will default to the host's value.

<dependency-check-interval> schema
element dependency-check-interval {
  string
}
Example: deployment dependency-check-interval
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
    <dependency-check-interval>1h<dependency-check-interval>

    <server id="app-a" .../>

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

<driver>

child of database

<driver> configures a database driver for a connection pool. The individual driver information is available from the driver vendor or on the Caucho Wiki.

The content of the driver tag configures bean properties of the driver class, e.g. url, user, password.

<driver> schema
element driver {
  type,
  *
}

<ear-default>

child of cluster

<ear-default> configures defaults for .ear resource, i.e. enterprise applications.

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

<ejb-message-bean>

<ejb-message-bean> configures a bean as a message listener. The listener can be a simple bean that just implements the javax.jms.MessageListener interface. No other packaging or complications are necessary. Resin will retrieve messages from a configured queue and pass them to the listener as they arrive. The listeners are typically pooled.

The bean has full access to Resin-IoC capabilities, including dependency injection, transaction attributes, and aspect interception.

The message bean can plug into custom messaging systems. The application will need to define a ResourceAdapter and an ActivationSpec.

<ejb-message-bean> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
activation-specConfigures a custom message-listener driver
classClassname of the listener beanrequired
destinationQueue or Topic for JMS message receiving
destination-typejavax.jms.Queue or javax.jms.Topic
initIoC configuration for the listener bean
message-consumer-maxThe number of listener instances to create for the pool.5
<ejb-message-bean> schema
element ejb-message-bean {
  class
  & init?
  & (activation-spec?
     | (destination?
        & destination-type?
        & destination-name?
        & message-consumer-max?)
    )
}

<ejb-server>

Configures an EJB server.

<ejb-server> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
auto-compileenables auto-compilation of EJB stubs and skeletonstrue
create-database-schemaenables JPA auto-creation of missing database tablesfalse
data-sourcespecifies the default database for JPA
config-directoryspecifies a directory containing *.ejb configuration files
ejb-descriptorpath to a *.ejb file to load
ejb-jarpath to a jar file containing a META-INF/ejb-jar.xml with EJBs
jndi-prefixprefix for JNDI registration of EJBs
validate-database-schemaverifies the actual database tables against the JPA definitionstrue
jms-connection-factoryspecifies the default JMS ConnectionFactory for message beans
xa-data-sourcespecifies a separate database for transactionsdata-source
<ejb-server> schema
element ejb-server {
  auto-compile
  & create-database-schema
  & data-source
  & config-directory
  & ejb-descriptor
  & ejb-jar
  & jndi-prefix
  & validate-database-schema
  & jms-connection-factory
  & xa-data-source
}

<ejb-stateful-bean>

<ejb-stateful-bean> is deprecated and replaced by CDI-style configuration. EJB stateful beans are now either scanned automatically if configured with the @Stateful annotation or can be configured as CDI beans with the <ee:Stateful> tag.

Stateful bean in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:ee="urn:java:ee"
         xmlny:mypkg="urn:java:com.mycom.mypkg">

  <mypkg:MyBean>
    <ee:Stateful/>

    <my-attribute>my-value</my-attribute>
  </mypkg:MyBean>

</web-app>  

<ejb-stateless-bean>

<ejb-stateless-bean> is deprecated and replaced by CDI-style configuration. EJB stateless beans are now either scanned automatically if configured with the @Stateless annotation or can be configured as CDI beans with the <ee:Stateless> tag.

Stateless bean in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:ee="urn:java:ee"
         xmlny:mypkg="urn:java:com.mycom.mypkg">

  <mypkg:MyBean>
    <ee:Stateless/>

    <my-attribute>my-value</my-attribute>
  </mypkg:MyBean>

</web-app>  

<environment-system-properties>

default true

By default, Resin's System.getProperties() is environment-dependent, so the settings in on web-app do not affect the properties in any other web-app. Some sites may need to disable this virtualization capability, when using certain JVM agents.

<environment-system-properties> schema
element environment-system-properties {
  r_boolean-Type
}

<env-entry>

<env-entry> configures a JNDI scalar value for JNDI-based application configuration.

Some application beans prefer to retrieve configuration data from JNDI, including String, Integer, and Double constants. env-entry configures that data in the current context.

The value can not use JSP-EL expressions, because the env-entry is part of the JavaEE spec. To set EL expressions, use resin:set instead.

<env-entry> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
env-entry-nameJNDI name to store the value. Since Servlet 2.1required
env-entry-typeJava type for the value. Since Servlet 2.1required
env-entry-valueValue to be stored. Since Servlet 2.1required
<env-entry> schema
element env-entry {
  description*,

  env-entry-name,

  env-entry-type,

  env-entry-value
}

The example configuration stores a string in java:comp/env/greeting. Following the J2EE spec, the env-entry-name is relative to java:comp/env. If the env-entry is in the <host> context, it will be visible to all web-apps in the host.

Example: WEB-INF/resin-web.xml with env-entry
<web-app xmlns="http://caucho.com/ns/resin">
  <env-entry>
    <env-entry-name>greeting</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>Hello, World</env-entry-value>
  </env-entry>

  <servlet ...>
  </servlet>
</web-app>

The following servlet fragment is a typical use in a servlet. The servlet only looks up the variable once and stores it for later use.

Example: GreetingServlet.java
import java.io.*;
import javax.naming.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class TestServlet extends HttpServlet {
  private String greeting;

  public void init()
    throws ServletException
  {
    try {
      Context env = 
        (Context) new InitialContext().lookup("java:comp/env");
      greeting = (String) env.lookup("greeting");
    } catch (NamingException e) {
      throw new ServletException(e);
    }
  }

  ...
}

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

<expand-cleanup-fileset>

The expand-cleanup-fileset tag lets you configure which files are to be kept on a .war redeploy. By default, Resin deletes the entire .war directory on a restart.

<fileset>

<fileset> provides the ability to match a set of files. It is modelled after the ant tag by the same name. The fileset matches files from a base directory defined by 'dir'. Files can be included by patterns defined by <include> tags or excluded by patterns defined in <exclude> tags.

A pattern can contain two special characters: '*' and '**'. '*' matches any part of path, but does not match the path separator. '**' matches any part of a path, including the path separator.

<fileset> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
dirthe starting directoryrequired
includean include patterndo not include all files
excludean exclude patterndo not exclude any files
<fileset> schema
element fileset {
  dir
  & exclude*
  & include*
Matching jars in WEB-INF/lib (non-recursive)
<fileset dir="WEB-INF/lib">
  <include name="*.jar"/>
</fileset>

MATCH    lib/foo.jar
MATCH    lib/bar.jar
NO MATCH lib/baz/foo.jar
Matching jars in WEB-INF/lib (recursive)
<fileset dir="WEB-INF/tree">
  <include name="**/*.jar"/>
</fileset>

MATCH    lib/foo.jar
MATCH    lib/bar.jar
MATCH    lib/baz/foo.jar

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

<form-login-config>

child of login-config

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

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

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

<form-login-config> Attributes
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>

<group-name>

child of server

<group-name> configures the operating system group Resin should run as. Since the HTTP port 80 is protected in Unix, the web server needs to start as root to bind to port 80. For security, Resin should switch to a non-root user after binding to port 80.

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

    <server-default>
      <http port="80"/>

      <user-name>resin</user-name>
      <group-name>www</group-name>
    </server-default>

    <server id="web-a"/>
    ...
  </cluster>
</resin>

<health:ActionSequence>

child of cluster

Executes a sequence of child health actions in order.

<health:ActionSequence> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:ActionSequence> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:ActionSequence>
    <health:DumpThreads/>
    <health:DumpHeap/>
    <health:IfHealthCritical time="5m"/>
  </health:ActionSequence>

</cluster>

<health:And>

child of cluster
javadoc <health:And>

Qualifies an action to match if all of the child predicates match.

Note: <health:And> is implied and thus not strictly necessary except when used in conjunction with more complex combining conditions.

<health:And> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:And> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:And>
      <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
      <health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/>      
    </health:And>
  </health:Restart> 

</cluster>

<health:AnomalyAnalyzer>

child of cluster

AnomalyAnalyzer examines a meter value, checking for deviations from the average value. So unusual changes like a spike in blocked threads can be detected, logged, and trigger health actions.

<health:AnomalyAnalyzer> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
meterName of the meter to analyze (ie. from <health:JmxMeter>)Stringrequired
health-eventA string to use to match using <health:IfHealthEvent>StringNone: when absent no health event will fire
min-samplesMinimum number of samples required to calculate an averageint60 (typically 1 hour of data)
sigma-thresholdThe number of standard deviations for a sample to be considered an anomaly.int5
Example: <health:AnomalyAnalyzer> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:JmxMeter>
    <name>JVM|Thread|JVM Blocked Count</name>
    <objectName>resin:type=JvmThreads</objectName>
    <attribute>BlockedCount</attribute>
  </health:JmxMeter>

  <health:AnomalyAnalyzer>
    <meter>JVM|Thread|JVM Blocked Count</meter>
    <health-event>caucho.thread.anomaly.jvm-blocked</health-event>
  </health:AnomalyAnalyzer>

  <health:DumpThreads>
    <health:IfHealthEvent regexp="caucho.thread"/>
    <health:IfNotRecent time="15m"/>
  </health:DumpThreads>
  
</cluster>

<health:CallJmxOperation>

child of cluster

Executes a JMX MBean operation with parameters.

Note: Calling a JMX operation can also be performed on-demand using the jmx-call command line.

<health:CallJmxOperation> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
objectNameThe JMX MBean nameStringN/A
operationThe method nameStringN/A
operationIndexUnique method index in case multiple methods match operationint-1
paramMethod parameters that will be converted to the appropriate type.StringN/A
Example: <health:CallJmxOperation> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:CallJmxOperation>
    <objectName>java.lang:type=Threading</objectName>
    <operation>resetPeakThreadCount</operation>
    <health:IfNotRecent time='5m'/>
  </health:CallJmxOperation>

</cluster>

<health:ConnectionPoolHealthCheck>

child of cluster

Monitors the health of Resin database connection pools. See <database> for additional information.

<health:ConnectionPoolHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
<health:ConnectionPoolHealthCheck> Conditions
HEALTHSTATUSCONDITION
WARNINGUpon exceeding max-connections.
CRITICALUpon exceeding max-overflow-connections.
Example: <health:ConnectionPoolHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:ConnectionPoolHealthCheck/>

</cluster>

<health:CpuHealthCheck>

child of cluster

Monitors CPU usage. On multi-core machines, each CPU is checked individually.

<health:CpuHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
warning-thresholdCPU usage warning thresholdint (percentage 0-100)95
critical-thresholdCPU usage critical thresholdint (percentage 0-100)200 (disabled)
<health:CpuHealthCheck> Conditions
HEALTHSTATUSCONDITION
WARNINGUpon exceeding warning-threshold on any CPU.
CRITICALUpon exceeding critical-threshold on any CPU.
Example: <health:CpuHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:CpuHealthCheck>
    <warning-threshold>95</warning-threshold>
    <critical-threshold>99</critical-threshold>
  </health:CpuHealthCheck>
  
</cluster>

<health:DumpHeap>

child of cluster

Create a memory heap dump. The heap dump will be logged to the internal log database and to the resin log file using com.caucho.health.action.DumpHeap as the class at info level.

Note: Creating a heap dump can also be performed on-demand using the heap-dump command line, and from /resin-admin.

<health:DumpHeap> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
hprofCreates an HPROF format dump instead of human readable type.booleanfalse
hprof-pathOutput path write HPROF files, if hprof = trueStringlog/heap.hprof
hprof-path-formatSelects a format for generating dynamic path names using timestamp tokens.String
logIf true, JMX dump is written to the server log in addition to being stored in the internal Resin databasebooleantrue
Example: <health:DumpHeap> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:DumpHeap/>

</cluster>
Example: <health:DumpHeap> in health.xml with hprof-path-format
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:DumpHeap>
    <hprof>true</hprof>
    <hprof-path-format>${resin.home}/log/dump-%H:%M:%S.%s.hprof</hprof-path-format>
    <health:OnAbnormalStop/>
  </health:DumpHeap>

</cluster>

<health:DumpHprofHeap>

child of cluster

Shortcut for <health:DumpHeap hprof='true'/>

<health:DumpJmx>

child of cluster

Health action to create a dump of all JMX attributes and values. The JMX dump will be logged to the internal log database and to the resin log file using com.caucho.health.action.DumpJmx as the class at info level.

Note: Creating a JMX dump can also be performed on-demand using the jmx-dump command line.

<health:DumpJmx> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
logIf true, JMX dump is written to the server log in addition to being stored in the internal Resin databasebooleanfalse
Example: <health:DumpJmx> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:DumpJmx/>

</cluster>

<health:DumpThreads>

child of cluster

Create a thread dump. The thread dump will be logged to the internal log database and log file using com.caucho.health.action.DumpThreads as the class at info level.

Note: Creating a thread dump can also be performed on-demand using the thread-dump command line.

<health:DumpThreads> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
only-activeOutput only currently active threads (RUNNABLE state)booleanfalse
logIf true, JMX dump is written to the server log in addition to being stored in the internal Resin databasebooleantrue
Example: <health:DumpThreads> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:DumpThreads>
    <only-active>false</only-active>
  </health:DumpThreads>

</cluster>

<health:ExecCommand>

child of cluster

Execute an operating system shell command.

<health:ExecCommand> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
commandThe command to execute, relative to dir if setStringN/A
dirThe directory to execute fromjava.io.FileN/A
timeoutTimeout on execution of the command, after which it will be killed if not completePeriod2s
envA custom env variable, available to the command.Name/Value PairN/A (System variables are available by default)
Example: <health:ExecCommand> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:ExecCommand>
    <dir>/tmp</dir>
    <command>remediation.sh</command>
    <timeout>2s</timeout>
    <env>
      <name>resin_home</name>
      <value>${resin.home}</value>
    </env>
    <env>
      <name>password</name>
      <value>foo</value>
    </env>
  </health:ExecCommand>

</cluster>

<health:ExprHealthCheck>

child of cluster

Evaluates user supplied EL expressions to a boolean.

<health:ExprHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
fatal-testEL expression that will trigger FATAL if it evaluates to trueExprN/A
critical-testEL expression that will trigger CRITICAL if it evaluates to trueExprN/A
warning-testEL expression that will trigger WARNING if it evaluates to trueExprN/A
<health:ExprHealthCheck> Conditions
HEALTHSTATUSCONDITION
FATALIf any fatal-test expression evaluates to true
CRITICALIf any critical-test expression evaluates to true
WARNINGIf any warning-test expression evaluates to true
Example: <health:ExprHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:ExprHealthCheck>
    <critical-test>${mbean('java.lang:type=Threading').ThreadCount > 100}</critical-test>
  </health:ExprHealthCheck>

</cluster>

<health:FailSafeRestart>

child of cluster

A timed restart of Resin, normally used in conjunction with an ActionSequence to gather shutdown information

<health:FailSafeRestart> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
timeoutTime to force a restart if one has not yet occurred.PeriodN/A
Example: <health:FailSafeRestart> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:ActionSequence>
    <health:FailSafeRestart timeout="10m"/>
    <health:DumpThreads/>
    <health:DumpHeap/>
    <health:StartProfiler active-time="5m"/>
    <health:Restart/>
    
    <health:IfHealthCritical time="5m"/>
  </health:ActionSequence>

</cluster>

<health:HealthSystem>

child of cluster

Configures overall health checking frequency and recheck rules. This element is present in health.xml for clarity, but is not strictly required since it will be created upon startup with default values.

<health:HealthSystem> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledAll health checking enabled or disabledbooleantrue
startup-delayThe time after startup before actions are triggered (checks still execute).Period15m
periodThe time between checksPeriod5m
recheck-periodThe time between rechecksPeriod30s
recheck-maxThe number of rechecks before returning to the normal checking periodint10
Example: <health:HealthSystem> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:HealthSystem>
    <enabled>true</enabled>
    <startup-delay>15m</startup-delay>
    <period>5m</period>
    <recheck-period>30s</recheck-period>
    <recheck-max>10</recheck-max>
  </health:HealthSystem>

</cluster>

<health:HealthSystemHealthCheck>

child of cluster

Monitors the health system itself by using a separate thread to detect if health checking is frozen or taking too long.

<health:HealthSystemHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
thread-check-periodThe polling frequency of the independent thread.Period1m
freeze-timeoutThe max time for no health checks to occur to declare the health system frozenPeriod15m
<health:HealthSystemHealthCheck> Conditions
HEALTHSTATUSCONDITION
FATALIf health checking has not occurred within freeze-timeout.
FATALIf health checking has not completed within an acceptable time, calculated using <health:HealthSystem>startup-delay, period, and recheck-period.
Example: <health:HealthSystemHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:HealthSystemHealthCheck>
    <thread-check-period>1m</thread-check-period>
    <freeze-timeout>15m</freeze-timeout>
  </health:HealthSystemHealthCheck>
  
</cluster>

<health:HeartbeatHealthCheck>

child of cluster

Monitors for heartbeats from other members of the cluster.

<health:HeartbeatHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
<health:HeartbeatHealthCheck> Conditions
HEALTHSTATUSCONDITION
WARNINGIf no heartbeat has been received from a know member of the cluster.
WARNINGIf a heartbeat has not been received in the last 180 seconds from a known member of the cluster.
Example: <health:HeartbeatHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:HeartbeatHealthCheck/>
  
</cluster>

<health:HttpStatusHealthCheck>

child of cluster

Monitors one or more URLs on the current Resin instance by making an HTTP GET request and comparing the returned HTTP status code to a pattern.

<health:HttpStatusHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
ping-hostThe server's ping host (for use where url is a URI)StringN/A
ping-portThe server's ping port (for use where url is a URI)int80
urlA URL or URI to be testedStringN/A
socket-timeoutThe socket connection timeoutPeriod10s
regexpThe HTTP status regular expressionjava.util.regex.Pattern200
<health:HttpStatusHealthCheck> Conditions
HEALTHSTATUSCONDITION
CRITICALIf the HTTP GET request failed to connect or the status code does not match the regexp.
Example: <health:HttpStatusHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:HttpStatusHealthCheck>
    <ping-host>localhost</ping-host>
    <ping-port>8080</ping-port>
    <url>/custom-test-1.jsp</url>
    <url>/custom-test-2.jsp</url>
    <socket-timeout>2s</socket-timeout>
    <regexp>^2|^3</regexp>
  </health:HttpStatusHealthCheck>

</cluster>

In some clustered configurations it may be simpler to use the <server-default> <ping-url> element rather than specifying the host and port in the health check itself. <ping-url> will dynamically construct a URL using the current server host. To enabled this, configure HttpStatusHealthCheck with no <url> elements and add <ping-url>to <server> or <server-default>.

Example: <health:HttpStatusHealthCheck> using ping-url
<!-- resin.xml -->
<resin xmlns="http://caucho.com/ns/resin">

  <cluster id="web-tier">
    <server-default>
      <ping-url>/ping-test.jsp<ping-url>
    </server-default>
    ...
  </cluster>
</resin>

<!-- health.xml -->
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:HttpStatusHealthCheck ee:Named="serverHttpPingCheck">
    <socket-timeout>5s</socket-timeout>
    <regexp>200</regexp>
  </health:HttpStatusHealthCheck>

</cluster>

<health:IfCron>

child of cluster

Qualify an action to execute if the current time is in an active range configured by cron-style times. This can be used both to schedule regular actions or to prevent restarts or other actions during critical times.

<health:IfCron> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enable-atThe cron enable timesCronTypeN/A
disable-at-atThe cron diable timesCronTypeN/A
Example: <health:IfCron> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfCron>
      <enable-at>0 0 * * *</enable-at>
      <disable-at>5 0 * * *</disable-at>
    </health:IfCron>
  </health:Restart> 

</cluster>

<health:IfExpr>

child of cluster

Qualifies an action to execute based on the evaluation of an JSP EL expression. Expression can include references to system properties, config properties, and JMX mbean attributes.

<health:IfExpr> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
testthe JSP-EL expression valueExprN/A
Example: <health:IfExpr> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfExpr>
      <test>${mbean('java.lang:type=Threading').ThreadCount > 100}</test>
    </health:IfExpr>
  </health:Restart> 

</cluster>

<health:IfHealthCritical>

child of cluster

Qualifies an action to match if health status is CRITICAL.

<health:IfHealthCritical> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
health-checkThe target health checkHealthCheckN/A (Overall Resin health will be used if absent)
timeThe minimum amount of time since the status startedPeriodN/A
Example: <health:IfHealthCritical> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
  </health:Restart> 

</cluster>

<health:IfHealthEvent>

child of cluster

Causes an action to fire in response to a matching health event. This is usually used in combination with AnomalyAnalyzer with a <health-event> attribute.

<health:IfHealthEvent> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
regexpA regular expression the event must match.java.util.regex.Patternrequired
Example: <health:IfHealthEvent> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:JmxMeter>
    <name>JVM|Thread|JVM Blocked Count</name>
    <objectName>resin:type=JvmThreads</objectName>
    <attribute>BlockedCount</attribute>
  </health:JmxMeter>

  <health:AnomalyAnalyzer>
    <meter>JVM|Thread|JVM Blocked Count</meter>
    <health-event>caucho.thread.anomaly.jvm-blocked</health-event>
  </health:AnomalyAnalyzer>

  <health:DumpThreads>
    <health:IfHealthEvent regexp="caucho.thread"/>
    <health:IfNotRecent time="15m"/>
  </health:DumpThreads>
  
</cluster>

<health:IfHealthFatal>

child of cluster

Qualifies an action to match if health status is FATAL.

<health:IfHealthFatal> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
health-checkThe target health checkHealthCheckN/A (Overall Resin health will be used if absent)
timeThe minimum amount of time since the status startedPeriodN/A
Example: <health:IfHealthFatal> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfHealthFatal health-check="${memoryTenuredHealthCheck}"/>
  </health:Restart> 

</cluster>

<health:IfHealthOk>

child of cluster

Qualifies an action to match if health status is OK.

<health:IfHealthOk> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
health-checkThe target health checkHealthCheckN/A (Overall Resin health will be used if absent)
timeThe minimum amount of time since the status startedPeriodN/A
Example: <health:IfHealthOk> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:Not>
      <health:IfHealthOk health-check="${memoryTenuredHealthCheck}"/>
    </health:Not>
  </health:Restart> 

</cluster>

<health:IfHealthUnknown>

child of cluster

Qualifies an action to match if health status is UNKNOWN.

<health:IfHealthUnknown> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
health-checkThe target health checkHealthCheckN/A (Overall Resin health will be used if absent)
timeThe minimum amount of time since the status startedPeriodN/A
Example: <health:IfHealthUnknown> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfHealthUnknown health-check="${memoryTenuredHealthCheck}"/>
  </health:Restart> 

</cluster>

<health:IfHealthWarning>

child of cluster

Qualifies an action to match if health status is WARNING.

<health:IfHealthWarning> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
health-checkThe target health checkHealthCheckN/A (Overall Resin health will be used if absent)
timeThe minimum amount of time since the status startedPeriodN/A
Example: <health:IfHealthWarning> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfHealthWarning health-check="${memoryTenuredHealthCheck}"/>
  </health:Restart> 

</cluster>

<health:IfMessage>

child of cluster

Qualifies an action to match the health result message to a regular expression.

<health:IfMessage> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
health-checkThe target health checkHealthCheckN/A (Overall Resin health will be used if absent)
regexpThe health message match regular expressionjava.util.regex.PatternN/A
Example: <health:IfMessage> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfHealthCritical/>
    <health:IfMessage health-check="${httpStatusCheck}" regexp="Not Found"/>
  </health:Restart> 

</cluster>

<health:IfNotRecent>

child of cluster

Qualifies an action to match at most an amount of time after the last execution. This is usefull to prevent unecessary frequent execution of an action.

<health:IfNotRecent> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
timeThe time before the action can execute again.PeriodN/A
Example: <health:IfNotRecent> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:HttpStatusHealthCheck ee:Named="httpStatusCheck">
    <url>http://localhost:8080/test-ping.jsp</url>
  </health:HttpStatusHealthCheck>
  
  <health:DumpHeap>
    <health:IfHealthCritical healthCheck="${httpStatusCheck}"/>
    <health:IfNotRecent time='5m'/>
  </health:DumpHeap>

</cluster>

<health:IfRecovered>

child of cluster

Qualifies an action to match upon recovery. Recovery is defined as the state change from FATAL, CRITICAL, or WARNING to OK.

<health:IfRecovered> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
health-checkThe target health checkHealthCheckN/A (Overall Resin health will be used if absent)
Example: <health:IfRecovered> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:SendMail>
    <to>admin@yourdomain</to>
    <health:IfRecovered health-check="${cpuHealthCheck}"/>
  </health:SendMail> 

</cluster>

<health:IfRechecked>

child of cluster

Qualifies an action to match only after the required number of rechecks have been performed. Since rechecking is not a health check specific condition, this predicate simply matches when recheck cycle count matches the HealthSystem parameter recheck-max.

<health:IfRechecked> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:IfRechecked> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfHealthFatal/>
    <health:IfRechecked/>
  </health:Restart> 

</cluster>

<health:IfUptime>

child of cluster

Qualifies an action to match an amount of time after startup.

<health:IfUptime> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
limitThe time after startup (at least)PeriodN/A
Example: <health:IfUptime> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfUptime limit="12h"/>
  </health:Restart> 

</cluster>

<health:JmxDeltaMeter>

child of cluster

Creates a meter that graphs the difference between the current and previous values of a numeric JMX MBean attribute.

<health:JmxDeltaMeter> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
nameThe name of the meter to display in /resin-admin (see meter names)StringN/A
objectNameThe JMX MBean nameStringN/A
attributeThe MBean attribute to sampleStringN/A
Example: <health:JmxDeltaMeter> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:JmxDeltaMeter>
    <name>JVM|Compilation|Compilation Time</name>
    <object-name>java.lang:type=Compilation</object-name>
    <attribute>TotalCompilationTime</attribute>
  </health:JmxDeltaMeter>

</cluster>

<health:JmxMeter>

child of cluster

Creates a meter that graphs the current value of a numeric JMX MBean attribute.

<health:JmxMeter> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
nameThe name of the meter to display in /resin-admin (see meter names)StringN/A
objectNameThe JMX MBean nameStringN/A
attributeThe MBean attribute to sampleStringN/A
Example: <health:JmxMeter> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:JmxMeter>
    <name>OS|Memory|Physical Memory Free</name>
    <object-name>java.lang:type=OperatingSystem</object-name>
    <attribute>FreePhysicalMemorySize</attribute>
  </health:JmxMeter>

</cluster>

<health:JvmDeadlockHealthCheck>

child of cluster

Monitors for deadlocked threads, as determined by the JVM.

<health:JvmDeadlockHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
<health:JvmDeadlockHealthCheck> Conditions
HEALTHSTATUSCONDITION
FATALIf deadlocked threads are detected.
Example: <health:JvmDeadlockHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:JvmDeadlockHealthCheck/>

</cluster>

<health:LicenseHealthCheck>

child of cluster

Checks for expiring Resin Pro license.

<health:LicenseHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
warning-periodLicense check warning periodPeriod30D
<health:LicenseHealthCheck> Conditions
HEALTHSTATUSCONDITION
WARNINGIf license expires in less than warning-period.
Example: <health:LicenseHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:LicenseHealthCheck>
    <warning-period>30D</warning-period>
  </health:LicenseHealthCheck>

</cluster>

<health:MemoryPermGenHealthCheck>

child of cluster

Monitors the amount of free memory in the JVM PermGen memory pool. Requests a garbage collection if memory falls too low.

Note: This check does not apply to all JVM vendor implementations, and will report UNKNOWN if there is no PermGen pool.

<health:MemoryPermGenHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
memory-free-minThe critical minimum amount of free memory.Bytes1m
free-warningThe warning threshold percentage.double (percentage 0.0 - 100.0)0.01
objectNameExplicitly set the MBean name to query for memory stats. When left unset the health check will search available MBeans for the appropriate memory stats MBean.javax.management.ObjectNameN/A
<health:MemoryPermGenHealthCheck> Conditions
HEALTHSTATUSCONDITION
UNKNOWNIf there is no PermGen pool (JVM vendor dependent) or the appropriate MBean could not be determined.
WARNINGIf free memory is below free-warning percentage after a GC.
CRITICALIf free memory is below memory-free-min after a GC.
Example: <health:MemoryPermGenHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:MemoryPermGenHealthCheck>
    <memory-free-min>1m</memory-free-min>
    <free-warning>0.01</free-warning>
  </health:MemoryPermGenHealthCheck>

</cluster>

<health:MemoryTenuredHealthCheck>

child of cluster

Monitors the amount of free memory in the JVM Tenured memory pool. Requests a garbage collection if memory falls too low. This check will monitor heap memory on JVMs where there is no tenured pool.

Note: memory-free-min will default to the value of <server> <memory-free-min> if present in resin.xml.

<health:MemoryTenuredHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
memory-free-minThe critical minimum amount of free memory.Bytes1m
free-warningThe warning threshold percentage.double (percentage 0.0 - 100.0)0.01
objectNameExplicitly set the MBean name to query for memory stats. When left unset the health check will search available MBeans for the appropriate memory stats MBean.javax.management.ObjectNameN/A
<health:MemoryTenuredHealthCheck> Conditions
HEALTHSTATUSCONDITION
UNKNOWNIf there is no PermGen pool (JVM vendor dependent) or the appropriate MBean could not be determined.
WARNINGIf free memory is below free-warning percentage after a GC.
CRITICALIf free memory is below memory-free-min after a GC.
Example: <health:MemoryTenuredHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:MemoryTenuredHealthCheck>
    <memory-free-min>1m</memory-free-min>
    <free-warning>0.01</free-warning>
  </health:MemoryTenuredHealthCheck>

</cluster>

<health:Nand>

child of cluster

Qualifies an action to match if all of the child predicates fail.

<health:Nand> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:Nand> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:Nand>
      <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
      <health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/>      
    </health:Nand>
  </health:Restart> 

</cluster>

<health:Nor>

child of cluster
javadoc <health:Nor>

Qualifies an action to match if none of the child predicates match.

<health:Nor> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:Nor> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:Nor>
      <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
      <health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/>      
    </health:Nor>
  </health:Restart> 

</cluster>

<health:Not>

child of cluster
javadoc <health:Not>

Qualifies an action to match if the child predicate is false.

<health:Not> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:Not> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
    <health:Not>
      <health:IfCron>
        <enable-at>0 7 * * *</enable-at>
        <disable-at>0 11 * * *</disable-at>
      </health:IfCron>
    </health:Not>
  </health:Restart> 

</cluster>

<health:OnAbnormalStop>

child of cluster

Qualifies an action to match only when Resin is stopping with an non-OK exit code.

<health:OnAbnormalStop> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
normal-exit-codeAdd an OK exit code; one that will not trigger this condition.com.caucho.env.shutdown.ExitCode[OK,MODIFIED,WATCHDOG_EXIT]
Example: <health:OnAbnormalStop> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:PdfReport snapshot='true'>
    <health:OnAbnormalStop/>
  </health:PdfReport 

</cluster>

<health:OnRestart>

child of cluster

Qualifies an action to match only when Resin is restarted by the watchdog. This generally only occurs during an error condition. OnStart will fire during this event also.

<health:OnRestart> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:OnRestart> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:SendMail>
    <to>admin@yourdomain.com</to>
    <health:OnRestart/>
  </health:SendMail> 

</cluster>

<health:OnStart>

child of cluster

Qualifies an action to match only when Resin is starting.

<health:OnStart> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:OnStart> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:SendMail>
    <to>admin@yourdomain.com</to>
    <health:OnStart/>
  </health:SendMail> 

</cluster>

<health:OnStop>

child of cluster

Qualifies an action to match only when Resin is stopping.

<health:OnStop> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:OnStop> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:SendMail>
    <to>admin@yourdomain.com</to>
    <health:OnStop/>
  </health:SendMail> 

</cluster>

<health:Or>

child of cluster
javadoc <health:Or>

Qualifies an action to match if any of the child predicates match.

<health:Or> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:Or> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:Restart>
    <health:Or>
      <health:IfHealthCritical health-check="${memoryTenuredHealthCheck}"/>
      <health:IfHealthCritical health-check="${memoryPermGenHealthCheck}"/>      
    </health:Or>
  </health:Restart> 

</cluster>

<health:PdfReport>

child of cluster

Health action to generate a PDF report from a PHP script.

<health:PdfReport> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
pathPath to a PDF generating .php fileString${resin.home}/doc/admin/pdf-gen.php
reportReport type keyStringSummary
periodReport look back period of timePeriod7D
log-pathPDF output directoryString${resin.logDirectory}
Example: <health:PdfReport> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:PdfReport>
    <path>${resin.home}/doc/admin/pdf-gen.php</path>
    <report>Summary</report>
    <period>7D</report>
    <health:IfCron value="0 0 * * 0"/>
  </health:PdfReport>

</cluster>

<health:Restart>

child of cluster

Restart Resin. Resin will exit with the reason HEALTH.

<health:Restart> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
None
Example: <health:Restart> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:Restart/>

</cluster>

<health:ScoreboardReport>

child of cluster

Produces a concise thread activity report for groups of related threads.

Note: A scoreboard report can also be produced using the scoreboard command line.

<health:ScoreboardReport> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
logOutput to server log in addition to pdf reportBooleanfalse
typeScoreboard report typeStringresin
greedyIf false threads can be categoried into more than one groupBooleantrue
Example: <health:ScoreboardReport> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:ScoreboardReport>
    <health:OnAbnormalStop/>
  </health:ScoreboardReport>

</cluster>

<health:SetJmxAttribute>

child of cluster

Sets a JMX attribute to a value.

Note: Setting a JMX attribute can also be performed on-demand using the jmx-set command line.

<health:SetJmxAttribute> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
objectNameThe JMX MBean nameStringN/A
attributeThe attribute nameStringN/A
valueNew attribute value that will be converted to the appropriate type.StringN/A
Example: <health:SetJmxAttribute> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:SetJmxAttribute>
    <objectName>java.lang:type=ClassLoading</objectName>
    <attribute>Verbose</attribute>
    <value>true</value>
    <health:OnStart/>
  </health:SetJmxAttribute>

</cluster>

<health:SendMail>

child of cluster

Send an email containing a summary of the current Resin health status.

<health:SendMail> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
toA "TO:" address; a mail recipientStringN/A
fromThe "FROM:" addressStringresin@localhost
mailA <mail> resource to use, see examplejavax.mail.SessionN/A

Without the mail parameter, the default behaviour for sending mail is to contact an SMTP server at host 127.0.0.1 (the localhost) on port 25. System properties can be used to configure a different SMTP server.

resin.xml - smtp server configuration
  <system-property mail.smtp.host="127.0.0.1"/>
  <system-property mail.smtp.port="25"/>
Example: <health:SendMail> in health.xml using system properties
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:SendMail>
    <to>admin@yourdomain.com</to>
    <to>another_admin@yourdomain.com</to>
    <from>resin@yourdomain.com</from>
  <health:SendMail>

</cluster>

Much more advanced SMTP options can be set by configuring a <mail> resource to use for sending health alerts.

Example: <health:SendMail> in health.xml referencing a <mail> resource
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <mail name="healthMailer">
    <smtp-host>mail.yourdomain.com</smtp-host>
    <smtp-port>25</smtp-port>
    <from>resin@yourdomain.com</from>
  </mail>
  
  <health:SendMail mail="${healthMailer}">
    <to>admin@yourdomain.com</to>
  <health:SendMail>

</cluster>

<health:SetJmxAttribute>

child of cluster

Sets a JMX attribute to a value.

Note: Setting a JMX attribute can also be performed on-demand using the jmx-set command line.

<health:SetJmxAttribute> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
objectNameThe JMX MBean nameStringN/A
attributeThe attribute nameStringN/A
valueNew attribute value that will be converted to the appropriate type.StringN/A
Example: <health:SetJmxAttribute> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:SetJmxAttribute>
    <objectName>java.lang:type=ClassLoading</objectName>
    <attribute>Verbose</attribute>
    <value>true</value>
    <health:OnStart/>
  </health:SetJmxAttribute>

</cluster>

<health:Snapshot>

child of cluster

A specific sequence of health actions: thread dump, heap dump, jmx dump, and pdf report. This is intended to generate a permanent representation, or "snapshot" of the system at a point in time that includes all the information necessary to debug server issues. It is usually intended to run in response to a unexpected issue.

<health:Snapshot> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
logOutput to server log in addition to pdf reportBooleanfalse
pathPath to a PDF generating .php fileString${resin.home}/doc/admin/pdf-gen.php
reportReport type keyStringSummary
periodReport look back period of timePeriod7D
Example: <health:Snapshot> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:Snapshot>
    <health:OnAbnormalStop/>
  </health:Snapshot>
  
</cluster>

<health:StartProfiler>

child of cluster

Starts a profiler session. Results are logged to the internal database and the Resin log file at INFO level.

Note: Starting the profiler can also be performed on-demand using the profile command line, and from /resin-admin.

<health:StartProfiler> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
active-timeThe amount of time to run the profilerPeriod5s
sampling-rateThe sampling ratePeriod10ms
depthThe stack trace depth (use smaller number (8) for smaller impact, larger for more information.)int16
Example: <health:StartProfiler> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">
         
  <health:ActionSequence>
    <health:FailSafeRestart timeout="10m"/>
    <health:DumpThreads/>
    <health:DumpHeap/>
    <health:StartProfiler active-time="5m"/>
    <health:Restart/>
    
    <health:IfHealthCritical time="5m"/>
  </health:ActionSequence>

</cluster>

<health:TransactionHealthCheck>

child of cluster

Monitors the Resin transaction manager for commit failures.

<health:TransactionHealthCheck> Attributes
ATTRIBUTEDESCRIPTIONTYPEDEFAULT
enabledCheck is enabled or disabledbooleantrue
<health:TransactionHealthCheck> Conditions
HEALTHSTATUSCONDITION
WARNINGIf there were commit failures since the last check.
Example: <health:TransactionHealthCheck> in health.xml
<cluster xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:health="urn:java:com.caucho.health"
         xmlns:ee="urn:java:ee">

  <health:TransactionHealthCheck/>

</cluster>

<home-cluster>

child of home-cluster

The <home-cluster> specifies the default --cluster value for dynamic servers. When Resin starts and elastic server, it looks for a <home-cluster> if the --cluster option is missing. The home cluster will be cluster that the Resin server tries to join.

<home-cluster> schema
element home-cluster {
  string
}

<host>

child of cluster

<host> configures a virtual host. Virtual hosts must be configured explicitly.

It is recommended that any <host> using a regexp include a <host-name> to set the canonical name for the host.

<host> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
idprimary host namenone
regexpRegular expression based host matchingnone
host-nameCanonical host namenone
host-aliasAliases matching the same hostnone
secure-host-nameHost to use for a redirect to SSLnone
root-directoryRoot directory for host filesparent directory
startup-mode'automatic', 'lazy', or 'manual', see startup-modeautomatic
Example: explicit host
<host host-name="www.foo.com">
  <host-alias>foo.com</host-alias>
  <host-alias>web.foo.com</host-alias>

  <root-directory>/opt/www/www.foo.com</root-directory>

  <web-app id="/" root-directory="webapps/ROOT">
    
  </web-app>
  ...
</host>
Example: regexp host
<host regexp="([^.]+)\.foo\.com">
  <host-name>${host.regexp[1]}.foo.com</host-name>

  <root-directory>/var/resin/hosts/www.${host.regexp[1]}.com</root-directory>

  ...
</host>

<host-alias>

child of host

<host-alias> defines a URL alias for matching HTTP requests. Any number of <host-alias> can be used for each alias.

The host-alias can be used either in the resin.xml or in a host.xml when use host-deploy together with resin:import.

Since the <host-deploy> and <host> tags lets you add a host.xml file to customize configuration, the <host-alias> can also fit in the custom host.xml page.

<host-alias> schema
element host-alias {
  string
}
Example: host-alias in the resin.xml
<resin xmlns="http://caucho.com">
<cluster id="">

  <host id="www.foo.com" root-directory="/var/resin/foo.com">
    <host-alias>foo.com</host-alias>

    <web-app id=""/>
  </host>

</cluster>
</resin>
Example: host-alias in a /var/resin/hosts/foo/host.xml
<host xmlns="http://caucho.com">

  <host-name>www.foo.com</host-name>
  <host-alias>foo.com</host-alias>

  <web-app id="" root-directory="htdocs"/>

</host>

<host-alias-regexp>

child of host

<host-alias-regexp> defines a regular expression for matching URLs for a given virtual host.

<host-alias-regexp> schema
element host-alias-regexp {
  string
}
Example: host-alias-regexp in the resin.xml
<resin xmlns="http://caucho.com">
<cluster id="">

  <host id="www.foo.com" root-directory="/var/resin/foo.com">
    <host-alias-regexp>.*foo.com</host-alias-regexp>

    <web-app id=""/>
  </host>

</cluster>
</resin>

<host-default>

child of cluster

Defaults for a virtual host.

The host-default can contain any of the host configuration tags. It will be used as defaults for any virtual host.

<host-deploy>

child of cluster

<host-deploy> configures an automatic deployment directory for virtual hosts.

The host-deploy will add an EL variable ${host.name}, referring to the name of the host jar file.

<host-deploy> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
archive-directorypath to the archive directorypath
pathpath to the deploy directoryrequired
expand-cleanup-filesetan ant-style fileset defining which directories to cleanup when an archive is redeployed
expand-directorypath to the expansion directorypath
host-defaultdefaults for the expanded host
host-namethe default hostname, based on the directory${name}
<host-deploy> schema
element host-deploy {
  archive-directory?
  & expand-cleanup-fileset?
  & expand-directory?
  & host-default?
  & host-name?
  & path?
}

The following example configures /var/resin/hosts as a host deployment directory. Each virtual host will have a webapps directory for .war deployment. So the directory /var/resin/hosts/www.foo.com/webapps/bar/test.jsp would serve the URL http://www.foo.com/bar/test.jsp.

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

    <host-deploy path="hosts">
      <host-default>
        <resin:import path="host.xml" optional="true"/>

        <web-app-deploy path="webapps"/>
      </host-default>
    </host-deploy>
  </cluster>
</resin>

<host-name>

child of host

<host-name> defines the canonical name for a virtual host. The <host-name> will be used in Resin's logging, management, and is available in the host's variables.

<host-name> schema
element host-name {
  string
}

<http>

child of server

<http> configures a HTTP or HTTPS port listening for HTTP requests.

When configuring multiple JVMs, each <http> will have a unique <server-id> which allows the -server command-line to select which ports the server should listen to.

note
Note
The virtual-host attribute overrides the browser's Host directive, specifying the explicit host and port for request.getServerName() and getServerPort(). It is not used in most virtual host configurations. Only IP-based virtual hosts which wish to ignore the browser's Host will use @virtual-host.
<http> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
address/hostIP address of the interface to listen to*
portport to listen torequired
accept-listen-backlogconfigures operating system TCP listen queue size for the port4000
accept-thread-idle-timeoutconfigures minimum spare accept-thread idle timeout120s
accept-thread-minconfigures the minimum number of threads listening for new connections 1
accept-thread-maxconfigures the maximum number of threads listening for new connectionsunbound
keepalive-connection-time-maxconfigures an absolute max time for keepalive connections600s
keepalive-maxconfigures the maximum number of sockets which can be used directly for keepalive connections256
keepalive-select-enableenables the select manager for keepalivestrue
keepalive-select-thread-timeoutconfigures a short timeout allowing the select manager to wait for a keepalive before detaching the thread1s
keepalive-timeoutconfigures how long a keepalive connection should wait for a new request before closing120s
suspend-reaper-timeoutconfigures check interval for suspended (async)connections60s
suspend-time-maxconfigures timeout for suspended (async) connections600s
socket-timeoutconfigures timeout for accepted socket's write and read operations120s
throttle-concurrent-maxconfigures maximum concurrent requests (Resin Pro)unlimited
tcp-no-delaysets the NO_DELAY socket parametertrue
socket-listen-backlogThe socket factory's listen backlog for receiving sockets100
virtual-hostforces all requests to this <http> to use the named virtual hostnone
opensslconfigures the port to use OpenSSLnone
jsse-sslconfigures the port to use JSSE for SSLnone
<http> schema
element http {
  (id | server-id)
  & (address | host )?
  & port?
  & accept-listen-backlog?
  & accept-thread-idle-timeout?
  & accept-thread-min?
  & accept-thread-max?
  & connection-max?
  & keepalive-connection-time-max?
  & keepalive-max?
  & keepalive-select-enable?
  & keepalive-select-thread-timeout?
  & keepalive-timeout?
  & secure?
  & socket-timeout?
  & suspend-reaper-timeout?
  & suspend-time-max?
  & tcp-no-delay?
  & throttle-concurrent-max?
  & virtual-host?
  & (openssl | jsse-ssl)?
}

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

<ignore-client-disconnect>

child of cluster
default true

ignore-client-disconnect configures whether Resin should ignore disconnection exceptions from the client, or if it should send those exceptions to the application.

<ignore-client-disconnect> schema
element ignore-client-disconnect {
  r_boolean-Type
}

<invocation-cache-size>

child of cluster
default 8192

Configures the number of entries in the invocation cache. The invocation cache is used to store pre-calculated servlet and filter chains from the URLs. It's also used as the basis for proxy caching.

<invocation-cache-size> schema
element invocation-cache-size {
  r_int-Type
}

<invocation-cache-max-url-length>

child of cluster
default 256

Configures the longest entry cacheable in the invocation cache. It is used to avoid certain types of denial-of-service attacks.

<invocation-cache-max-url-length> schema
element invocation-cache-max-url-length {
  r_int-Type
}

<javac>

default internal

<javac> configures the Java compiler for automatically compiled files.

The javac configuration is used for JSP, PHP, EJB and compiling-loader configuration. Thus you can deploy JSPs to Resin and it will use the compiler to generate classes at runtime. In other words, you do not need to precompile your JSPs, Java files, et al. to deploy them on Resin.

The internal compiler (recommended) requires tools.jar from the JDK installation, so a JDK must be used (not a JRE). Sometimes the internal compiler causes errors, creating exceptions or simply hanging and taking up a thread. The solution is to change the compiler to use an external compiler.

The javac compiler is included with the JDK. It performs the same function as the internal compiler, however it is executed as an external process and is less prone to the problems described for the internal compiler. In resin.xml with the javac configuration option:

<javac> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
argsextra arguments to pass to the compiler
compilerthe compiler name: eclipse, internal, or a command-line
encodingthe character encoding to useutf-8
max-batchthe maximum number of source files to batch into one compilation64
<javac> schema
element javac {
  args*
  & compiler
  & encoding?
  & max-batch?
}
Internal compiler
<resin xmlns="http://caucho.com/ns/resin">

 <javac compiler="internal" args=""/>

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

 <javac compiler="javac" args=""/>

  ...

</resin>

<jndi-link>

<jndi-link> creates a symbolic link from one jndi name to another, or links to a foreign JNDI context.

Resin's JNDI can link to foreign JNDI contexts. For example, third-party EJB servers will often expose their EJB beans through a JNDI context. jndi-link will create the appropriate InitialContextFactory, configure it, and lookup the foreign JNDI objects.

<jndi-link> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
factoryClass name of the JNDI InitialContextFactory. Since Resin 1.2optional
foreign-nameThe target name of the symbolic link, or the sub-context of the foreign JNDI context. Since Resin 1.2none
init-paramConfiguration parameters for the JNDI environment passed to InitialContextFactory. Since Resin 1.2none
jndi-nameThe JNDI name to use for the link. Resin 3.0required
<jndi-link> schema
element jndi-link {
  jndi-name
  & factory?
  & foreign-name?
  & init-param*
}
Example: A JNDI symbolic link for a DataSource
<web-app xmlns="http://caucho.com/ns/resin"dd>
  <database jndi-name="jdbc/oracle">
    ...
  </database>

  <jndi-link jndi-name="java:comp/env/jdbc/gryffindor">
    <foreign-name>java:comp/env/jdbc/oracle</foreign-name>
  </jndi-link>

  <jndi-link jndi-name="java:comp/env/jdbc/slytherin">
    <foreign-name>java:comp/env/jdbc/oracle</foreign-name>
  </jndi-link>
</web-app>
Example: A JNDI foreign context for all EJB
<web-app xmlns="http://caucho.com/ns/resin">
  <jndi-link jndi-name='java:comp/env/ejb'>
    <factory>com.caucho.ejb.hessian.HessianContextFactory</factory>
    <init-param java.naming.provider.url='http://ejb.hogwarts.com:80/hessian'/>
  </jndi-link>
</web-app>
Example: A JNDI foreign context for selected EJB
<web-app xmlns="http://caucho.com/ns/resin">
  <jndi-link jndi-name='java:comp/env/remote-ejb'>
    <factory>com.caucho.ejb.hessian.HessianContextFactory</factory>
    <init-param java.naming.provider.url='http://ejb.hogwarts.com:80/hessian'/>
  </jndi-link>

  <jndi-link jndi-name="java:comp/env/ejb/Foo">
    <foreign-name>java:comp/env/remote-ejb/Foo</foreign-name>
  </jndi-link>

  <jndi-link jndi-name="java:comp/env/ejb/Bar">
    <foreign-name>java:comp/env/local-ejb/Bar</foreign-name>
  </jndi-link>
</web-app>

<jpa-persistence>

<jpa-persistence> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
create-database-schemaIf true, Amber will automatically create the database schemafalse
cache-sizeSize of the entity cache32k
data-sourcedatabase used for JTA
jdbc-isolationJDBC isolation level used for connections
read-data-sourceData source to be used for read-only queriesdata-source
validate-database-schemaenables validation of the database tables on startupfalse
xa-data-sourcedatabase to use in transactionsdata-source
<jpa-persistence> schema
element jpa-persistence {
  create-database-schema?
  & cache-size?
  & cache-timeout?
  & data-source?
  & jdbc-isolation?
  & persistence-unit*
  & persistence-unit-default*
  & read-data-source?
  & validate-database-schema?
  & xa-data-source?
}

element persistence-unit {
  name
  & jta-data-source?
  & non-jta-data-source?
  & provider?
  & transaction-type?
  & properties?
}

element persistence-unit-default {
  & jta-data-source?
  & non-jta-data-source?
  & provider?
  & transaction-type?
  & properties?
}

element properties {
  element property {
     name
     & value
  }*
}

<jpa-persistence-unit>

Replacement for jpa-persistence.

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

<jvm-arg>

child of server

<jvm-arg> configures JVM arguments to be passed to Resin on the command line, typically -X memory parameters and -D defines.

standard jvm-args
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
      <jvm-arg>-Xmx512m</jvm-arg>
      <jvm-arg>-Xss1m</jvm-arg>
      <jvm-arg>-verbosegc</jvm-arg>
    </server-default>

    <server id="app-a" address="192.168.2.10"/>

    ...
  </cluster>
</resin>

<jvm-classpath>

child of server

<jvm-classpath> adds a classpath entry when starting the JVM.

adding a classpath
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
      <jvm-classpath>/tmp/test-classpath;/jvm-classpath>
    </server-default>

    <server id="app-a" address="192.168.2.10"/>

    ...
  </cluster>
</resin>

<keepalive-max>

child of server
default 100

<keepalive-max> configures the maximum number of sockets which can be used directly for keepalive connections. In Resin Professional, the select manager allows for a much larger number of keepalive sockets, since it can detach threads from connections. Without the select manager, each connection is associated with a thread.

A value of -1 disables keepalives.

Keepalives are an important TCP technique used with HTTP and Resin's load-balancing to avoid the heavy network cost of creating a new socket. Since an initial HTTP request is usually immediately followed by extra requests to load files like images and stylesheets, it's generally more efficient to keep the socket open for a short time instead of creating a new one. The socket keepalive is even more important for Resin's load balancing, to avoid creating extra sockets between the web-tier and the app-tier and to make distributed sessions more efficient.

Higher values of <keepalive-max> improve network efficiency but increase the number of threads waiting for new client data.

keepalive-thread-max in resin.xml
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
      <http port="80"/>

      <thread-max>512</thread-max>

      <keepalive-max>100</keepalive-max>
    </server-default>

    <server id="web-a" address="192.168.0.10"/>
        ...
  </cluster>
</resin>

<keepalive-select-enable>

child of server
default true

<keepalive-select-enable> enables the select manager for keepalives. The select manager is a Resin Professional feature allowing more keepalives by detaching threads from sockets.

Normally, this should be left enabled.

<keepalive-select-thread-timeout>

child of server
default 1s

<keepalive-select-thread-timeout> is a short timeout allowing the select manager to wait for a keepalive before detaching the thread. This value would not normally be changed.

<keepalive-timeout>

child of server
default 15s

<keepalive-timeout> configures how long a keepalive connection should wait for a new request before closing.

Keepalives are used both for HTTP connections and for load-balancing and clustering connections. HTTP connections generally have a single HTML page, followed by a number of image requests. By using keepalives, all the requests can use a single socket. The <keepalive-timeout> should be long enough to catch all the HTTP burst requests, but can close after the burst is complete. A value of 5s or 15s is generally sufficient.

The load-balancing and clustering keepalives have a different timeout behavior. Since load-balancing sockets are reused for multiple clients, they can have longer timeouts.

keepalive-thread-max in resin.xml
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
      <http port="80"/>

      <thread-max>512</thread-max>

      <keepalive-max>100</keepalive-max>
      <keepalive-timeout>15s</keepalive-timeout>
    </server-default>

    <server id="web-a" address="192.168.0.10"/>
        ...
  </cluster>
</resin>

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

<library-loader>

child of class-loader

<library-loader> configures a jar library, WEB-INF/lib-style class loader.

The library-loader will add jar files in its path to the current classpath. Jar files are recognized wihen they have a filename extension of .jar or .zip.

See DirectoryLoader.

<library-loader> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
filesetAn ant-style fileset
pathFilesystem path for the class loader. Since Resin 3.0required
<library-loader> schema
element library-loader {
  fileset
  | path
}

element fileset {
  dir
  & exclude*
  & include*
}

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

<load-balance-connect-timeout>

child of server
default 5s

<load-balance-connect-timeout> configures the maximum time a client connection to a cluster-port should take. The load balance and persistent sessions use load-balance-connect-timeout to connect to backend or peer servers in the cluster.

Lower values detect failed servers more quickly, but a too-low value can timeout too quickly for a live server with some network congestion.

load-balance-connect-timeout
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <server-default>
          <load-balance-connect-timeout>2s</load-balance-connect-timeout>
        </server-default>

        <server id="a" address="192.168.0.10" port="6800"/>
        <server id="b" address="192.168.0.11" port="6800"/>

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

<load-balance-recover-time>

child of server
default 15s

<load-balance-recover-time> is the maximum time the load balancer will consider the server dead after a failure before retrying the connection.

Resin uses the load-balance-recover-time to avoid wasting time trying to connect to an unavailable app-tier server.

Lower values let the load balancer use a restarted app-tier server faster, but lower values also increase the overhead of trying to contact unavailable servers.

load-balance-recover-time
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <server-default>
          <load-balance-recover-time>10s</load-balance-recover-time>
        </server-default>

        <server id="a" address="192.168.0.10" port="6800"/>
        <server id="b" address="192.168.0.11" port="6800"/>

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

<load-balance-idle-time>

child of server
default keepalive-timeout - 1s

<load-balance-idle-time> is the maximum time the load balancer and distributed sessions will leave an idle socket before closing it.

The default value is normally sufficient, since it tracks the keepalive of the cluster port.

load-balance-idle-time must be less than the keepalive value of the target cluster-port.

The load balancer and distributed sessions reuse sockets to the cluster peer and app-tier servers to improve TCP performance. The load-balance-idle-time limits the amount of time those sockets can remain idle.

Higher values may improve the socket pooling, but may also increase the chance of connecting to a closed server.

<load-balance-warmup-time>

child of server
default 60s

The time the load balancer uses to throttle connections to an app-tier server that's just starting up.

Java web-applications often start slowly while they initialize caches. So a newly-started application will often be slower and consume more resources than a long-running application. The warmup-time increases Resin's reliability by limiting the number of requests to a new app-tier server until the server has warmed up.

Larger values give the application a longer time to warm up.

load-balance-warmup-time
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <server-default>
          <load-balance-warmup-time>60s</load-balance-warmup-time>
        </server-default>

        <server id="a" address="192.168.0.10" port="6800"/>
        <server id="b" address="192.168.0.11" port="6800"/>

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

<load-balance-weight>

child of server
default 100

load-balance-weight assigns a load-balance weight to a backend server. Servers with higher values get more requests. Servers with lower values get fewer requests.

In some cases, some app-tier servers may be more powerful than others. load-balance-weight lets the load-balancer assign more connections to the more powerful machines.

Test and profiling servers can also use load-balance-weight to receive a small number of connections for profiling purposes.

Larger values tell the load-balancer to assign more requests to the app-tier server.

load-balance-weight
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <server id="a" address="192.168.0.10" port="6800"/>
        <server id="b" address="192.168.0.10" port="6800"/>

        <server id="test" address="192.168.0.100" port="6800">
            <load-balance-weight>1</load-balance-weight>
        </server>

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

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

<log-handler>

Configure a log handler for the JDK java.util.logging.* API. java.util.logging has two steps: configure a set of log handlers, and configure the levels for each logger. The <log-handler> creates a destination for logs, sets a minimum logging level for the handler, and attaches the handler to a logging name.

In addition to configuring custom handlers, <log-handler> has the most common configuration build-in: logging to a rotating file. Most of the configuration attributes are used for the rotating file and are shared with the other logging configuration.

<log-handler> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
archive-formatthe format for the archive filename when a rollover occurs, see Rollovers. see below
classconfigures a custom Handler class
formatAn EL expression string to format the current output line.
formatterConfigures a custom java.util.logging.Formatter to format the output.
levelThe log level for the handler. Typically, the handler's level will be finer than the logger's levelinfo
mbean-namean mbean name, see MBean control.no mbean name, no mbean registration
nameA hierarchical name, typically aligned with the Java packaging names. The handler will be registered with the Logger with the matching name.match all names
pathOutput path for the log messages, see "Log Paths"required
path-formatSelects a format for generating path names. The syntax is the same as for archive-formatoptional
timestampa timestamp format string to use at the beginning of each log line. "[%Y/%m/%d %H:%M:%S.%s] "
rollover-countmaximum number of rollover files before the oldest ones get overwritten. See Rollovers. none
rollover-croncron-style specification on rollover times.none
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
<log-handler> schema
element log-handler {
  archive-format?
  & class?
  & filter?
  & format?
  & formatter?
  & level?
  & mbean-name?
  & name
  & path?
  & path-format?
  & rollover-count?
  & rollover-period?
  & rollover-size?
  & timestamp?
  & use-parent-handlers?
}

The following example is a standard log handler writing to a rollover file. Because the handler's level is "all", the <logger> configuration will set the actual logging level.

Example: logging to a rollover file
<web-app xmlns="http://caucho.com/ns/resin">

  <log-handler name="" level="all"
       timestamp="[%Y/%m/%d %H:%M:%S.%s] {%{thread}} "/>

  <logger name="com.caucho" level="info"/>

</web-app>

<logger>

<log> configures JDK 1.4 java.util.logger Logger level.

The log configuration describes log in detail.

<logger> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
levelthe java.util.logging level: finest, finer, fine, config, info, warning, severeinfo
namethe java.util.logging name, typically a classnamerequired
use-parent-handlersif true, parent handlers are also invokedtrue
<logger> schema
element logger {
  name
  & level?
  & use-parent-handlers?
}
Example: compilation logging
<resin xmlns="http://caucho.com/ns/resin">
  <log name="" level="all" path="log/debug.log"/>
  <logger name="com.caucho.java" level="fine"/>

  <cluster id="app-tier">
    ...
  </cluster>
</resin>
Example: logging to a JMS queue
<web-app xmlns="http://caucho.com/ns/resin"
    xmlns:resin="urn:java:com.caucho.resin">

  <resin:MemoryQueue ee:Named="myQueue"/>

  <logger name="qa.test">
    <resin:JmsLogHandler level="warning">
      <target>${myQueue}</target>

      <resin:TimestampLogFormatter/>
    </resin:JmsLogHandler>
  </logger>

</web-app>

Log format string

The format for log tags is used to specify a format string for each log message. format recognizes EL-expressions. The EL variable log is a com.caucho.log.ELFormatter.ELFormatterLogRecord object.

log format string

<log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
     format=" ${log.level} ${log.loggerName} ${log.message}"/>

log EL variable 'log' is a LogRecord
ACCESSORVALUE
${log.level}The level of the log record
${log.name}The source loggers name
${log.shortName}A shorter version of the source loggers name, "Foo" instead of "com.hogwarts.Foo"
${log.message}The message, with no formatting or localization
${log.millis}event time in milliseconds since 1970
${log.sourceClassName}Get the name of the class that issued the logging request (may not be available at runtime)
${log.sourceMethodName}Get the name of the method that issued the logging request (may not be available at runtime)
${log.threadID}Get an int identifier of the thread where the logging request originated
${log.thrown}Get any java.lang.Throwable associated with the logging request

You can also use the Environment EL variables in your format string:

log format string using an Environment EL variable.
<host ...>

  <web-app>
    <log name='' level='all' path='log/debug.log' timestamp="[%H:%M:%S.%s]"
         format=" [${app.contextPath}] ${log.message}"/>

    ...
  </web-app>

  ...

</host>
[14:55:10.189] [/foo] `null' returning JNDI java:
       model for EnvironmentClassLoader[web-app:http://localhost:8080/foo]
[14:55:10.189] [/foo] JNDI lookup `java:comp/env/caucho/auth'
       exception javax.naming.NameNotFoundException: java:comp/env/caucho/auth
[14:55:10.199] [/foo] Application[http://localhost:8080/foo] starting

The fmt.sprintf() function can space pad the values and make the results look a little nicer:

fmt.sprintf() in log format string
<log name='' level='all' path='stderr:' timestamp="[%H:%M:%S.%s]"
     format=" ${fmt.sprintf('%-7s %45s %s',log.level,log.loggerName,log.message)}"/>
[14:28:08.137] INFO com.caucho.vfs.QJniServerSocket Loaded Socket JNI library.
[14:28:08.137] INFO com.caucho.server.port.Port http listening to *:8080
[14:28:08.137] INFO com.caucho.server.resin.ServletServer ServletServer[] starting
[14:28:08.307] INFO com.caucho.server.port.Port hmux listening to localhost:6802
[14:28:08.437] INFO com.caucho.server.host.Host Host[] starting 

fmt.sprintf() and fmt.timestamp() can be used to produce CSV files:

CSV log files
<log name='' level='all' path='log/debug.csv' timestamp=""
     format="${fmt.sprintf('%vs,%d,%d,%vs,%vs',fmt.timestamp('%Y-%m-%d %H:%M:%S.%s'), 
               log.threadID, log.level.intLevel(), log.loggerName, log.message)}"/>
"2003-11-17 14:46:14.529",10,800,"com.caucho.vfs.QJniServerSocket",
            "Loaded Socket JNI library."
"2003-11-17 14:46:14.549",10,800,"com.caucho.server.port.Port",
            "http listening to *:8080"
"2003-11-17 14:46:14.549",10,800,"com.caucho.server.resin.ServletServer",
            "ServletServer[] starting"
"2003-11-17 14:46:14.719",10,800,"com.caucho.server.port.Port",
            "hmux listening to localhost:6802"
"2003-11-17 14:46:14.850",10,800,"com.caucho.server.host.Host",
            "Host[] starting"
"2003-11-17 14:46:15.100",10,800,"com.caucho.server.webapp.Application",
            "Application[http://localhost:8080/freelistbm] starting"

<mail>

<mail> configures a javax.mail.Session object and makes it available in Resin-IoC/WebBeans. Mail properties can be configured using the properties attribute. Some of the most common properties can be configured directly on the <mail> tag.

<mail> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
authenticatorsets a custom javamail authenticator, either with EL or a custom resin:type bean
debugsets the mail.debug flag
fromsets the mail.from property
hostsets the mail.host property
imap-hostsets the mail.imap.host property
imap-portsets the mail.imap.port property
imap-usersets the mail.imap.user property
initIoC configuration for other properties
jndi-nameJNDI name to store the mail Session
nameResin-IoC/WebBeans @Named value
passwordsets the password for authentication
pop3-hostsets the mail.pop3.host property
pop3-portsets the mail.pop3.port property
pop3-usersets the mail.pop3.user property
propertiesgeneral mail properties in property file format
smtp-hostsets the mail.smtp.host property
smtp-portsets the mail.smtp.port property
smtp-usersets the mail.smtp.user property
store-protocolsets the mail.store.protocol property
transport-protocolsets the mail.transport.protocol property
usersets the mail.user property
<mail> schema
element mail {
  authenticator?
  & debug?
  & from?
  & host?
  & imap-host?
  & imap-port?
  & imap-user?
  & init?
  & jndi-name?
  & name?
  & pop3-host?
  & pop3-port?
  & pop3-user?
  & smtp-host?
  & smtp-port?
  & smtp-user?
  & store-protocol?
  & transport-protocol?
  & user?
}
Example: mail
<web-app xmlns="http://caucho.com/ns/resin">

  <mail jndi-name="java:comp/env/mail">
    <from>noreply@foo.com</from>
    <smtp-host>localhost</smtp-host>
    <smtp-port>25</smtp-port>

    <properties>
      mail.smtp.starttls.enable=true
    </properties>
  </mail>
</web-app>

<max-active-time>

child of database
default 6h

<max-active-time> configures the maximum time a connection can be active before Resin will automatically close it. Normally, the max-active-time should not be configured, since Resin will also automatically close a connection at the end of a request.

Sites should generally leave max-active-time at the default.

<max-close-statements>

child of database
default 256

<max-close-statements> configures how many open statements Resin should save to for the connection close. Since the JDBC Connection.close() call automatically closes any open statements, Resin's database pool needs to keep track of any open statements to close them in case the application has forgotten. The <max-close-statements> is primarily needed for older database drivers implementing the java.sql.Driver interface.

<max-connections>

child of database
default 128

<max-connections> configures the maximum number of open connections allowed for Resin's database pool. Sites can use <max-connections> to throttle the number of database connections for an overloaded server. When max-connections is reached and an application calls getConnection, Resin will wait connection-wait-time or until a connection is freed before allocating a new connection.

<max-create-connections>

child of database
default 5

<max-create-connections> configures the maximum number of simultaneous connection creations. Since connection creation is slow and database access can be spiky, Resin's pool limits the number of new connections to the database at any time. Once a connection has succeeded, a new connection can proceed.

<max-idle-time>

child of database
default 30s

<max-idle-time> configures the maximum time a connection can remain idle before Resin automatically closes it. Since idle databases tie up resources, Resin will slowly close idle connections that are no longer needed.

Higher values of <max-idle-time> will connections to remain in the idle pool for a longer time. Lower values will close idle connections more quickly.

<max-overflow-connections>

child of database
default 0

<max-overflow-connections> extends <connection-max> temporarily in case of overflow. After the <connection-wait-time> expires, Resin can create an overflow connection to handle unforseen load spikes.

<max-pool-time>

child of database
default 24h

<max-pool-time> configures the maximum time the connection can remain open. A connection could theoretically remain open, switching between active and idle, for an indefinite time. The <max-pool-time> allows a site to limit to total time of that connection.

Most sites will leave <max-pool-time> at the default.

<max-uri-length>

child of cluster
default 1024

Sets limit on longest URIs that can be served by Resin.

<max-uri-length> schema
element max-uri-length {
  r_int-Type
}

<memory-free-min>

child of server
default 1m

<memory-free-min> improves server reliability by detecting low-memory situations caused by memory leaks and forcing a clean server restart. Since Resin's watchdog service reliably restarts the server, a website can improve stability by forcing a restart before memory becomes a major problem. The memory-free-min restart will also log a warning, notifying the developers that a potential memory leak needs to be resolved.

When free heap memory gets very low, the garbage collector can run continually trying to free up extra memory. This continual garbage collection can send the CPU time to 100%, cause the site to become completely unresponsive, and yet take a long time before finally failing to an out of memory error (forcing an unclean restart). To avoid this situation, Resin will detect the low-memory condition and gracefully restart the server when free memory becomes too low.

The ultimate solution to any memory leak issues is to get a memory profiler, find the leaking memory and fix it. <memory-free-min> is just a temporary bandage to keep the site running reliably until the memory leak can be found and fixed.

memory-free-min resin.xml
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
      <thread-max>512</thread-max>

      <memory-free-min>1m</memory-free-min>
    </server-default>

    <server id="web-a" address="192.168.0.10"/>
        ...
  </cluster>
</resin>

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

<password>

child of database

<password> configures the database connection password. Sites requiring additional security for their passwords can use the <mypkg:MyDecryptor/> syntax to configure a password decoder.

<ping>

child of cluster

Starts a thread that periodically makes a request to the server, and restarts Resin if it fails. This facility is used to increase server reliability - if there is a problem with the server (perhaps from a deadlock or an exhaustion of resources), the server is restarted.

A failure occurs if a request to the url returns an HTTP status that is not 200.

Since the local process is restarted, it does not make sense to specify a url that does not get serviced by the instance of Resin that has the ping configuration. Most configurations use url's that specify 'localhost' as the host.

This pinging only catches some problems because it's running in the same process as Resin itself. If the entire JDK freezes, this thread will freeze as well. Assuming the JDK doesn't freeze, the PingThread will catch errors like deadlocks.

<ping> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
urlA url to ping.required
sleep-timeTime to wait between pings. The first ping is always 15m after the server starts, this is for subsequent pings.15m
try-countIf a ping fails, number of times to retry before giving up and restartingrequired
freeze-timeoutTime with no response to detect a frozen jvm.15m
retry-timetime between retries1s
socket-timeouttime to wait for server to start responding to the tcp connection before giving up10s
Example: resin.xml - simple usage of server ping
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
    <cluster id="app-tier">
        <ping url="http://localhost/"/>
        ...
    </cluster>
</resin>
Example: resin.xml - configured usage of server ping
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
    ...
    <cluster id="app-tier">
        <ping>
            <url>http://localhost:8080/index.jsp</url>
            <url>http://localhost:8080/webapp/index.jsp</url>
            <url>http://virtualhost/index.jsp</url>
            <url>http://localhost:443/index.jsp</url>

            <sleep-time>5m</sleep-time>
            <try-count>5</try-count>
    
            <!-- a very busy server -->
            <socket-timeout>30s</socket-timeout>
        </ping>
      ...
    </cluster>
</resin>

The class that corresponds to <ping> is PingThread.

Mail notification when ping fails

A refinement of the ping facility sends an email when the server is restarted.

resin.xml - mail notification when ping fails
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">
  ...
  <cluster id="web-tier">
    <ping resin:type="com.caucho.server.admin.PingMailer">
      <url>http://localhost:8080/index.jsp</url>
      <url>http://localhost:8080/webapp/index.jsp</url>

      <mail-to>fred@hogwarts.com</mail-to>
      <mail-from>resin@hogwarts.com</mail-from>
      <mail-subject>Resin ping has failed for server ${'${'}server.name}</mail-subject>
    </ping>
    ...
  </server>
</resin>

The default behaviour for sending mail is to contact a SMTP server at host 127.0.0.1 (the localhost) on port 25. System properties are used to configure a different SMTP server.

resin.xml - smtp server configuration
  <system-property mail.smtp.host="127.0.0.1"/>
  <system-property mail.smtp.port="25"/>

<ping>

child of database
default false

<ping> enables connection validation. When <ping> is enabled, Resin will test the connection with <ping-query> or <ping-table> before returning a connection to the user. If the connection fails the test, Resin will close it and return a new connection.

For efficiency, Resin will only validate the connection if it has been idle for longer than <ping-interval>.

<ping-table>

child of database

<ping-table> configures the database table Resin should use to verify if a connection is still valid when returned from the pool.

<ping-query>

child of database

<ping-query> specifies the query to use for validating if a database connection is still valid when returned from the idle pool.

<ping-interval>

child of database
default 1s

<ping-interval> configures when Resin should validate an idle connection. Connections which have been idle for less than <ping-interval> are assumed to be still valid without validation. Connections idle for longer than <ping-interval> are validated.

Sites can force a validation by setting <ping-interval> to 0.

<port>

child of server
default 6800

The server <port> defines the TCP port for Resin cluster communication and load balancing. Most server instances will use a common port like 6800, while machines with multiple servers may use multiple ports like 6800 and 6801.

multiple servers on a machine
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
    <server id="app-a" address="192.168.1.11" port="6800"/>
    <server id="app-b" address="192.168.1.11" port="6801"/>

    <server id="app-b" address="192.168.2.12" port="6800"/>
    <server id="app-c" address="192.168.2.12" port="6801"/>

    ...
  </cluster>
</resin>

<port-default>

child of server

Defines default port parameters for all <http>, <protocol>, and <cluster-port>.

<prepared-statement-cache-size>

child of database
default 0

<prepared-statement-cache-size> configures how many prepared statements Resin should cache for each connection. Caching prepared statement can improve performance for some database drivers by avoiding repeated parsing of the query SQL.

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

<rewrite-vary-as-private>

Because not all browsers understand the Vary header, Resin can rewrite Vary to a Cache-Control: private. This rewriting will cache the page with the Vary in Resin's proxy cache, and also cache the page in the browser. Any other proxy caches, however, will not be able to cache the page.

The underlying issue is a limitation of browsers such as IE. When IE sees a Vary header it doesn't understand, it marks the page as uncacheable. Since IE only understands "Vary: User-Agent", this would mean IE would refuse to cache gzipped pages or "Vary: Cookie" pages.

With the <rewrite-vary-as-private> tag, IE will cache the page since it's rewritten as "Cache-Control: private" with no Vary at all. Resin will continue to cache the page as normal.

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

<reference>

<reference> configures a JNDI ObjectFactory. Some legacy resources are configured using an ObjectFactory syntax. The <reference> tag provides a compatible way to configure those objects. More modern resources should use <bean> or <component> for IoC configuration.

JNDI ObjectFactories are used to create objects from JNDI references. The <reference> tag configures the ObjectFactory and stores it in JNDI.

<reference> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
jndi-nameJNDI name for the reference. Since Resin 3.0required
factoryClass name of the ObjectFactory. Resin 3.0required
initBean-style initialization for the factorynone
<reference> schema
element reference {
  factory 
  & jndi-name
  & init-param*
}
Example: Hessian client reference
<web-app xmlns="http://caucho.com/ns/resin">

<reference>
  <jndi-name>hessian/hello</jndi-name>
  <factory>com.caucho.hessian.client.HessianProxyFactory</factory>
  <init url="http://localhost:8080/ejb/hello"/>
        type="test.HelloHome"/>
</reference>

</web-app>

<remote-client>

<remote-client> configures a proxy to a web-service. It uses a Java interface and a URI to select the web-service.

The URI is defined as: protocol:url=location, where location is typically a HTTP URL.

  • See Resin remoting for more information, including how to write an adapter for Resin remoting.
<remote-client> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
classClass name of the protocol implementationrequired (or uri)
initIoC initialization for the protocol implementation
name@Named binding for Resin-IoC
jndi-nameJNDI binding name
uriShortcut alias name for the protocol class
remote-client protocols
URIDESCRIPTION
cxf:url=http://foo.com/hello/cxfDefines a cxf service. See http://wiki.caucho.com/CXF for more information.
burlap:url=http://foo.com/hello/burlapDefines a burlap service at http://foo.com/hello/burlap
hessian:url=http://foo.com/hello/hessianDefines a hessian service at http://foo.com/hello/hessian
xfire:url=http://foo.com/hello/cxfDefines a xfire client. See http://wiki.caucho.com/XFire for more information.
remote-client
element remote-client {
  (class|uri)
  & name?
  & jndi-name?
  & interface
}

<resin>

<resin> is the top-level configuration tag for the resin.xml file. The <resin> tag needs to specify the Resin namespace, to allow for validation of the configuration file.

The environment of the top-level <resin> is the global classpath. This environment can be important for <log> configuration for threads which run with using only the global class loader. Because the <resin> environment does not have a dynamic class loader, dynamically loaded classes, like custom jars in resin/lib are not available.

<resin> schema
element resin {
  env resources
  & cluster*
  & cluster-default*
  & environment-system-properties?
  & management?
  & min-free-memory?
  & root-directory?
  & security-manager?
  & security-provider?
  & watchdog-manager?
}
Example: minimal resin.xml
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  <root-directory>/var/resin</root-directory>

  <cluster id="web-tier">
    <server id="">
      <http address="*" port="8080"/>
    </server>

    <resin:import path="app-default.xml"/>

    <host id="">
      <web-app id="" root-directory="/var/resin/htdocs"/>
    </host>
  </cluster>
</resin>

<resin-system-auth-key>

child of resin

<resin-system-auth-key> specifies authorization token for Resin's Security service.

<resin-system-auth-key> schema
element resin-system-auth-key {
  String
}

<resin:AdminAuthenticator>

Authenticator used by Resin for administration purposes such as the /resin-admin application. Also used by the watchdog and clustering code to authenticate servers, so changing principals or passwords in this authenticator requires a shutdown and restart of the watchdog and Resin instances.

Uses the same syntax as XmlAuthenticator.

<resin:AdminAuthenticator> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
userSpecifies a user authentication record. There maybe zero, one or more records.None
password-digest Specifies the digest algorithm and format used to secure the password (see following section in this document for details). md5-base64
pathSpecifies the path to an XML file containing users and passwords.None
logout-on-session-timeoutIf true, the user will be logged out when the session times out.true

<resin:Allow>

child of web-app

The <resin:Allow> tag is used to secure a particular URL pattern. Because it is affirmative, it must always include a nested condition expressing an authorization constraint. All access attempts that do not satisfy the authorization rule are denied access. This tag is the most common type of top level authorization tag.

<resin:Allow> Attributes
ATTRIBUTEDESCRIPTION
url-patternURL pattern describing the resource to be secured.
http-methodHTTP methods that the restriction applies to.
Protecting all pages for logged-in users
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:Allow url-pattern="/*">
    <resin:IfUserInRole role="user"/>
  </resin:Allow>
  ...
</web-app>

<resin:And>

javadoc <resin:And>

Matches if all children match.

Matching both of two query parameters
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp="" target="/match">
    <resin:And>
      <resin:IfQueryParam name="foo" regexp="foo"/>
      <resin:IfQueryParam name="bar" regexp="bar"/>
    </resin:And>
  </resin:Redirect>
  
</web-app>

<resin:BasicLogin>

child of web-app

As the name implies, HTTP basic authentication is the simplest mechanism for gathering login data for web applications. When a web page is secured through HTTP basic authentication, the brower renders a simple dialog box for the user to enter login information. This information is then sent to the server in clear-text using well-defined HTTP headers. This authentication mechanism can be convenient for quick protection of internal pages or administration when writing a form isn't necessary. If you use basic authentication for applications outside the fire-wall, it is highly recommended that you secure the transport layer using SSL. The <resin:BasicLogin> tag is used to configure basic authentication.

WEB-INF/resin-web.xml resin:BasicLogin
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:BasicLogin/>

  <resin:Allow url-pattern="/foo/*">
     <resin:IfUserInRole role="user"/>
  </resin:Allow>

  <resin:XmlAuthenticator>
     ...
  </resin:XmlAuthenticator>
  
</web-app>  

<resin:ByteStreamCache>

Distributed cache of InputStream/OutputStream byte streams across a cluster pod.

<resin:choose>

resin:choose implements an if, elsif, else.

The <resin:choose> schema is context-dependent. A <resin:choose> in a <web-app> will have <web-app> content, while a <resin:choose> in a <host> will have <host> content.

<resin:choose> Attributes
ATTRIBUTEDESCRIPTION
resin:whenA configuration section executed when matching a test condition
resin:otherwiseA fallback section executed when the tests fail
<resin:choose> schema
element resin:choose {
  resin:when*,
  resin:otherwise
}

element resin:when {
  attribute test { string },

  context-dependent content
}

element resin:otherwise {
  context-dependent content
}
Example: resin:choose usage pattern
<resin:choose>
  <resin:when test="${expr1}">
    ...
  </resin:when>

  <resin:when test="${expr2}">
    ...
  </resin:when>

  <resin:otherwise>
    ...
  </resin:otherwise>
<resin:choose>

<resin:ClusterCache>

JCache-style distributed object cache across a cluster pod (java.util.Map).

<resin:ClusterQueue>

Clustered queue.

<resin:ClusterSingleSignon>

Cluster-based single signon.

<resin:DatabaseAuthenticator>

The DatabaseAuthenticator asks a back-end relational database for the password matching a user's name. It uses the DataSource specified by the data-source attribute. data-source refers to an existing configured DataSource.

<resin:DatabaseAuthenticator> Attributes
ATTRIBUTEMEANINGDEFAULT
data-source The pooled JDBC data source. Looks in the application attributes first, then in the global database pools. None
password-query An SQL query to get the user's password given the user name. The default query is shown in the code example below. See below
cookie-auth-queryAn SQL query to authenticate the user by a persistent cookie.None
cookie-auth-updateA SQL update to match a persistent cookie to a user.None
role-query A SQL query to determine the user's role. By default, all users are in role "user", but no others. None
password-digest Specifies the digest algorithm and format used to secure the password (see following section in this document for details). md5-base64
logout-on-session-timeoutIf true, the user will be logged out when the session times out.true
WEB-INF/resin-web.xml for DatabaseAuthenticator
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  <-- Authentication mechanism -->
  <resin:BasicLogin/>

  <-- Role-based authorization -->
  <resin:Allow url-pattern="/foo/*">
     <resin:IfUserInRole role="user"/>
  </resin:Allow>
  
  <-- The authenticator -->
  <resin:DatabaseAuthenticator'>
    <resin:data-source>test</resin:data-source>   
    <resin:password-query>
      SELECT password FROM login WHERE username=?
    </resin:password-query>
    <resin:cookie-auth-query>
      SELECT username FROM LOGIN WHERE cookie=?
    </resin:cookie-auth-query>    
    <resin:cookie-auth-update>
      UPDATE LOGIN SET cookie=? WHERE username=?
    </resin:cookie-auth-update>
    <resin:role-query>
      SELECT role FROM LOGIN WHERE username=?
    </resin:role-query>
  </resin:DatabaseAuthenticator>
</web-app>

<resin:Deny>

javadoc <resin:Deny>

The <resin:Deny> tag is the opposite of the top level <resin:Allow>. It restricts access to a particular URL pattern based on any nested conditions. Access attempts that match the condition are denied access. If no conditions are specified, all access to a URL pattern is restricted.

<resin:Deny> Attributes
ATTRIBUTEDESCRIPTION
url-patternURL pattern describing the resource to be secured.
http-methodHTTP methods that the restriction applies to.
Security-constraint to protect static files
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <!-- protect all .properties files -->
  <resin:Deny url-pattern="*.properties"/>

  <!-- protect the config/ subdirectory -->
  <resin:Deny url-pattern="/config/*"/>
  ...
</web-app>

<resin:DigestLogin>

child of web-app

The HTTP protocol includes a method to indicate to the client that it should digest the password before sending it to the server. This is basically a more secure variant of HTTP basic authentication. The browser submits a digest to Resin instead of submitting a clear-text password. HTTP digest authentication protects the password in transmission.

When using the HTTP digest, Resin will respond to the browser when a secure URL is accessed and ask it to calculate a digest. The steps involved are:

  • Resin provides the client a realm and some other information.
  • The client obtains a user-name and password (usually through a dialog box with a web browser).
  • The client calculates a digest using the user-name, realm, password, and other information supplied by Resin.
  • The client submits the digest to Resin.
  • Resin does the same digest calculation as the client did.
  • Resin compares the submitted digest and the digest it calculated. If they match, the user is authenticated.

The advantage of this method is that the clear-text password is protected in transmission, it cannot be determined from the digest that is submitted by the client to the server. The <resin:DigestLogin> tag is used to configure digest login.

Using HTTP Digest Authentication
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:DigestLogin/>
  ...
</web-app>

<resin:Dispatch>

Normal servlet dispatching with optional target rewriting.

<resin:Dispatch> Attributes
ATTRIBUTEDESCRIPTION
regexpThe regular expression of the URL to match.
targetThe target to which to dispatch the request.
Dispatching static resources directly
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  <resin:Dispatch regexp="\.(jpg|html|txt|gif|png|js|css)$"/>
  <resin:Dispatch regexp="^" target="/controller"/>

</web-app>

<resin:ElasticCloudService>

Enables dynamic servers. When dynamic servers are enable, a new Resin server can join a cluster by contacting the hub triad without needing an explicit server configuration in the resin.properties or resin.xml.

<resin:FastCgiPort>

FastCGI requests, e.g. from nginx.

<resin:FastCgiProxy>

Proxies the request to a backend server using FastCGI as a proxy protocol.

<resin:FastCgiProxy> Attributes
ATTRIBUTEDESCRIPTION
regexpThe regular expression of the URL to match.
addressAn address of a FastCGI server (multiple allowed).
Proxying requests to local FastCGI processes
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

   <resin:FastCgiProxy regexp="\.rb$">
     <address>127.0.0.1:12345</address>
     <address>127.0.0.1:67890</address>
   </resin:FastCgiProxy>

</web-app>

<resin:FileQueue>

Filesystem based queue.

<resin:FileTopic>

Filesystem based topic.

<resin:Forbidden>

Send a HTTP forbidden response.

<resin:Forbidden> Attributes
ATTRIBUTEDESCRIPTION
regexpThe regular expression of the URL to match.
Forbidding access based for unsecured connections
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Forbidden regexp="/foo">
    <resin:Not>
      <resin:IfSecure/>
    </resin:Not>
  </resin:Forbidden>
  
</web-app>

<resin:FormLogin>

Form-based login is the most common way collecting login information. Using this login mechanism, you can plug-in a custom login page with a form storing login information (usually two input text fields for user-name and password). This custom login page can then be used with the Resin security framework. This allows for a much more seamless login mechanism integrated closely with your application, especially in terms of look and feel.

When a URL is secured via form based login, the custom login form page is used to collect authentication information. If authentication succeeds, the user is redirected to the originally requested page. Otherwise, the user is forwarded to an error page (that can also be configured).

A login page can be anything that renders a valid login form such as HTML, Servlet, JSP or JSF. A valid login form must have the action j_security_check. It must also have the parameters j_username and j_password holding the username and password. Optionally, it can also have j_uri and j_use_cookie_auth. j_uri gives the next page to display when login succeeds. If the form-uri-priority is set to true, the user will be forwarded to the j_uri page regardless of what the originally requested page was. If the attribute is set to false (the default), the j_uri page is only used when the originally requested page was the login page itself. j_use_cookie_auth allows Resin to send a persistent cookie to the client to make subsequent logins automatic. When j_use_cookie_auth is set, Resin will store a persistent cookie on the client's machine after authentication succeeds. On all subsequent access, Resin detects the persistent cookie and automatically logs the user in instead of prompting for authentication. This essentially lets you implement "remember me" functionality common in many web-sites. By default, the authentication only lasts for a single session and no persistent login cookie is sent to the client.

The following table outlines all the login parameters recognized by Resin:

j_security_check Parameters
PARAMETERMEANING
j_usernameThe user name.
j_passwordThe password.
j_uriResin extension for the successful display page (optional).
j_use_cookie_authResin extension to allow cookie login (optional).
<resin:FormLogin> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
form-login-pageThe page to be used to prompt the user login.none
form-error-pageThe error page for unsuccessful login.none
internal-forwardUse an internal redirect on success or a sendRedirect.false
form-uri-priorityIf true, the login form's j_uri will override the originally requested URI.false
WEB-INF/resin-web.xml resin:FormLogin
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:FormLogin form-login-page="/login.html"
                      form-error-page="/login_failure.html"/>
  ...
</web-app>
j_security_check form
<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>

<resin:Forward>

Forwards to the new URL using RequestDispatcher.forward with the target URL.

<resin:Forward> Attributes
ATTRIBUTEDESCRIPTION
regexpThe regular expression of the URL to match.
targetThe target URL to which to forward the request.
absolute‑targetThe absolute target URL to which to forward the request. The absolute target is based on the host root, not relative to the webapp.
Forwarding requests across web-apps
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  <resin:Forward regexp='^/foo' target='/bar/'/>

</web-app>

<resin:GlobalCache>

JCache-style distributed object cache across the entire Resin system.

<resin:HttpProxy>

Proxies the request to a backend server using HTTP as a proxy protocol.

<resin:HttpProxy> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT VALUE
regexpThe regular expression of the URL to match.none
addressaddress:port of an HTTP servernone
addressesaddress:port of HTTP servers (space separated)none
backenda <backend> with address and optional timeouts (see below)none
strategyround-robin or adaptiveadaptive
connect-timeoutthe maximum time a proxy connection to a backend should take5s
socket-timeoutthe maximum time a the proxy will wait for a read or write to a backend30s
idle-timethe maximum time the proxy will leave an idle socket before closing it (must be less than the keepalive value of the target backend)10s
warmup-timetime the proxy uses to throttle connections to a backend server that's just starting up60s
recover-timethe maximum time the proxy will consider the backend dead after a failure before retrying15s
<backend> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT VALUE
addressaddress:port of an HTTP servernone
connect-timeoutthe maximum time a proxy connection to the backend should take5s
socket-timeoutthe maximum time a the proxy will wait for a read or write to the backend30s
idle-timethe maximum time the proxy will leave an idle socket before closing it (must be less than the keepalive value of the target backend)10s
warmup-timetime the proxy uses to throttle connections to the backend server that's just starting up60s
recover-timethe maximum time the proxy will consider the backend dead after a failure before retrying15s
weightassigns a load-balance weight to a backend server. Servers with higher values get more requests. Servers with lower values get fewer requests100
Proxying requests to local HTTP servers
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

   <resin:HttpProxy regexp="\.cgi$">
     <strategy>adaptive</strategy>
     <backend address="127.0.0.1:12345" weight="100">
     <backend address="127.0.0.1:65432" weight="200">
   </resin:HttpProxy>

</web-app>

<resin:if>

resin:if executes part of the configuration file conditionally. resin:if can be particularly useful in combination with Java command-line properties like -Dfoo=bar to enable development mode or testing configuration.

The resin:if schema is context-dependent. For example, resin:if in a <web-app> will have web-app content while resin:if in a <host> will have host content.

<resin:if> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
testthe test to performrequired
<resin:if> schema
element resin:if {
  attribute test { string }

  context-dependent content
}
Example: enable debugging for -Ddevelopment
<resin xmlns="http://caucho.com/ns/resin"
        xmlns:core="http://caucho.com/ns/resin/core">

  <resin:if test="${system['development']}">
    <logger name="com.foo" level="finer"/>
  </resin:if>

  ...
</resin>

<resin:IfAuthType>

Checks for the authentication type, request.getAuthType().

<resin:IfAuthType> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
valuenone, basic, client_cert, digest, or formnone
Redirecting based on authentication type
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp='^/user-area' target='/secret'>
    <resin:IfAuthType value="BASIC"/>
  </resin:Redirect>

  <resin:Redirect regexp='^/user-area' target='/login'/>

  <resin:XmlAuthenticator password-digest='none'>
    <user name="Aladdin" password="open sesame" group="user"/>
  </resin:XmlAuthenticator>

  <resin:BasicLogin realm-name="foobar"/>

</web-app>

<resin:IfCookie>

Checks for the presence of a named HTTP cookie from request.getCookies().

<resin:IfCookie> Attributes
ATTRIBUTEDESCRIPTION
nameThe name of the cookie to match.
regexpA regular expression to match the value of the cookie.
valueA regular expression to match the value of the cookie. (synonym for regexp)
Redirecting if a cookie is set
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp='^/welcome' target='/user-area'>
    <resin:IfCookie name="session"/>
  </resin:Redirect>

</web-app>

<resin:IfCron>

Matches if the current time is in an active range configured by cron-style times.

<resin:IfCron> Attributes
ATTRIBUTEDESCRIPTION
enable-atA cron expression representing the start time(s) at which the predicate matches.
disable-atA cron expression representing the end time(s) after which the predicate does not match.
Redirecting based on time
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp='^/live-support' target='/hours'>
    <resin:IfCron>
      <resin:enable-at>0 17 * * *</resin:enable-at>
      <resin:disable-at>0 8 * * *</resin:disable-at>
    </resin:IfCron>
  </resin:Redirect>

</web-app>

<resin:IfFileExists>

Matches if the URL corresponds to an actual file. Has no attributes.

Dispatch only if the URL represents an existant file
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  <resin:Dispatch>
    <resin:IfFileExists/>
  </resin:Dispatch>

  <resin:Redirect regexp="^" target='/does-not-exist'/>
</web-app>

<resin:IfHeader>

Tests for a HTTP header and value match.

<resin:IfHeader> Attributes
ATTRIBUTEDESCRIPTION
nameThe name of the header to match.
regexpA regular expression to match the value of the header.
valueA regular expression to match the value of the header. (synonym for regexp)
Redirect based on referrer
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp='^/foo' target='/foo-for-example-customers'>
    <resin:IfHeader name="Referer" value="example.com"/>
  </resin:Redirect>

  <resin:Redirect regexp='^/foo' target='/everyone-else'/>
</web-app>

<resin:IfLocale>

Tests for a Locale match from the HTTP request (Accept-Language header).

<resin:IfLocale> Attributes
ATTRIBUTEDESCRIPTION
valueA regular expression to match locale.
Redirecting based on locale
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp='^/your-lang' target='/francais'>
    <resin:IfLocale value="fr"/>
  </resin:Redirect>

  <resin:Redirect regexp='^/your-lang' target='/default'/>
</web-app>

<resin:IfLocalPort>

Compares the local port of the request, request.getLocalPort().

<resin:IfLocalPort> Attributes
ATTRIBUTEDESCRIPTION
valueThe port to match.
Redirecting based on local port
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

    <resin:Redirect regexp='^/foo' target='/match-5555'>
      <resin:IfLocalPort value="5555"/>
    </resin:Redirect>

    <resin:Redirect regexp='^/foo' target='/match-6666'>
      <resin:IfLocalPort value="6666"/>
    </resin:Redirect>

    <resin:Redirect regexp='^/foo' target='/no-match'/>

</web-app>

<resin:IfMBeanEnabled>

Matches if a MBean is enabled().

<resin:IfMBeanEnabled> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
nameThe MBean name.required
enabledSets the default enable/disable value.true

The mbean name will be something like:

MBean name for maintenance
  resin:type=IfMBeanEnabled,name=my-name,Host=www.example.com,WebApp=/

The following example redirects URLs to a maintenance page if an mbean is enabled.

Redirecting based on an MBean
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

    <resin:Redirect regexp='^/foo' target='/scheduled-maintenance.jsp'>
      <resin:IfMBeanEnabled name="maintenance" enabled="false"/>
    </resin:Redirect>

</web-app>

<resin:IfMethod>

Compares the HTTP method, request.getMethod().

<resin:IfMethod> Attributes
ATTRIBUTEDESCRIPTION
valueThe HTTP method to match.
methodThe HTTP method to match (synonym of value).
Redirecting based on HTTP method
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

    <resin:Redirect regexp='^/foo' target='/foo/post'>
      <resin:IfMethod value="POST"/>
    </resin:Redirect>

</web-app>

<resin:IfNetwork>

The <resin:IfNetwork> tag allows or denies requests based on the IP address of the client. IP-constraint is very useful for protecting administration resources to an internal network. It can also be useful for denying service to known problem IPs.

<resin:IfNetwork> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
valueAn IP address to match (multiple allowed).N/A
cache-sizeThe size of the IP address LRU cache used for performance.256

The /24 in the IP 192.168.17.0/24 means that the first 24 bits of the IP are matched - any IP address that begins with 192.168.17. will match. The usage of /bits is optional.

Admin Pages Allowed Only from 192.168.17.0/24
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:Allow url-pattern="/admin/*">
    <resin:IfNetwork value="192.168.17.0/24"/>
  </resin:Allow>
  ...
</web-app>

The following example shows how the tag can be used to construct an IP block list:

Block-out Known Trouble-Makers
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:Deny>
    <resin:IfNetwork>
       <resin:value>205.11.12.3</resin:value>
       <resin:value>213.43.62.45</resin:value>
       <resin:value>123.4.45.6</resin:value>
       <resin:value>233.15.25.35</resin:value>
       <resin:value>233.14.87.12</resin:value>
    </resin:IfNetwork>
  </resin:Deny>
  ...
</web-app>

Be careful with deny - some ISP's (like AOL) use proxies and the IP of many different users may appear to be the same IP to your server.

If only deny is used, then all IPs are allowed if they do not match a deny. If only allow is used, then an IP is denied unless it matches an allow. If both are used, then the IP must match both an allow and a deny

<resin:IfQueryParam>

Tests for a HTTP query parameger, request.getParameter().

<resin:IfQueryParam> Attributes
ATTRIBUTEDESCRIPTION
nameThe name of the query parameter to match.
regexpA regular expression to match the value of the query parameter.
valueA regular expression to match the value of the query parameter. (synonym for regexp)
Redirecting based on query parameter
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
    <resin:Redirect regexp='^/foo' target='/login'>
      <resin:IfQueryParam name="area" value="login"/>
    </resin:Redirect>

</web-app>

<resin:IfRemoteUser>

Tests against the remote user, request.getRemoteUser().

<resin:IfRemoteUser> Attributes
ATTRIBUTEDESCRIPTION
valueThe user to match.
Forbidding a path based on remote user
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Forbidden regexp="/harry">
    <resin:Not>
      <resin:IfRemoteUser value="harry"/>
    </resin:Not>
  </resin:Forbidden>

  <resin:XmlAuthenticator>
    <user>harry:H83FykjQaBwvqjGRyIRUHQ==:user</user>
  </resin:XmlAuthenticator>

  <resin:BasicLogin realm-name='global'/>

</web-app>

<resin:IfSecure>

The <resin:IfSecure> tag restricts access to secure transports, usually SSL.

<resin:IfSecure> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
valueA boolean value against which HttpServletRequest.isSecure is matched.true

In the following example, all pages in the web application are enforced to be accessible via SSL only.

WEB-INF/resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"
  ...	 
  <resin:Allow>
    <resin:IfSecure/>
  </resin:Allow>
  ...  
</web-app>

The default behaviour is for Resin to rewrite any URL that starts with "http:" by replacing the "http:" part with "https:", and then send a redirect to the browser because this configuration.

If the default rewriting of the host is not appropriate, you can set the secure-host-name for the host:

WEB-INF/resin-web.xml
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">
  ...  
  <host id="...">
    <secure-host-name>https://hogwarts.com</secure-host-name>
    ...
</resin> 

<resin:IfUserInRole>

The resin:IfUserInRole condition enforces role-based security. It requires that authenticated users have a specified role.

<resin:IfUserInRole> Attributes
ATTRIBUTEDESCRIPTION
roleRoles which are allowed to access the resource.

The following is an example of how <resin:IfUserInRole> might be used:

WEB-INF/resin-web.xml Protecting WebDav for WebDav Users
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:Allow url-pattern="/webdav/*">
    <resin:IfUserInRole role='webdav'/>
  </resin:Allow>
  ...  
</web-app>

<resin:import>

<resin:import> reads configuration from another file or set of files. For example, the WEB-INF/web.xml and WEB-INF/resin-web.xml files are implemented as <resin:import> in the app-default.xml.

The target file is validated by the schema of the including context. So a resin:import in <web-app-default> will have a target with a top-level of <web-app>, and a resin:import in <cluster> will have a top-level tag of <cluster>.

<resin:import> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
patha path to a fileeither path or fileset is required
fileseta fileset describing all the files to import.either path or fileset is required
optionalif true, no error when file does not existfalse
<resin:import> schema
element import {
  (path | fileset)
  & optional?
}

element fileset {
  dir
  & exclude*
  & include*
}

The following example shows how Resin implements the WEB-INF/web.xml and WEB-INF/resin-web.xml files. Both are simply resin:import in a web-app-default. When Resin configures the web-app, it will process the web-app-default program, and call resin:import for the web.xml file.

Example: import implementation of WEB-INF/web.xml
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  <cluster id="app-tier">

    <web-app-default>
      <resin:import path="WEB-INF/web.xml" optional="true"/>
      <resin:import path="WEB-INF/resin-web.xml" optional="true"/>
    </web-app-default>

  </cluster>
</resin>

Virtual hosts can use resin:import to add a custom host.xml file. The host.xml can use any <host> attribute, including <host-name> and <host-alias> to customize the virtual host configuration.

Example: adding host.xml in host-deploy
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">
  <cluster id="app-tier">

    <host-deploy path="/var/resin/hosts">
      <host-default>
        <resin:import path="host.xml" optional="true"/>

        <web-app-deploy path="webapps"/>
      </host-default>
    </web-app-default>

  </cluster>
</resin>

Some applications may want to split their configuration into multiple files using the fileset. For example, a Resin-IoC application might want to define beans in WEB-INF/beans/*.xml and give the web-app flexibility in which bean files to create.

Example: Bean IoC fileset in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:core="http://caucho.com/ns/resin/core">

  <resin:import>
    <fileset dir="WEB-INF/beans">
      <include>*.xml</include>
    </fileset>
  </resin:import>

</web-app>

<resin:JaasAuthenticator>

The JaasAuthenticator uses a JAAS LoginModule for authentication. A common use of the JaasAuthenticator is to serve as an adapter for the large number of JAAS LoginModule's included in the Sun JDK for authentication purposes. However, the JAAS authenticator can be used with any valid JAAS login module.

<resin:JaasAuthenticator> Attributes
ATTRIBUTEMEANINGDEFAULT
init-paramAdds a property to the LoginModule.None
login-moduleThe fully qualified class name of the LoginModule implementation.Required
logout-on-session-timeoutIf true, the user will be logged out when the session times out.true
password-digest Specifies the digest algorithm and format used to secure the password (see following section in this document for details). md5-base64
WEB-INF/resin-web.xml for JaasAuthenticator
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:JaasAuthenticator>
    <resin:login-module>com.sun.security.auth.module.Krb5LoginModule</resin:login-module>
    <resin:init-param>
      <debug>true</debug>
    </resin:init-param>
  </resin:JaasAuthenticator>
  ...
</web-app>

<resin:JmsConnectionFactory>

Combined Queue and Topic ConnectionFactory.

<resin:JmxService>

Enables cluster-wide JMX administration.

<resin:LdapAuthenticator>

The LdapAuthenticator uses JNDI to connect to an LDAP (or Active Directory) server for authentication.

<resin:LdapAuthenticator> Attributes
ATTRIBUTEMEANINGDEFAULT
dn-prefixString to prepend to query before portion selecting user by name.None
dn-suffixString to append to query after portion selecting user by name.None
jndi-envAdd a property to the JNDI provider used for connecting to the LDAP server.See below
logout-on-session-timeoutIf true, the user will be logged out when the session times out.true
security-authenticationSets the Context.SECURITY_AUTHENTICATION for the LDAP environment.
security-principalSets the Context.SECURITY_PRINCIPAL for the LDAP environment.
security-credentialsSets the Context.SECURITY_CREDENTIALS for the LDAP environment.
password-digest Specifies the digest algorithm and format used to secure the password (see following section in this document for details). md5-base64
user-attributeThe attribute name to use in the query for matching the user.uid
password-attributeThe attribute name to use for obtaining the password.userPassword
urlThe URL for the server.ldap://localhost:389
WEB-INF/resin-web.xml for LdapAuthenticator
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:LdapAuthenticator password-digest="none">
    <resin:url>ldap://localhost:389</resin:url>
    <resin:dn-suffix>dc=hogwarts,dc=com</resin:dn-suffix>
  </resin:LdapAuthenticator>
  ...
</web-app>

jndi-env

jndi-env configures properties of the LDAP provider implementation. Prior to 3.1.1, the URL of the server is specified with jndi-env and the java.naming.provider.url property.

The following example shows the usage of the jndi-env configuration property:

WEB-INF/resin-web.xml LdapAuthenticator jndi-env
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:LdapAuthenticator password-digest="none">
    <resin:jndi-env java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"/>
    <resin:jndi-env java.naming.provider.url="ldap://localhost:389"/>
    <resin:dn-suffix>dc=hogwarts,dc=com</dn-suffix>
  </resin:LdapAuthenticator>
  ...
<web-app>

<resin:LoadBalance>

<resin:LoadBalance> requires Resin Professional

Load balance to a cluster of backend Resin servers.

<resin:LoadBalance> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
regexpThe regular expression of the URL to match.None (match all)
clusterThe id of the cluster to which to load balance.required
session-cookiechange the session cookie to examine for sticky sessionsJSESSIONID
sticky-sessionssessions are sticky to the original backend app servertrue
strategyround-robin or adaptiveadaptive
Load Balancing to a backend cluster
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">
   
  <cluster id='app-tier'>
    <server id='a' port='6810'/>
    <server id='b' port='6820'/>

    ...
  </cluster>

  <cluster id='web-tier'>
    <server id='http' port='80'/>

    <host id=''>
    
      <resin:LoadBalance cluster="app-tier"/>
      
    </host>
  </cluster>
</resin>

<resin:LogService>

Stores high-priority log messages in a database.

<resin:MemoryQueue>

Memory based queue.

<resin:MemorySingleSignon>

Memory-based single signon.

<resin:MemoryTopic>

Memory based topic.

<resin:message>

Logs a message to the given log file. The content of the element is the message.

<resin:message> schema
element resin:message {
  string
}
logging in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">

  <resin:message>Starting server ${server.name}</resin:message>

</web-app>

<resin:MovedPermanently>

Send an HTTP redirect to a new URL specified by target.

<resin:MovedPermanently> Attributes
ATTRIBUTEDESCRIPTION
regexpThe regular expression of the URL to match.
targetThe target to which to redirect the request.
Flipping elements of a path with a MovedPermanently
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  <resin:MovedPermanently regexp='^/([^/]+)/([^/]+)' target='/$2/$1'/>
  
</web-app>

<resin:Not>

javadoc <resin:Not>

Matches if the child does not match.

Negative matching of a query parameter
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp="" target="/match">
    <resin:Not>
      <resin:IfQueryParam name="foo" regexp="bar"/>
    </resin:Not>
  </resin:Redirect>
  
</web-app>

<resin:NotAnd>

Matches if any child does not match.

Negative matching of at least one of two query parameters
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp="" target="/match">
    <resin:NotAnd>
      <resin:IfQueryParam name="foo" regexp="foo"/>
      <resin:IfQueryParam name="bar" regexp="bar"/>
    </resin:NotAnd>
  </resin:Redirect>
  
</web-app>

<resin:NotOr>

Matches if all the children do not match.

Negative matching of two query parameters
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp="" target="/match">
    <resin:NotOr>
      <resin:IfQueryParam name="foo" regexp="foo"/>
      <resin:IfQueryParam name="bar" regexp="bar"/>
    </resin:NotOr>
  </resin:Redirect>
  
</web-app>

<resin:Or>

javadoc <resin:Or>

Matches if any children match.

Matching at least one of two query parameters
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:Redirect regexp="" target="/match">
    <resin:Or>
      <resin:IfQueryParam name="foo" regexp="foo"/>
      <resin:IfQueryParam name="foo" regexp="bar"/>
    </resin:Or>
  </resin:Redirect>
  
</web-app>

<resin:otherwise>

child of resin:choose

<resin:otherwise> is the catch-all configuration for a <resin:choose> block when none of the <resin:when> items match.

<resin:otherwise> schema
element resin:otherwise {
  context-dependent content
}

<resin:PingMailer>

Mails a notification when a ping check fails.

<resin:PingThread>

Checks status of Resin sutomatically.

<resin:ProjectJarRepository>

Maven-style library jar management for webapps.

<resin:PropertiesAuthenticator>

The PropertiesAuthenticator allows you to use Java properties to store authentication information. This is very useful for a variety of applications such as very small sites, developement, unit testing or integration testing. You can either specify properties in-line in XML or via an external properties file.

<resin:PropertiesAuthenticator> Attributes
ATTRIBUTEMEANINGDEFAULT
pathPath to the properties file.None
password-digest Specifies the digest algorithm and format used to secure the password (see following section in this document for details). md5-base64

The following is an example of in-lining properties with the authenticator. This is useful for extremely simple web-sites maintained by developers as well as testing.

WEB-INF/resin-web.xml - in-line Properties
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:PropertiesAuthenticator password-digest="none">
     harry=quidditch,user,admin
     draco=mudblood,disabled,user
  </resin:PropertiesAuthenticator>
  ...
</web-app>

Alternatively, external properties files can be used as in the example below. This is useful for a simple site where authentication may be managed by administrators or non-technical users.

WEB-INF/resin-web.xml - File Property
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"
  ...
  <resin:PropertiesAuthenticator path="WEB-INF/users.properties"/>
  ...
</web-app>
WEB-INF/users.properties
harry=/Tj/54ylCloUeMi2YQIVCQ===,user,admin

As the example indicates, the properties file includes the user as property name while the value is the password (that may be hashed as in the example or may be in plain-text) and any roles that are assigned to the user separated by commas. The password and role values are also separated by a comma.

<resin:Redirect>

Send an HTTP redirect to a new URL specified by target.

<resin:Redirect> Attributes
ATTRIBUTEDESCRIPTION
regexpThe regular expression of the URL to match.
targetThe target to which to redirect the request.
Flipping elements of a path with a Redirect
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  <resin:Redirect regexp='^/([^/]+)/([^/]+)' target='/$2/$1'/>
  
</web-app>

<resin:RemoteAdminService>

Enables administration by remote agents, like an eclipse console.

<resin:ScheduledTask>

<resin:ScheduledTask> schedules a job to be executed at specific times or after specific delays. The times can be specified by a cron syntax or by a simple delay parameter. The job can be either a Runnable bean, a method specified by an EL expression, or a URL.

When specified as an Java Injection bean, the bean task has full IoC capabilities, including injection, @TransactionAttribute aspects, interception and @Observes.

<resin:ScheduledTask> Attributes
ATTRIBUTEDESCRIPTION
crona cron-style scheduling description
delaya simple delay-based execution
initIoC initialization for the bean
mbean-nameoptional MBean name for JMX registration
methodEL expression for a method to be invoked as the task
nameoptional IoC name for registering the task
periodhow often the task should be invoked in simple mode
taskalternate task assignment for predefined beans
A runnable task
<resin:ScheduledTask>
  <cron>* * * * *</cron>
  <task>
    <example:MyClass xmlns:qa="urn:java:com.example"/>
  </task>
</resin:ScheduledTask>
Weekly maintenance script
<resin:ScheduledTask url="/saturday-maintenance.jsp">
  <cron>* * * * 6</cron>
</resin:ScheduledTask>

<resin:SendError>

Send a HTTP error response.

<resin:SendError> Attributes
ATTRIBUTEDESCRIPTION
regexpThe regular expression of the URL to match.
codeThe HTTP status to send.
messageA descriptive message to send to the client.
Sending an error code based on request path
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

	<resin:SendError regexp="/upcoming" code="501" message="Not Implemented"/>

</web-app>

<resin:set>

resin:set adds an EL variable to the current context.

<resin:set> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
varname of the variable to setrequired
valuevaluerequired
<resin:set> schema
element set {
  var
  & value
  & default
  & attribute * { string }
}
Example: resin:set in resin.xml
<resin xmlns="http://caucho.com/ns/resin"
          xmlns:resin="http://caucho.com/ns/resin/core">
  <resin:set var="root" value="/var/resin"/>

  <cluster id="app-tier">
    <root-directory>${root}</root-directory>

    ...
  </cluster>
</resin>

<resin:SetHeader>

Sets a response header.

<resin:SetHeader> Attributes
ATTRIBUTEDESCRIPTION
nameThe name of header to set.
valueThe value to which the header will be set.
regexpregular expression matching URLs.
Example: Setting a custom header based on network
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:SetHeader regexp="\.jsp$" name="X-External" value="true">
    <resin:Not>
      <resin:IfNetwork>
        <resin:value>192.168.1.0/24</resin:value>
      </resin:IfNetwork>
    </resin:Not>
  </resin:SetHeader>

</web-app>

<resin:SetRequestSecure>

Marks the request as secure.

Setting a request as secure based on network
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:SetRequestSecure>
    <resin:IfNetwork>
      <resin:value>192.168.1.0/24</resin:value>
    </resin:IfNetwork>
  </resin:SetRequestSecure>

</web-app>

<resin:SetVary>

Sets the Vary header.

<resin:SetVary> Attributes
ATTRIBUTEDESCRIPTION
valueThe value to which the Vary header will be set.
regexpregular expression matching URLs.
Example: Setting the Vary header for JSPs
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:SetVary regexp="\.jsp" value="Accept"/>

</web-app>

<resin:StatService>

<resin:StatService> requires Resin Professional

Gathers timed runtime status of Resin for graphing.

<resin:StatService> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
unix-load-avg-exit-thresholdCPU load triggering a Resin exit (and restart)100.0
cpu-load-log-info-thresholdCPU load triggering a log message at the info level1.0
cpu-load-log-warning-thresholdCPU load triggering a log message at the warning level5.0
cpu-load-log-thread-dump-thresholdCPU load triggering thread dump to the log5.0
sample-periodhow often to sample the statistics60s
thread-dump-intervalminimum time between thread dumps15m
unix-load-avg-exit-thresholdUnix CPU load triggering a Resin exit (and restart)5.0

<resin:when>

child of resin:choose

<resin:when> conditionally configures a block within a <resin:choose> block. If the test matches, Resin will use the enclosed configuration.

<resin:when> Attributes
ATTRIBUTEDESCRIPTION
testthe test to perform
<resin:when> schema
element resin:when {
  attribute test { string },

  context-dependent content
}

<resin:XaLogService>

<resin:XaLogService> requires Resin Professional

Transaction log service.

<resin:XmlAuthenticator>

In a similar vein to the properties authenticator, the XML authenticator allows you to store authentication information in XML - either in-line or in an external file. This authenticator has some of the same use-cases as the properties file authenticator, in a slight more human readable form, especially for a non-technical user.

ATTRIBUTEMEANINGDEFAULT
userSpecifies a user authentication record. There maybe zero, one or more records.None
password-digest Specifies the digest algorithm and format used to secure the password (see following section in this document for details). md5-base64
pathSpecifies the path to an XML file containing users and passwords.None
logout-on-session-timeoutIf true, the user will be logged out when the session times out.true

The following example uses in-line XML for authentication. When configuring the XmlAuthenticator in resin.xml (or resin-web.xml), each user adds a new configured user. The user value contains the username, password, and the roles for the user.

XmlAuthenticator in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:XmlAuthenticator password-digest="none">
    <resin:user name="Harry Potter" password="quidditch" group="user,gryffindor"/>
    <resin:user name="Draco Malfoy" password="pureblood" group="user,slytherin"/>
  </resin:XmlAuthenticator>
  ...
</web-app>  

This example shows how to use an external XML file for authentication:

WEB-INF/resin-web.xml - File XML
<web-app xmlns="http://caucho.com/ns/resin">
  ...
  <resin:XmlAuthenticator path="WEB-INF/users.xml"/>
  ...
</web-app>
WEB-INF/users.xml
<users>
  <user name="harry password="/Tj/54ylCloUeMi2YQIVCQ===" roles="user,admin"/>
<users>

<resin:XmlRoleMap>

Role to group permission mapping.

RequestPredicate

Interface for custom request predicates.

<resource>

<resource> is an obsolete synonym for <bean> to define custom singletons. Applications should use the <bean> syntax instead.

<resource-ref>

<resource-ref> declares that the application needs a resouce configuration.

resource-ref is not directly used by Resin. It's a servlet configuration item intended to tell GUI tools which resources need configuration. Resource configuration in Resin uses the resource, reference, database, and ejb-server tags.

For backwards compatibility, Resin 2.1-style configuration files may still use resource-ref to configure resources, but it's recommended to convert the configuration.

<resource-ref> schema
element resource-ref {
  attribute id?,
  description*,
  res-ref-name,
  ref-type,
  res-auth,
  res-sharing-scope?
}

<save-mode>

<save-mode> configures when Resin should save a persistence session during a request. The values are:

<save-mode> Attributes
ATTRIBUTEDESCRIPTION
after-requestSave the session after the request has been served and completed
before-headersSave the session before sending headers to the browser
on-shutdownOnly save the session when Resin is shutting down

In some situations, like redirects, a fast browser can send a request back to Resin before the session is persisted with the after-request save-mode. If the server is configured without sticky sessions, the load balancer might send the request to a different server, which may not get the updated session. In the situation, either the save-mode should be changed to before-headers or sticky sessions should be enabled.

If the save-mode is before-headers, the application should take care to make any session changes before sending data to the browser.

default after-request

<save-allocation-stack-trace>

child of database

<save-allocation-stack-trace> helps debugging application with a missing Connection.close() by saving the stack trace where the Connection.getConnection() was called. When Resin detects that the connection has failed to close, it can then print the allocation stack trace, which is more informative for tracking down errors.

<scheduled-task>

child of web-app

The <scheduled-task> is replaced by bean-style resin:ScheduleTask.

ScheduledTask in resin-web.xml
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:ee="urn:java:ee"
         xmlns:mypkg="urn:java:com.mycom.mypkg">

  <resin:ScheduleTask>
    <cron>* * 23 * *</cron>
    
    <task>
      <mypkg:MyBean/>
    </task>
  </resin:ScheduleTask>
  
</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
}

<secure-host-name>

<secure-host-name> sets a host-name or URL to be used for secure redirection. For some security configurations, Resin needs to redirect from an insecure site to a secure one. The <secure-host-name> configures the host to redirect to.

See Resin security.

<secure-host-name> schema
element secure-host-name {
  string
}

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

<security-manager>

<security-manager> enables the use of the security manager for the JVM. Because the JVM security manager is very slow, we generally do not recommend enabling it for server applications. Instead, see the watchdog configuration for alternative methods for securiting the JVM in ISP configurations.

<security-manager> schema
element security-manager {
  r_boolean-Type
}
Example: enabling security-manager
<resin xmlns="http://caucho.com/ns/resin">

  ...
  <security-manager/>
  ...

<security-provider>

<security-provider> adds one or more security providers. Each entry specifies the name of a security provider class. The name is used to instantiate an instance of the object, which is then passed to Security.addProvider.

<security-provider> schema
element security-provider {
  string
}
Example: adding custom security providers
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">

  ...

  <security-provider>
    com.sun.net.ssl.internal.ssl.Provider
  </security-provider>
  <security-provider>
    example.MyProvider
  </security-provider>

  ...

<server>

child of cluster

<server> configures a JVM instance in the cluster. Each <server> is uniquely identified by its id attribute. The id will match the -server command line argument.

The server listens to an internal network address, e.g. 192.168.0.10:6800 for clustering, load balancing, and administration.

The current server is managed with a ServerMXBean. The ObjectName is resin:type=Server.

Peer servers are managed with ServerConnectorMXBean. The ObjectName is resin:type=ServerConnector,name=server-id.

<server> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
idunique server identifierrequired
addressIP address of the cluster port127.0.0.1
portThe cluster port6800
server
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <server id="a" address="192.168.0.10" port="6800">
          <http port="8080"/>
        </server>

        <server id="b" address="192.168.0.11" server-port="6800">
          <http port="8080"/>
        </server>

        <server id="c" address="192.168.0.12" server-port="6800">
          <http port="8080"/>
        </server>

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

Main configuration for the server, configuring ports, threads and virtual hosts.

  • Common resources for all virtual hosts and web-apps.
  • Thread pooling
  • HTTP and Server/Cluster ports
  • Caching
  • virtual host configuration and common web-app-default

The <server> will generally contain a <class-loader> configuration which loads the resin/lib jars dynamically, allowing for system-wide jars to be dropped into resin/lib. <server> configures the main dynamic environment. Database pools common to all virtual hosts, for example, should be configured in the <server> block.

The <server> configures the <thread-pool> and a set of <http> and <server> ports which share the thread pool. Requests received on those ports will use worker threads from the thread pool.

<server> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
alternate-session-url-prefixa prefix to add the session to the beginning of the URL as a path prefix instead of the standard ;jsessionid= suffix. For clients like mobile devices with limited memory, this will allow careful web designers to minimize the page size.null
keepalive-maxthe maximum number of keepalive connections512
keepalive-timeoutthe maximum time a connection is maintained in the keepalive state15s
alternate-session-url-prefix
<server>
  ...
  <alternate-session-url-prefix>/~J=</alternate-session-url-prefix>
  ...

EL variables and functions

EL variables defined by <server>
VARIABLECORRESPONDING API
serverIdserver.getServerId()
root-dirserver.getRootDirectory()
server-rootserver.getRootDirectory()
EL functions defined by <server>
FUNCTIONCORRESPONDING API
jndiJndi.lookup(String)

<server-default>

child of cluster

<server-default> defines default values for all <server> instances. Since most <server> configuration is identical for all server instances, the shared configuration belongs in a <server-default>. For example, <http> ports, timeouts, JVM arguments, and keepalives are typically identical for all server instances and therefore belong in a server-default.

server
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <server-default>
           <thread-max>512</thread-max>

           <jvm-arg>-Xmx512m -Xss1m</jvm-arg>

           <http port="8080"/>
        </server-default>

        <server id="a" address="192.168.0.10" port="6800"/>
        <server id="b" address="192.168.0.11" port="6800"/>
        <server id="c" address="192.168.0.12" port="6800"/>

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

<server-header>

child of cluster
default Resin/4.0.x

Configures the HTTP Server: header which Resin sends back to any HTTP client.

<server-header> schema
element server-header {
  string
}
server-header
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <server-header>MyServer/1.0</server-header>
    </cluster>
</resin>

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

child of class-loader

Use of servlet-hack is discouraged. Using servlet-hack violates the JDK's classloader delegation model and can produce surprising ClassCastExceptions.

servlet-hack reverses the normal class loader order. Instead of parent classloaders having priority, child classloaders have priority.

<servlet-hack> schema
element servlet-hack {
  boolean
}

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

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>

ServletRequestPredicate

Although extremely rare, it is sometimes useful to create a custom predicate (for example for encapsulating complex custom authorization logic). You can easily do this by extending com.caucho.rewrite.RequestPredicate. This essentially allows you to create your own <IfXXX> rule.

The following example demonstrates how to create a custom Resin predicate:

WEB-INF/resin-web.xml - Custom rule
<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:foo="urn:java:com.foo"
 ...
 <resin:Allow url-pattern="/safe/*"
    <foo:IfMyTest value="abcxyz"/>
 </resin:Allow url-pattern="/safe/*"
 ...
</web-app>
package com.foo;

import javax.servlet.http.HttpServletRequest;
import com.caucho.security.ServletRequestPredicate;

public class IfMyTest extends ServletRequestPredicate {
  private String value;

  // Your custom attribute for the tag.
  public void setValue(String value)
  {
    this.value = value;
  }

  // Here you must actually determine the match.
  public boolean isMatch(HttpServletRequest request)
  {
    return value.equals(request.getHeader("Foo"));
  }
}

<session-cookie>

child of cluster
default JSESSIONID

Configures the cookie used for servlet sessions.

<session-cookie> schema
element session-cookie {
  string
}

<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

<session-url-prefix>

child of cluster
default ;jsessionid=

Configures the URL prefix used for session rewriting.

note
Note
Session rewriting is discouraged as a potential security issue.
<session-url-prefix> schema
element session-cookie {
  string
}

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

<simple-loader>

child of class-loader

<simple-loader> Configures a simple WEB-INF/classes-style class loader.

.class files in the specified directory will be loaded without any special compilation steps (in contrast with compiling-loader.)

<simple-loader> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
pathFilesystem path for the class loader. Since Resin 3.0required
prefixClass package prefix to only load to a subset of classes. Resin 3.0none
<simple-loader> schema
element simple-loader {
  path
  & prefix?
}

<socket-timeout>

default 60s

<socket-timeout> is the maximum time a socket load balancer and distributed sessions will wait for a read or write to a cluster socket.

Crashed servers may never respond to a read request or accept a write. The socket-timeout lets Resin recover from these kinds of crashes.

Lower values can detect crashes more quickly, but too-low values may report bogus failures when the server machine is just a little slow.

socket-timeout
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="app-tier">
        <server-default>
          <socket-timeout>60s</socket-timeout>
        </server-default>

        <server id="a" address="192.168.0.10" port="6800"/>
        <server id="b" address="192.168.0.11" port="6800"/>

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

<spy>

child of database
default false

The <spy> tag is a very useful logging tag for debugging database problems. If <spy> is enabled, all database queries will be logged at the "fine" level. Applications can use <spy> to debug unexpected database queries, or to improve query performance.

Example: spy output
0.6:setString(1,1)
0.6:executeQuery(select o.DATA from my_bean o where o.ID=?)

<ssl-session-cookie>

child of cluster
default value of session-cookie

Defines an alternative session cookie to be used for a SSL connection. Having two separate cookies increases security.

<ssl-session-cookie> schema
element ssl-session-cookie {
  string
}
Example: ssl-session-cookie
<resin xmlns="http://caucho.com/ns/resin">
    <cluster id="web-tier">
        <ssl-session-cookie>SSLJSESSIONID</ssl-session-cookie>
        ...
    </cluster>
</resin>

<startup-mode>

<startup-mode> configures the virtual-host's behavior on Resin startup, either "automatic", "lazy" or "manual".

<startup-mode> Attributes
MODEDESCRIPTION
automaticautomatically start when Resin starts
lazystart only when the first request is received
manualstart only when JMX administration requests a start
<startup-mode> schema
element startup-mode {
  string
}

<stat-service>

<stat-service> periodically checks the status of the server, and reports errors as necessary.

<stat-service> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
unix-load-avg-exit-thresholdCPU load triggering a Resin exit (and restart)100.0
cpu-load-log-info-thresholdCPU load triggering a log message at the info level1.0
cpu-load-log-warning-thresholdCPU load triggering a log message at the warning level5.0
cpu-load-log-thread-dump-thresholdCPU load triggering thread dump to the log5.0
sample-periodhow often to sample the statistics60s
thread-dump-intervalminimum time between thread dumps15m
<stat-service> schema
element stat-service {
  unix-load-avg-exit-threshold?
  & cpu-load-log-info-threshold?
  & cpu-load-log-warning-threshold?
  & cpu-load-thread-dump-threshold?
  & sample-period?
  & thread-dump-interval?
}

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

<stderr-log>

Configures the destination for System.err.

The log configuration describes stderr-log in detail.

<stderr-log> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
archive-formatdefines a format string for log rollover
pathsets the VFS path for the log file
path-formatsets a pattern for creating the VFS path for the messages
rollover-countsets the maximum number of rollover files
rollover-periodsets the number of days before a log file rollover 1m
rollover-sizesets the maximum log size before a rollover1g
timestampsets the formatting string for the timestamp label
<stderr-log> schema
element stderr-log {
  (path | path-format)
  & archive-format?
  & rollover-period?
  & rollover-size?
  & rollover-count?
  & timestamp?
}

<stdout-log>

Configures the destination for System.out.

The log configuration describes stderr-log in detail.

<stdout-log> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
archive-formatdefines a format string for log rollover
pathsets the VFS path for the log file
path-formatsets a pattern for creating the VFS path for the messages
rollover-countsets the maximum number of rollover files
rollover-periodsets the number of days before a log file rollover 1m
rollover-sizesets the maximum log size before a rollover1g
timestampsets the formatting string for the timestamp label
<stdout-log> schema
element stdout-log {
  (path | path-format)
  & archive-format?
  & rollover-period?
  & rollover-size?
  & rollover-count?
  & timestamp?
}

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

<system-property>

Sets a Java system property. The effect is the same as if you had called java.lang.System#setProperty(String,String) before starting Resin.

<system-property> schema
element system-property {
  attribute * { string }+
}
Example: setting system property
<resin xmlns="http://caucho.com/ns/resin">
  <system-property foo="bar"/>
</resin>

Time intervals

Time intervals are used throughout Resin configuration. To specify the units for a given interval, use the appropriate suffix as shown below.

SUFFIXMEANING
sseconds
mminutes
hhours
Ddays

<temp-dir>

default Defaults to WEB-INF/tmp

<temp-dir> configures the application temp directory. This is the path used in javax.servlet.context.tempdir.

<temp-dir> schema
element temp-dir {
  string
}

<thread-idle-max>

child of server
default 10

<thread-idle-max> configures the maximum number of idle threads in the thread pool. <thread-idle-max> works with <thread-idle-min> to maintain a steady number of idle threads, avoiding the creation or destruction threads when possible.

<thread-idle-max> should be set high enough beyond <thread-idle-min> so a spiky load will avoid creating a thread and then immediately destroying it.

thread-idle-max in resin.xml
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
      <thread-max>512</thread-max>

      <thread-idle-min>10</thread-idle-min>
      <thread-idle-max>20</thread-idle-max>

      <jvm-arg>-Xss1m -Xmx1024m</jvm-arg>
    </server-default>

    <server id="web-a" address="192.168.0.10"/>
        ...
  </cluster>
</resin>

<thread-idle-min>

child of server
default 5

<thread-idle-min> configures the minimum number of idle threads in the thread pool. <thread-idle-min> helps spiky loads, avoiding delays for thread requests by keeping threads ready for future requests. When the number of idle threads drops below <thread-idle-min>, Resin creates a new thread.

<thread-idle-min> should be set high enough to deal with load spikes. Since idle threads are relatively inexpensive in modern operating systems, having a number of idle threads is not a major resource hog, especially since these threads are idle, waiting for a new job.

<thread-idle-min> works together with <thread-idle-max> to avoid thread allocation thrashing, i.e. avoiding creating a new thread because of <thread-idle-min> and then quickly destroying it because of <thread-idle-max>.

thread-idle-min in resin.xml
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
      <thread-max>512</thread-max>

      <thread-idle-min>10</thread-idle-min>
      <thread-idle-max>20</thread-idle-max>

      <jvm-arg>-Xss1m -Xmx1024m</jvm-arg>
    </server-default>

    <server id="web-a" address="192.168.0.10"/>
        ...
  </cluster>
</resin>

<thread-max>

child of server
default 4096

<thread-max> configures the maximum number of threads managed by Resin's thread pool. Resin's thread pool is used for connection threads, timers, and Resin worker threads for JMS, JCA and EJB. Since Resin's thread pool only manages Resin threads, the actual number of threads in the JVM will be higher.

Modern operating systems can handle a fairly large number of threads, so values of 512 or 1024 are often reasonable values for thread-max. The main limitation for thread-max is virtual memory. Since each thread takes up stack space (configured with -Xss), a 32-bit system might have a thread limit based on virtual memory.

For example, on Linux the user space is only 2G. If the heap memory is 1024m (-Xmx1024m) and the stack size is 1m (-Xss1m), the maximum number of threads is somewhat less than 1024.

In general, JVMs do not handle running out of threads very well, either freezing or throwing out of memory errors. Although it may be necessary to limit the number of threads to avoid running out of memory, <thread-max> should generally be set to a high value.

thread-max in resin.xml
<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
      <thread-max>512</thread-max>

      <jvm-arg>-Xss1m -Xmx1024m</jvm-arg>
    </server-default>

    <server id="web-a" address="192.168.0.10"/>
        ...
  </cluster>
</resin>

<transaction-timeout>

child of database
default -1

<transaction-timeout> configures the maximum time a transaction can be alive before a mandatory rollback.

<tree-loader>

child of class-loader

<tree-loader> configures a jar library, WEB-INF/lib-style class loader similar to library-loader, but will also find .jar and .zip files in subdirectories.

<tree-loader> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
pathFilesystem path for the class loader. Since Resin 3.0required
<tree-loader> schema
element tree-loader {
  path
}

<url-character-encoding>

child of cluster
default UTF-8

Defines the character encoding for decoding URLs.

The HTTP specification does not define the character-encoding for URLs, so the server must make assumptions about the encoding.

<url-character-encoding> schema
element url-character-encoding {
  string
}

<url-regexp>

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

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

<user-name>

child of server

<user-name> configures the operating system user Resin should run as. Since the HTTP port 80 is protected in Unix, the web server needs to start as root to bind to port 80. For security, Resin should switch to a non-root user after binding to port 80.

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

    <server-default>
      <http port="80"/>

      <user-name>resin</user-name>
    </server-default>

    <server id="web-a"/>
    ...
  </cluster>
</resin>

Variables: java

java properties
PROPERTYDESCRIPTION
versionReturns the JDK version from the java.version property

Variables: resin

resin properties
PROPERTYDESCRIPTION
addressThe machine's address as returned by InetAddress
confThe path to the resin.xml
homeThe --resin-home value, i.e. the location of the Resin installation
homeNameThe local hostname as returned by InetAddress
idThe --serverId command line value (see serverId)
isProfessional()True if Resin professional is installed and licensed
rootThe --resin-root value, i.e. the site's deployment directory
serverIdThe --serverId command line value
versionThe Resin version
versionDateThe compilation date of Resin

Variables: system

The ${system} variable return the System.getProperties() value.

Example: returning -Dfoo=bar
<resin xmlns="http://caucho.com/ns/resin"
      xmlns:resin="http://caucho.com/ns/resin/core">

  <resin:message>${system['foo']}</resin:message>

  ...
</resin>

<watchdog>

The <watchdog> tag is used in ISP-style configurations where the <watchdog-manager> is configured separately from the resin.xml instances, and where the configuration file is generally not readable by the instance users.

The <watchdog> tag corresponds to the <server> tag in standard resin.xml configurations, and specifies the resin.xml, the root directory and resin-user.

<watchdog> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
chrootcalls chroot before starting the Resin process
group-namesetgid value for unix systems
java-exejava executable to use for the Resin instancejava
java-homeJAVA_HOME value for the Resin instance
open-portlist of ports the watchdog should open for the Resin instance, e.g. for ports that require root access
resin.xmlPath to the resin.xml file for the Resin instancesame as for watchdog
resin-rootRoot directory for the Resin instancesame as for watchdog
<watchdog> schema
element watchdog {
  attribute id { string }
  & chroot?
  & group-name?
  & java-exe?
  & java-home?
  & jvm-arg*
  & resin.xml?
  & resin-root?
  & open-port { address & port }*
  & user-name?
}

<watchdog-arg>

child of server

The <watchdog-arg> configures arguments for the watchdog process. The watchdog improves reliability by monitoring the Resin instance, restarting it if necessary.

The <watchdog-arg> typically is used to enable jconsole for the watchdog JVM.

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

      <watchdog-arg>-Dcom.sun.management.jmxremote</watchdog-arg>

    </server-default>

    ...
       
  </cluster>
</resin>

<watchdog-manager>

For ISP configurations, <watchdog-manager> is used for a separate resin.xml just to configure the watchdog-manager itself. The <watchdog-manager> selects the <user-name>, <resin.xml>, ports, and Resin home directories before giving access to the user's Resin instance.

<watchdog-manager> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
watchdogWatchdog configuration for a Resin instance, corresponding to a <server> in the resin.xml
watchdog-addressThe TCP address the watchdog-manager listens for start, stop, status127.0.0.1
watchdog-defaultDefaults applied to all watchdog instances
watchdog-jvm-argJVM arguments for the watchdog-manager when launched
watchdog-portThe TCP port the watchdog-manager listens for start, stop, status6700
<watchdog-manager> schema
element watchdog-manager {
  watchdog*
  & watchdog-address?
  & watchdog-default*
  & watchdog-jvm-arg*
  & watchdog-port?
}

<watchdog-port>

child of server
default 6700

<watchdog-port> configures the administration port for the watchdog JVM. The watchdog launches the server JVM and monitors its health, restarting the JVM when necessary to improve site reliability. The command line arguments use the watchdog-port for the "start" and "stop" commands to tell the watchdog to start and stop the server JVM. The administration also uses the watchdog port for watchdog administration.

The watchdog port will use the same <address> as the server, so it will always be an internal network address, never an external internet address.

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

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.

<work-dir>

default Defaults to WEB-INF/work

<work-dir> configures a work directory for automatically generated code, e.g. for JSP, PHP, and JPA classes.

<work-dir> schema
element work-dir {
  string
}

Copyright © 1998-2012 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 blog wiki docs 
app server web server 
health cloud java ee pro