<document>
<localtoc/> <parents>resin, server, host-default, host, web-app-default, web-app</parents>

Adds dynamic classloaders to the current environment.

Each environment (<server>, <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, even make-loader for more complex auto-compilation.

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

Configures an auto-compiling WEB-INF/classes-style class loader.

The compiling-loader will automatically compile Java code into .class files loading them.

args Additional arguments to be passed to the Java compiler. Resin 3.0 none
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 none
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
<parents>class-loader</parents>

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

path Filesystem path for the class loader. Since Resin 3.0 required

See .

<parents>class-loader</parents>

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

path Filesystem path for the class loader. Since Resin 3.0 required

See .

<parents>class-loader</parents>

Configures a custom make-style loader.

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

<parents>class-loader</parents>

Configures a simple classes-style class loader.

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

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
<parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures a cluster of Resin servers for load balancing and sharing state information.

Each cluster is a collection of Resin servers. The servers will share session information if the sessions are configured for <cluster-store>.

Each environment context is associated with a single cluster. If no cluster is defined for the context, it defaults to the parent cluster.

Normally, the cluster will be configured in the <server> context, although a cluster could be defined in a web-app for finer load-balancing. Only clusters defined in the <server> context are used for listening to ports. Other clusters are only for outgoing load balancing.

id identifies the cluster for later reference. Since Resin 3.0 none
srun configures the srun port and protocol for a cluster server. Since Resin 3.0 none
cluster-group specialized configuration for sub-clusters. Since Resin 3.0 none
cluster-ref an identifier for a previous cluster-definition to use for the cluster. Since Resin 3.0 none
<example> <resin xmlns="http://caucho.com/ns/resin"> <server> <cluster> <srun id='a' port='6810'/> <srun id='b' port='6811'/> </cluster> ... <parents>resin, server, host-default, host, web-app-default, web-app</parents>

Defines a cluster for later use by cluster-ref.

id identifies the cluster for later reference. Since Resin 3.0 required
srun configures the srun port and protocol for a cluster server. Since Resin 3.0 none
cluster-group specialized configuration for sub-clusters. Since Resin 3.0 none
<parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures a JCA resource adapter and its associated connection factories.

The resource adapter/connector will have been added as a rar file (see resource-deploy. The <connector> configures that rar resource.

<connector connector-name="Test Resource"> <connection-factory jndi-name="eis/test"> <init> <value>b</value> </init> </connection-factory> </connector>
connector Configures a connector required
connector-name Specifies the rar connector's display-name required
resource-adapter Configures the resource-adapter optional
connection-factory Configures a connection-factory optional
jndi-name JNDI name for a resource-adapter or connection-factory required
type For connectors with multiple connection-factories, specifies the connection-factory optional
local-transaction-optimization Enables the local transaction optimization. Resin 3.0.7 true
init Bean-style initialization optional
element connector { connector-name { string } & resource-adapter? & connection-factory* } element connection-factory { jndi-name, type?, element init { any }? } element resource-adapter { jndi-name, element init { any }? } <parents>resin, server, host-default, host, web-app-default, web-app</parents>

Defines a database resource.

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

<example> <database jndi-name='jdbc/test_mysql'> <driver type="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource"> <url>jdbc:mysql://localhost:3306/test</url> <user></user> <password></password> </driver> </database> <parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures an EJB/CMP server. See the CMP configuration for more details.

<parents>resin, server, host-default, host, web-app-default, web-app</parents>

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.

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

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.

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

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); } } ... } element env-entry { (attribute env-entry-name { string } | element env-entry-name { string }), (attribute env-entry-type { string } | element env-entry-type { string }), (attribute env-entry-value { string } | element env-entry-value { string }) } <parents>resin, server, host-default, host, web-app-default, web-app</parents>

Links a foreign JNDI contexts or JNDI object.

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-name The JNDI name where the foreign context should be linked. Resin 3.0 required
factory Class name of the JNDI InitialContextFactory. Since Resin 1.2 optional
foreign-name 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-link> <jndi-name>java:comp/env/ejb/traderHome</jndi-name> <factory>weblogic.jndi.WLInitialContextFactory</factory> <init-param java.naming.provider.url="t3://localhost:7001"/> <foreign-name>statelessSession/TraderHome</foreign-name> </jndi-link> <jndi-link> <jndi-name>java:comp/env/ejb/MyBean</jndi-name> <foreign-name>/SampleBean</foreign-name> </jndi-link> <parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures a JNDI ObjectFactory.

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

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
<example> <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> <parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures a custom bean resource and stores in JNDI.

Resources are beans stored in JNDI. The resources can be created from any Java class that conforms to the bean conventions. Configuration of the resource is in the <init> section. Field values may use JSP-EL expressions as well as constant strings or even complex sub-beans.

jndi-name JNDI name for the resource. Since Resin 3.0 required
type Bean class implementing the resource. Since Resin 3.0 required
arg Arguments to the resource's constructor. Since Resin 3.0 optional
mbean-name JMX name for management registration. Resin 3.0 optional
init Bean-style initialization for the bean optional
listener Registers the bean as a listener for a JMX emitter. Resin 3.0 optional
local-transaction-optimization Enables the local transaction optimization. Resin 3.0.7 true
<example> <resource jndi-name="env/test"> <type>test.MyBean</type> <init> <greeting>Hello</greeting> <server>${'${'}serverId}</server> <sub-bean> <value>${'${2'} + 2}</value> </sub-bean> </init> </resource> r_listener-Resource = element listener { r_mbean-name, r_handback* } r_resource = element resource { (r_jndi-name? & r_mbean-name? & r_mbean-interface?), (r_type, r_arg*)?, (r_init* & r_listener-Resource*) } <parents>resin, server, host-default, host, web-app-default, web-app</parents>

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.

<host> <resource-deploy path="deploy"/> ... </host>
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 { (attribute path { string } | element path { string }) & (attribute expand-path { string } | element expand-path { string })? } <parents>resin, server, host-default, host, web-app-default, web-app</parents>

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.

<parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures JDK 1.4 java.util.logger logging.

The log configuration describes log in detail.

<parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures the destination for `System.err`.

The log configuration describes stderr-log in detail.

<parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures the destination for `System.out`.

The log configuration describes stderr-log in detail.

<parents>resin, server, host-default, host, web-app-default, web-app, login-config</parents>

Configures an authentication resource for the current context.

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. So 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 type attribute. It can be any custom class extending `com.caucho.server.security.AbstractAuthenticator`. Configuration of the authenticator uses bean-style configuration in the <init> tag.

jndi-name The JNDI name where the authenticator is stored. Since Resin 3.0 java:comp/env/caucho/auth
type The implementing class for the authenticator. Since Resin 3.0 required
init A bean-style configuration section. Since Resin 3.0 none
<parents>resin, server, host-default, host, web-app-default, web-app</parents>

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

<example> <resin> <system-property foo="bar"/> </resin> <parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures the Java compiler for automatically compiled files.

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

compiler Configures the Java compiler to use. Since Resin 3.0 internal
args Any additional arguments for the compiler. Since Resin 3.0 none
encoding Any encoding valued for the compiler. Since Resin 3.0 none
<parents>resin, server, host-default, host, web-app-default, web-app</parents>

Configures a path as a file which should force a reload when changed, like web.xml and resin.xml.

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

Configures how often the environment context should be checked for changes.

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.

<parents>resin, server, host-default, host, web-app-default, web-app</parents> <default>The default value is ISO-8859-1.</default>

Specifies the default character encoding for the environment.

<example> <web-app id='/'> <character-encoding>shift_jis</character-encoding> ... </web-app> <parents>resin, server, host-default, host, web-app-default, web-app</parents> <default>true on Windows, false on Unix.</default>

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.

<parents>resin, server, host-default, host, web-app-default, web-app</parents> <default>Defaults to WEB-INF/tmp</default>

Application temp directory. This is the path used in javax.servlet.context.tempdir.

<parents>resin, server, host-default, host, web-app-default, web-app</parents> <default>Defaults to WEB-INF/work</default>

Application work directory. This is the directory used for generated code like JSP, XSL and EJB classes.

</document>