<document>
<localtoc/> <parents>resin, cluster, host, web-app, login-config</parents>

<authenticator> configures an authentication resource for the current environment context. The authenticator is used for login and also for the `getUserPrincipal` and `isUserInRole` methods of the `HttpServletRequest` object.

The authenticators are scoped to their containing environment. An authenticator defined in WEB-INF/resin-web.xml applies only to the web-app, while an authenticator defined in the <cluster> section of the resin.conf applies to the entire cluster. The <management> configuration provides an authenticator which is available to all applications.

Resin's servlet authentication uses an authentication resource to validate user login and to provide single-signon capability. The authenticator is configured in the environment context where it is shared. An authenticator configured in the web-app only applies to the web-app, but an authenticator configured in the host will apply to all hosts.

The authenticator class is selected with the uri or class attribute. The class can be any custom class extending `com.caucho.server.security.AbstractAuthenticator`. The uri is a symbolic name for the authenticator class. More details on the predefined authenticators are in the Resin security documentation.

- properties: Java properties-style authentication.
- jaas: JAAS authentication.
- jdbc: JDBC password-based authentication.
- xml: XML JDBC password-based authentication.

Configuration of the authenticator uses bean-style configuration in the <init> tag.

See also: the Resin security section.

Attribute Description Default
binding Custom WebBeans binding. Since Resin 3.1.5
class The implementing class for the authenticator. Since Resin 3.0
jndi-name The JNDI name where the authenticator is stored. Since Resin 3.0
name The Resin-IoC name where the authenticator is stored. Since Resin 3.1.5
uri shortcut alias for the authenticator class. Can also include inline parameters. Examples include xml:, property:, jdbc:, jndi:.
init A bean-style configuration section. Since Resin 3.0
r_authenticator = element authenticator { (r_class | r_uri) & r_binding* & r_init? & r_jndi-name? & r_name? & r_scope? } <web-app xmlns="http://caucho.com/ns/resin"> <authenticator uri="properties:password-digest=none"> <init> harry=quidditch,user ron=cannons,user,prefect </init> </authenticator> </web-app> <parents>resin, cluster, host, web-app</parents>

<bean> configures a custom singleton bean and stores in the WebBeans registry. <bean> is a primary configuration tag for Resin's IoC capabilities. The bean can also be optional registered in JNDI.

Custom configuration of the bean is in the <init> section. Field values may use JSP-EL expressions as well as constant strings or even complex sub-beans. More details for configuring singleton beans are in Resin IoC.

Attribute Description Default
class Application class implementing the resource. Since Resin 3.0 required
init IoC configuration for the bean
jndi-name JNDI name for the resource. Since Resin 3.0
mbean-name JMX name for management registration. Resin 3.0
name The name of the bean, used for @Named injection. Resin 3.1.4.
scope request, session, conversational, application, singleton. Resin 3.1.4. singleton
r_bean = element bean { r_class? & r_binding* & r_init? & r_jndi-name? & r_mbean-name? & r_mbean-interface? & r_name? & r_scope? } <web-app xmlns="http://caucho.com/ns/resin"> <bean name="test"> <type>test.MyBean</type> <init> <greeting>Hello</greeting> <server>${serverId}</server> <sub-bean> <value>${2 + 2}</value> </sub-bean> </init> </bean> </web-app> <parents>resin, cluster, host, web-app</parents> <default>true on Windows, false on Unix.</default>

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

r_case-insensitive = element case-insensitive { r_boolean-Type } <parents>resin, cluster, host, web-app</parents> <default>The default value is ISO-8859-1.</default>

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

r_character-encoding = element character-encoding { string } <resin xmlns="http://caucho.com/ns/resin"> <character-encoding>utf-8</character-encoding> ... </resin> <parents>resin, cluster, host, web-app</parents>

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

Element Description
<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.
r_class-loader = element class-loader { r_compiling-loader* & r_library-loader* & r_simple-loader* & r_tree-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> <parents>class-loader</parents>

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

Attribute Description Default
args Additional arguments to be passed to the Java compiler. Resin 3.0
batch If true, multiple changed *.java files will be compiled in a single batch. Resin 3.0.7 true
encoding I18N encoding for the Java compiler. Since Resin 3.0
path Filesystem path for the class loader. Since Resin 3.0 required
source Java source directory. Since Resin 3.0 value of path
require-source If true, .class files without matching .java files will be deleted. Since Resin 3.0 false
<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> <parents>resin, cluster, host, web-app</parents>

<component> configures a component bean template and stores in the WebBeans registry. Injection of a <component> will generally create a new bean instance in constrast to the singleton <bean>. <component> is a primary configuration tag for Resin's IoC capabilities. The bean can also be optionally registered in JNDI.

Custom configuration of the component is in the <init> section. Field values may use JSP-EL expressions as well as constant strings or even complex sub-beans. More details for configuring singleton beans are in Resin IoC.

Attribute Description Default
class Application class implementing the resource. Since Resin 3.0 required
init IoC configuration for the bean
jndi-name JNDI name for the resource. Since Resin 3.0
name The name of the bean, used for @Named injection. Resin 3.1.4.
scope dependent, request, session, conversational, application, singleton. Resin 3.1.4. dependent
r_component = element component { r_class? & r_binding* & r_init? & r_jndi-name? & r_name? & r_scope? } <web-app xmlns="http://caucho.com/ns/resin"> <component name="test"> <type>test.MyBean</type> <init> <greeting>Hello</greeting> <server>${serverId}</server> <sub-bean> <value>${2 + 2}</value> </sub-bean> </init> </component> </web-app> <parents>resin, cluster, host, web-app</parents>
JDBC Class Connector Class
Connection Connection (driver-defined class)
DataSource ConnectionFactory (driver-defined class)
Driver ManagedConnectionFactory
n/a ResourceAdapter
Attribute Description Default
class ManagedConnectionFactory driver for the resource required or uri
init IoC configuration for the ManagedConnectionFactory
local-transaction-optimization Enables the local transaction optimization during commit true
max-active-time Configures the maximum time allowed for a connection infinite
max-connections Configures the maximum connections available 1024
jndi-name JNDI name for the `ConnectionFactory`
name The IoC name for the `ConnectionFactory`, used for @Named injection. Resin 3.1.4.
resource-adapter The driver's `ResourceAdapter`
shareable Enables sharing of `Connection` objects in a transaction true
uri Shortcut alias for the ManagedConnectionFactory required or class
r_connection-factory = element connection-factory { (r_class | r_uri) & r_binding* & r_init? & r_jndi-name? & r_name? & local-transaction-optimization? & max-active-time? & max-connections? & resource-adapter? & shareable? } <parents>resin, cluster, host, web-app</parents>

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

The database configuration section has more details on the configuration. A code pattern for using databases is in a DataSource tutorial.

Attribute Description Default
backup-driver Configures a backup database driver. If Resin can't connect to any of the main drivers, it will use one of the. backups
close-dangling-connections If an application does not close a Connection by the end of the request, Resin will close it automatically an issue a warning. true
connection Defines initialization attributes for new connections, e.g. setting the transaction-isolation. true
connection-wait-time When max-connections has been reached, how long Resin will wait for a connection to become idle before giving up. 10min
driver Configures the database driver, giving the driver's class name as well as its JDBC URL and any other configuration. required
jndi-name The JNDI name to register the connection's `DataSource` under. If the name can be relative to java:comp/env.
max-active-time The maximum time Resin will allow a connection to remain open before forcing a close. 6 hours
max-close-statements The maximum number of Statements Resin will hold to automatically close when the Connection closes. 256
max-connections The maximum number of Connections allowed. 128
max-create-connections The maximum number of connection creation allowed at one time. 5
max-idle-count The maximum number of Connections in the idle pool. 1024
max-idle-time The maximum time a connection will spend in the idle pool before closing. 30s
max-overflow-connections The number of extra connection creation if the number of connections exceeds to pool size. 0
max-pool-time The total time a connection can be used before it is automatically closed instead of returned to the idle pool. 24h
name The IoC name to save the `ConnectionFactory` as, used with `@Named` to inject the resource.
password The JDBC password for the connection.
ping If true, Resin will ping the database before returning a connection from the pool (if ping-interval is exceeded). false
ping-interval How often an idle connection should ping the database to ensure it is still valid. 1s
ping-query A custom query used to ping the database connection.
ping-table A table used to ping the database connection.
prepared-statement-cache-size How many `PreparedStatements` to save in the prepared statement cache. 0
save-allocation-stack-trace If true, saves the location of the connection allocation as a stack trace. false
spy Enables spy logging of database statements. The logging occurs with name="com.caucho.sql" and level="fine". false
transaction-timeout Sets the transaction timeout. none
user Sets the authentication user.
wrap-statements If true, Resin wraps statements and automatically closes them on connection close. true
xa Enables 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-rm Workaround flag to handle certain database drivers that do not properly implement the XAResource API. false
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 * { * }? } <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> <parents>resin, cluster, host, web-app</parents>

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

element database-default { r_database-Content } <web-app xmlns="http://caucho.com/ns/resin"> <database-default> <max-idle-time>10s</max-idle-time> </database-default> </web-app> <parents>resin, cluster, host, web-app</parents>

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

Attribute Description Default
path Filesystem path to the dependent file. Since Resin 3.0 required
element dependency { string } <web-app xmlns="http://caucho.com/ns/resin"> <dependency path="WEB-INF/struts-config.xml"/> ... </web-app> <parents>resin, cluster, host, web-app</parents> <default>2s</default>

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

element dependency-check-interval { string } <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> <parents>resin, cluster, host, web-app</parents>

<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`. More details are available in the Resin Messaging section.

Attribute Description Default
activation-spec Configures a custom message-listener driver
class Classname of the listener bean required
destination Queue or Topic for JMS message receiving
destination-type javax.jms.Queue or javax.jms.Topic
init IoC configuration for the listener bean
message-consumer-max The number of listener instances to create for the pool. 5
element ejb-message-bean { class & init? & (activation-spec? | (destination? & destination-type? & destination-name? & message-consumer-max?) ) } <web-app xmlns="http://caucho.com/ns/resin"> <jms-connection-factory uri="resin:"/> <jms-queue name="my_queue" uri="memory:"/> <ejb-message-bean class="qa.MyListener"> <destination>${my_queue}</destination> </ejb-message-bean> </web-app> <web-app xmlns="http://caucho.com/ns/resin"> <resource-adapter uri="activemq:"/> <ejb-message-bean class="qa.MyListener"> <activation-spec uri="activemq:"> <init physical-name="queue.test"/> </activation-spec uri="activemq:"> </ejb-message-bean> </web-app> <parents>resin, cluster, host, web-app</parents>

Configures an EJB server. See Resin EJB for more details.

Attribute Description Default
auto-compile enables auto-compilation of EJB stubs and skeletons true
create-database-schema enables JPA auto-creation of missing database tables false
data-source specifies the default database for JPA
config-directory specifies a directory containing *.ejb configuration files
ejb-descriptor path to a *.ejb file to load
ejb-jar path to a jar file containing a META-INF/ejb-jar.xml with EJBs
jndi-prefix prefix for JNDI registration of EJBs
validate-database-schema verifies the actual database tables against the JPA definitions true
jms-connection-factory specifies the default JMS ConnectionFactory for message beans
xa-data-source specifies a separate database for transactions data-source
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 } <parents>resin, host-default, host, web-app-default, web-app</parents>

<ejb-stateful-bean> configures an EJB @Stateful bean. The @Stateful bean is a single-threaded component bean suitable for transaction processing. See Resin EJB for more details.

The stateful-bean is registered in the Resin-IoC/WebBeans context and optionally with JNDI.

Since @Stateful beans are components, they are created at the request of the application and destroyed by the application. @Stateful beans are never singletons. For singleton-style beans, either use a <bean> or a @Stateless session bean.

@Stateful beans may optionally implement a SessionSynchronization interface for transaction callbacks.

Attribute Description Default
class the classname of the bean implementation required
init IoC initialization for each bean instance
jndi-name A JNDI name to store the bean as.
name The Resin-IoC/WebBeans @Named registration The classname
scope The Resin-IoC/WebBeans scope: dependent, request, session, conversaion dependent classname
element ejb-stateful-bean { class & init? & jndi-name? & name? & scope? } <parents>resin, host-default, host, web-app-default, web-app</parents>

<ejb-stateless-bean> configures an EJB @Stateless bean. The @Statelesss bean is a pooled, proxied, singleton component bean suitable. See Resin EJB for more details.

The stateless-bean is registered in the Resin-IoC/WebBeans context and optionally with JNDI.

@Stateless beans are similar to <bean> singletons, but pool instances. Each instance executes a single thread at a time, unlike <bean> singletons which are multithreaded like servlets. Both styles can use the same aspect capabilities like dependency injection, transactions, and interceptors. Because @Stateless beans are singletons, they do not have a scope attribute.

Attribute Description Default
class the classname of the bean implementation required
init IoC initialization for each bean instance
jndi-name A JNDI name to store the bean as.
name The Resin-IoC/WebBeans @Named registration The classname
element ejb-stateless-bean { class & init? & jndi-name? & name? } <parents>resin, host-default, host, web-app-default, web-app</parents>

<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. As with other Resin configuration, the value can use JSP-EL expressions.

Attribute Description Default
env-entry-name JNDI name to store the value. Since Servlet 2.1 required
env-entry-type Java type for the value. Since Servlet 2.1 required
env-entry-value Value to be stored. Since Servlet 2.1 required
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.

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

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); } } ... }

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

Attribute Description Default
dir the starting directory required
include an include pattern do not include all files
exclude an exclude pattern do not exclude any files
element fileset { dir & exclude* & include*

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.

The following example matches .jar files in WEB-INF/lib. Since it does not search the lib directory recursively, WEB-INF/lib/foo/bar.jar will not match.

<fileset dir="WEB-INF/lib"> <include name="*.jar"/> </fileset> MATCH lib/foo.jar MATCH lib/bar.jar NO MATCH lib/baz/foo.jar

The following example matches .jar files in WEB-INF/lib recursively, so a deeper file like WEB-INF/lib/foo/bar.jar will match.

<fileset dir="WEB-INF/tree"> <include name="**/*.jar"/> </fileset> MATCH lib/foo.jar MATCH lib/bar.jar MATCH lib/baz/foo.jar <parents>resin, cluster, host, web-app</parents>

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

The javac configuration is used for JSP, PHP, EJB and compiling-loader configuration.

Attribute Description Default
args extra arguments to pass to the compiler
compiler the compiler name: eclipse, groovyc, internal, or a command-line
encoding the character encoding to use utf-8
max-batch the maximum number of source files to batch into one compilation 64
element javac { args* & compiler & encoding? & max-batch? }

The eclipse compiler requires the presence of $RESIN_HOME/lib/eclipse-compiler.jar (which is included with Resin). It is a very fast compiler that was developed as part of the Eclipse project.

<resin xmlns="http://caucho.com/ns/resin"> <javac compiler="eclipse" args="-source 1.5"/> ... </resin>

The internal compiler 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.

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

The javac compiler is included with the JDK. It executes that same 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.conf with the javac configuration option:

<resin xmlns="http://caucho.com/ns/resin"> <javac compiler="javac" args=""/> ... </resin> <parents>resin, cluster, host, web-app</parents>

<jms-connection-factory> configures a JMS `ConnectionFactory` and registers it with Resin-IoC/WebBeans. The `ConnectionFactory` can be specified by it's class or a URI alias.

See Resin messaging for more information.

Scheme Description
resin: Resin's ConnectionFactory implementation
Attribute Description Default
class class name of the ConnectionFactory implementation required (or uri)
init IoC initialization configuration for the factory
jndi-name Name for registering in JNDI, relative to java:comp/env
name @Named binding in Resin-IoC
uri URI alias for the ConnectionFactory class
element jms-connection-factory { (class | uri) & init? & jndi-name? & name? } <parents>resin, cluster, host, web-app</parents>

<jms-queue> configures a JMS `Queue` and registers it with Resin-IoC/WebBeans. Resin's JMS Queues implement the `BlockingQueue` interface and can be used directly or with the JMS `ConnectionFactory`.

See Resin messaging for more information.

The Queue can either be identified by the implementing class name or with a URI alias. Third-party queues using JCA will use the <resource-adapter> and either <connection-factory> or <activation-spec>.

Code sending messages to a Queue will typically use either the `BlockingQueue` API or JMS. Code receiving from a queue will generally use an EJB message bean.

Attribute Description Default
class class name of the Queue implementation required (or uri)
init IoC initialization for the Queue
jndi-name JNDI name for storing the Queue
name @Named binding for Resin-IoC
URI Description
file: Persistent, file-backed Queue
memory: Simple, memory-based Queue
server: Server side of a clustered Queue
client: Client side of a clustered Queue
element jms-queue { (class | uri) & init & jndi-name & name } <parents>resin, cluster, host, web-app</parents>

<jms-topic> configures a JMS `Topic` and registers it with Resin-IoC/WebBeans. Resin's JMS Topics implement the `BlockingTopic` interface and can be used directly or with the JMS `ConnectionFactory`.

See Resin messaging for more information.

The Topic can either be identified by the implementing class name or with a URI alias. Third-party topics using JCA will use the <resource-adapter> and either <connection-factory> or <activation-spec>.

Code sending messages to a Topic will typically use either the `BlockingTopic` API or JMS. Code receiving from a topic will generally use an EJB message bean.

Attribute Description Default
class class name of the Topic implementation required (or uri)
init IoC initialization for the Topic
jndi-name JNDI name for storing the Topic
name @Named binding for Resin-IoC
URI Description
file: Persistent, file-backed Topic
memory: Simple, memory-based Topic
server: Server side of a clustered Topic
client: Client side of a clustered Topic
element jms-topic { (class | uri) & init & jndi-name & name } <parents>resin, cluster, host, web-app</parents>

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

Attribute Description Default
factory Class name of the JNDI InitialContextFactory. Since Resin 1.2 optional
foreign-name The target name of the symbolic link, or the sub-context of the foreign JNDI context. Since Resin 1.2 none
init-param Configuration parameters for the JNDI environment passed to InitialContextFactory. Since Resin 1.2 none
jndi-name The JNDI name to use for the link. Resin 3.0 required
element jndi-link { jndi-name & factory? & foreign-name? & init-param* } <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> <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> <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> <parents>class-loader</parents>

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

<deftable>
Attribute Description Default
fileset An ant-style fileset
path Filesystem path for the class loader. Since Resin 3.0 required
element library-loader { fileset | path } element fileset { dir & exclude* & include* }

See DirectoryLoader.

<parents>resin, cluster, host, web-app</parents>

<log> configures JDK 1.4 java.util.logger handler.

The log configuration describes log in detail.

Attribute Description Default
archive-format defines a format string for log rollover
format defines the output formatting
formatter defines a custom formatter
handler defines a custom handler
level sets the logging level of the handler info
mbean-name sets an mbean-name to register the logger for runtime management
path sets the VFS path for the log file
path-format sets a pattern for creating the VFS path for the messages
rollover-count sets the maximum number of rollover files
rollover-period sets the number of days before a log file rollover 1m
rollover-size sets the maximum log size before a rollover 1g
timestamp sets the formatting string for the timestamp label
use-parent-handlers if true, the log is also copied to parent handlers true
element log { archive-format? & format? & formatter? & handler? & level? & mbean-name? & name & path? & path-format? & rollover-count? & rollover-period? & rollover-size? & timestamp? & use-parent-handlers? } <parents>resin, cluster, host, web-app</parents>

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

The log configuration describes log in detail.

Attribute Description Default
level the java.util.logging level: finest, finer, fine, config, info, warning, severe info
name the java.util.logging name, typically a classname required
use-parent-handlers if true, parent handlers are also invoked true
element logger { name & level? & use-parent-handlers? } <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> <parents>resin, cluster, host, web-app</parents>

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

Attribute Description Default
authenticator sets the javamail authenticator
debug sets the mail.debug flag
from sets the mail.from property
host sets the mail.host property
imap-host sets the mail.imap.host property
imap-port sets the mail.imap.port property
imap-user sets the mail.imap.user property
init IoC configuration for other properties
jndi-name JNDI name to store the mail Session
name Resin-IoC/WebBeans @Named value
pop3-host sets the mail.pop3.host property
pop3-port sets the mail.pop3.port property
pop3-user sets the mail.pop3.user property
smtp-host sets the mail.smtp.host property
smtp-port sets the mail.smtp.port property
smtp-user sets the mail.smtp.user property
store-protocol sets the mail.store.protocol property
transport-protocol sets the mail.transport.protocol property
user sets the mail.user property
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? } <parents>resin, cluster, host, web-app</parents>

<persistence-manager> configures JPA persistence defaults. More details on JPA are available on the Amber page.

Attribute Description Default
create-database-schema If true, Amber will automatically create the database schema false
cache-size Size of the entity cache 32k
data-source database used for JTA
jdbc-isolation JDBC isolation level used for connections
read-data-source Data source to be used for read-only queries data-source
validate-database-schema enables validation of the database tables on startup false
xa-data-source database to use in transactions data-source
element persistence-manager { create-database-schema & cache-size & cache-timeout & data-source & jdbc-isolation & read-data-source & validate-database-schema & xa-data-source } <parents>resin, cluster, host, web-app</parents>

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

Attribute Description Default
jndi-name JNDI name for the reference. Since Resin 3.0 required
factory Class name of the ObjectFactory. Resin 3.0 required
init Bean-style initialization for the factory none
element reference { factory & jndi-name & init-param* } <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> <parents>cluster, host, web-app</parents>

<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.
- See the hello world tutorial for an example.

Attribute Description Default
class Class name of the protocol implementation required (or uri)
init IoC initialization for the protocol implementation
name @Named binding for Resin-IoC
jndi-name JNDI binding name
uri Shortcut alias name for the protocol class
URI Description
cxf:url=http://foo.com/hello/cxf Defines a cxf service. See http://wiki.caucho.com/CXF for more information.
burlap:url=http://foo.com/hello/burlap Defines a burlap service at http://foo.com/hello/burlap
hessian:url=http://foo.com/hello/hessian Defines a hessian service at http://foo.com/hello/hessian
xfire:url=http://foo.com/hello/cxf Defines a xfire client. See http://wiki.caucho.com/XFire for more information.
element remote-client { (class|uri) & name? & jndi-name? & interface }

resin:choose implements an if, elsif, else.

Attribute Description
resin:when A configuration section executed when matching a test condition
resin:otherwise A fallback section executed when the tests fail

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.

element resin:choose { resin:when*, resin:otherwise } element resin:when { attribute test { string }, context-dependent content } element resin:otherwise { context-dependent content } <resin:choose> <resin:when test="${expr1}"> ... </resin:when> <resin:when test="${expr2}"> ... </resin:when> <resin:otherwise> ... </resin:otherwise> <resin:choose> <parents>resin:choose</parents>

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

Attribute Description
test the test to perform
element resin:when { attribute test { string }, context-dependent content } <parents>resin:choose</parents>

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

element resin:otherwise { context-dependent content }

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.

Attribute Description Default
test the test to perform required

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.

element resin:if { attribute test { string } context-dependent content } <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: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>.

Attribute Description Default
path a path to a file either path or fileset is required
fileset a fileset describing all the files to import. either path or fileset is required
optional if true, no error when file does not exist false
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.

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

<resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <cluster id="app-tier"> <host-deploy path="/var/www/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.

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

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

element resin:message { string } <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:set adds an EL variable to the current context.

Attribute Description Default
var name of the variable to set required
value value required
element set { name & value & default & attribute * { string } } <resin xmlns="http://caucho.com/ns/resin" xmlns:resin="http://caucho.com/ns/resin/core"> <resin:set name="root" value="/var/www"/> <cluster id="app-tier"> <root-directory>${root}</root-directory> ... </cluster> </resin> <parents>resin, cluster, host, web-app</parents>

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

<parents>resin, cluster, host, web-app</parents>

<resource-adapter> configures a JCA `ResourceAdapter` in combination with <connection-factory> for connections or <activation-spec for message listeners. See Resin messaging for typical uses.

`ResourceAdapters` can be deployed in .rar files, but this is not required by Resin. Instead, you can configure the ResourceAdapter directly.

A symbolic URI can be used in place of the ResourceAdapter's class name.

Attribute Description Default
class The classname of the ResourceAdapter implementation class required (or uri)
init IoC initialization for the ResourceAdapter
jndi-name JNDI name for binding the ResourceAdapter
name @Named binding for Resin-IoC injection.
uri Alias schema for the ResourceAdapter class name
element resource-adapter { (class | uri) & init? & name? & jndi-name? } <parents>resin, cluster, host-default, host, web-app-default, web-app</parents>

<resource-deploy> defines a deployment directory for .rar files.

Connectors and resources defined in .rar files must be deployed before they can be configured by connector. The <resource-deploy> tag specifies the directory for that deployment.

Attribute Description Default
resource-deploy Configures .rar deployment required
path Configures the path where users will place .rar files required
expand-path Configures the directory where Resin will expand rar files the path value
element resource-deploy { path & expand-directory? & expand-path? & resource-default? } <resin xmlns="http://caucho.com/ns/resin"> <cluster id="app-tier"> <host id=""> <resource-deploy path="deploy"/> </host> </cluster> </resin> <parents>resin, cluster, host, web-app</parents>

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

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

<scheduled-task> 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 IoC bean, the bean task has full IoC capabilities, including injection, @TransactionAttribute aspects, interception and @Observes.

Attribute Description
class the classname of the singleton bean to create
cron a cron-style scheduling description
delay a simple delay-based execution
init IoC initialization for the bean
mbean-name optional MBean name for JMX registration
method EL expression for a method to be invoked as the task
name optional IoC name for registering the task
period how often the task should be invoked in simple mode
task alternate task assignment for predefined beans
element scheduled-task { class? & cron? & delay? & init? & mbean-name? & method? & name? & period? & task? }

The most common and flexible job configuration uses standard IoC bean-style configuration. The bean must implement `Runnable`. Like the <bean> tag, the class attribute specifies the `Runnable` class, and any init section configures the bean using Resin IoC configuration.

<web-app xmlns="http://caucho.com/ns/resin"> <scheduled-task class="qa.MyTask"> <cron>*/5</cron> </scheduled-task> </web-app>

The task bean can also be passed to the <scheduled-task> using a Resin-IoC EL reference. The name of the task bean would be defined previously, either in a <bean> or <component> or picked up by classpath scanning. Like the bean-style job configuration, the reference bean must implement `Runnable`.

<web-app xmlns="http://caucho.com/ns/resin"> <scheduled-task task="#{taskBean}"> <cron>0 0 *</cron> </scheduled-task> </web-app>

<scheduled-task> can execute a method on a defined bean as the scheduler's task. The method is specified using EL reference syntax. At each trigger time, <scheduled-task> will invoke the EL method expression.

In the following example, the task invokes `myMethod()` on the myBean singleton every 1 hour.

<web-app xmlns="http://caucho.com/ns/resin"> <bean name="myBean" class="qa.MyBean"/> <scheduled-task method="#{myBean.myMethod}"> <delay>10m</delay> <period>1h</period> </scheduled-task> </web-app>

In a <web-app>, the <scheduled-task> can invoke a servlet URL at the trigger times. The task uses the servlet `RequestDispatcher` and forwards to the specified URL. The URL is relative to the <web-app> which contains the <scheduled-task.

<web-app xmlns="http://caucho.com/ns/resin"> <scheduled-task url="/cron.php"> <cron>0 15 * * 0</cron> </scheduled-task> </web-app> <parents>class-loader</parents>

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.

element servlet-hack { boolean } <parents>class-loader</parents>

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

Attribute Description Default
path Filesystem path for the class loader. Since Resin 3.0 required
prefix Class package prefix to only load to a subset of classes. Resin 3.0 none
element simple-loader { path & prefix? } <parents>resin, cluster, host-default, host, web-app-default, web-app</parents>

Configures the destination for `System.err`.

The log configuration describes stderr-log in detail.

Attribute Description Default
archive-format defines a format string for log rollover
path sets the VFS path for the log file
path-format sets a pattern for creating the VFS path for the messages
rollover-count sets the maximum number of rollover files
rollover-period sets the number of days before a log file rollover 1m
rollover-size sets the maximum log size before a rollover 1g
timestamp sets the formatting string for the timestamp label
element stderr-log { (path | path-format) & archive-format? & rollover-period? & rollover-size? & rollover-count? & timestamp? } <parents>resin, cluster, host-default, host, web-app-default, web-app</parents>

Configures the destination for `System.out`.

The log configuration describes stderr-log in detail.

Attribute Description Default
archive-format defines a format string for log rollover
path sets the VFS path for the log file
path-format sets a pattern for creating the VFS path for the messages
rollover-count sets the maximum number of rollover files
rollover-period sets the number of days before a log file rollover 1m
rollover-size sets the maximum log size before a rollover 1g
timestamp sets the formatting string for the timestamp label
element stdout-log { (path | path-format) & archive-format? & rollover-period? & rollover-size? & rollover-count? & timestamp? } <parents>resin, cluster, host, web-app</parents>

Sets a Java system property. The effect is the same as if you had called before starting Resin.

element system-property { attribute * { string }+ } <resin xmlns="http://caucho.com/ns/resin"> <system-property foo="bar"/> </resin> <parents>resin, cluster, host-default, host, web-app-default, web-app</parents> <default>Defaults to WEB-INF/tmp</default>

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

element temp-dir { string } <parents>class-loader</parents>

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

Attribute Description Default
path Filesystem path for the class loader. Since Resin 3.0 required
element tree-loader { path } <parents>resin, config, host, web-app</parents> <default>Defaults to WEB-INF/work</default>

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

element work-dir { string }
</document>