<document>
<header>
<product>resin</product>
<title>Environment: Class Loaders, Resources and JNDI</title>
<version>Resin 3.0</version>

<description>
<p>Resin organizes resources and classloaders into nested environments.
Each environment context merges its own configuration with configuration
inherited from the parent environment.  Each environment context: server,
host, web-app, etc. may be configured with any of the environment
configuration tags.
</p>
</description>
</header>

<summary objsummary='localtoc'/>

<section title="Classloaders">
<defun title="class-loader" occur="*" version="Resin 3.0">
  <parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.loader.DynamicLoader -->

<p>Adds dynamic classloaders to the current environment.</p>

<p>Each environment (&lt;server>, &lt;host>, &lt;web-app>) etc,
can add dynamic classloaders.  The environment will inherit the parent
classloaders.  Each &lt;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.</p>

<example>
&lt;web-app>
  &lt;class-loader>
    &lt;compiling-loader path="WEB-INF/classes"/>

    &lt;library-loader path="WEB-INF/lib"/>
  &lt;/class-loader>
&lt;/web-app>
</example>

</defun>

<defun title="compiling-loader" occur="*" version="Resin 3.0">
  <parents>class-loader</parents>
  <!-- com.caucho.loader.CompilingLoader -->

<p>Configures an auto-compiling <var/WEB-INF/classes/>-style class loader.</p>

<p>The compiling-loader will automatically compile Java code into .class
files loading them.</p>

<deftable-childtags>
<tr><td>args<td>Additional arguments to be passed to the Java compiler. Resin 3.0<td>none
<tr><td>batch<td>If true, multiple changed *.java files will be compiled in a single batch. Resin 3.0.7<td>true
<tr><td>encoding<td>I18N encoding for the Java compiler. Since Resin 3.0<td>none
<tr><td>path<td>Filesystem path for the class loader.  Since Resin 3.0<td>required
<tr><td>source<td>Java source directory. Since Resin 3.0<td>value of path
<tr><td>require-source<td>If true, .class files without matching .java files will be deleted. Since Resin 3.0<td>false
</deftable-childtags>

</defun>

<defun title="library-loader" occur="*" version="Resin 3.0">
  <parents>class-loader</parents>

<p>Configures a jar library, <var/WEB-INF/lib/>-style class loader.</p>

<p>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
<code>.jar</code> or <code>.zip</code>.</p>

<deftable-childtags>
<tr><td>path<td>Filesystem path for the class loader.  Since Resin 3.0<td>required
</deftable-childtags>

See <a href="javadoc|com.caucho.loader.DirectoryLoader|"/>.
</defun>

<defun title="tree-loader" occur="*" version="Resin 3.0">
  <parents>class-loader</parents>
  <!-- com.caucho.loader.TreeLoader -->

<p>Configures a jar library, <var/WEB-INF/lib/>-style class loader similar to
<a config-tag="library-loader"/>, but will also find <code>.jar</code> and
<code>.zip</code> files in subdirectories.</p>

<deftable-childtags>
<tr><td>path<td>Filesystem path for the class loader.  Since Resin 3.0<td>required
</deftable-childtags>

See <a href="javadoc|com.caucho.loader.TreeLoader|"/>.
</defun>

<defun title="make-loader" occur="*" version="Resin 3.0">
  <parents>class-loader</parents>
  <!-- com.caucho.loader.MakeLoader -->

<p>Configures a custom make-style loader.</p>
</defun>

<defun title="servlet-hack" occur="*" version="Resin 3.0">
  <parents>class-loader</parents>

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

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

</defun>

<defun title="simple-loader" occur="*" version="Resin 3.0">
  <parents>class-loader</parents>
  <!-- com.caucho.loader.SimpleLoader -->

<p>Configures a simple <var/classes/>-style class loader.</p>

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

<deftable-childtags>
<tr><td>path<td>Filesystem path for the class loader.  Since Resin 3.0<td>required
<tr><td>prefix<td>Class package prefix to only load to a subset of classes. Resin 3.0<td>none
</deftable-childtags>

</defun>

</section>

<section title="Clustering">
<defun title="cluster" occur="?" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.server.cluster.Cluster -->

<p>Configures a cluster of Resin servers for load balancing and sharing
state information.</p>

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

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

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

<deftable-childtags>
<tr><td>id<td>identifies the cluster for later reference.  Since Resin 3.0<td>none
<tr><td>srun<td>configures the srun port and protocol for a cluster server. Since Resin 3.0<td>none
<tr><td>cluster-group<td>specialized configuration for sub-clusters. Since Resin 3.0<td>none
<tr><td>cluster-ref<td>an identifier for a previous cluster-definition to use for the cluster.  Since Resin 3.0<td>none
</deftable-childtags>

<example>
&lt;resin xmlns="http://caucho.com/ns/resin">
&lt;server>
  &lt;cluster>
    &lt;srun id='a' port='6810'/>
    &lt;srun id='b' port='6811'/>
  &lt;/cluster>
  ...
</example>
</defun>

<defun title="cluster-definition" occur="*" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.server.cluster.ClusterDef -->

<p>Defines a cluster for later use by cluster-ref.</p>

<deftable-childtags>
<tr><td>id<td>identifies the cluster for later reference.  Since Resin 3.0<td>required
<tr><td>srun<td>configures the srun port and protocol for a cluster server. Since Resin 3.0<td>none
<tr><td>cluster-group<td>specialized configuration for sub-clusters. Since Resin 3.0<td>none
</deftable-childtags>

</defun>
</section>

<section title="Resources">

<defun title="connector" occur="*" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.jca.ConnectorResource -->

<p>Configures a JCA resource adapter and its
associated connection factories.</p>

<p>The resource adapter/connector  will have been added as a rar
file (see <a href="#resource-deploy">resource-deploy</a>.  The
&lt;connector> configures that rar resource.</p>

<example title="Connector Example">
&lt;connector connector-name="Test Resource">
  &lt;connection-factory jndi-name="eis/test">
    &lt;init>
      &lt;value>b&lt;/value>
    &lt;/init>
  &lt;/connection-factory>
&lt;/connector>
</example>

<deftable-childtags>
<tr><td>connector<td>Configures a connector<td>required
<tr><td>connector-name<td>Specifies the rar connector's display-name<td>required
<tr><td>resource-adapter<td>Configures the resource-adapter<td>optional
<tr><td>connection-factory<td>Configures a connection-factory<td>optional
<tr><td>jndi-name<td>JNDI name for a resource-adapter or connection-factory<td>required
<tr><td>type<td>For connectors with multiple connection-factories, specifies the connection-factory<td>optional
<tr><td>local-transaction-optimization<td>Enables the local transaction optimization. Resin 3.0.7<td>true
<tr><td>init<td>Bean-style initialization<td>optional
</deftable-childtags>

<def title="connector schema">
r_connector = element connector {
  (attribute connector-name { string } | element connector-name { string })

  & r_resource-adapter?

  & r_connection-factory*
}

r_connection-factory = element connection-factory {
  (attribute jndi-name { string } | element jndi-name { string }),

  (attribute type { string } | element type { string })?,

  element init { any }?
}

r_resource-adapter = element resource-adapter {
  (attribute jndi-name { string } | element jndi-name { string }),

  element init { any }?
}
</def>

</defun>

<defun title="database" occur="*" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.sql.DBPool -->

<p>Defines a database resource.</p>

<p>The <a href="doc|db|config">database configuration</a> section has
more details on the configuration.  A code pattern for using databases
is in a <a href="doc|db|tutorial/jdbc-basic/index">DataSource tutorial.</a></p>

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

</defun>

<defun title="ejb-server" occur="*" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.ejb.EJBServer -->

<p>Configures an EJB/CMP server.  See the CMP configuration for more details.</p>
</defun>

<defun title="env-entry" occur="*" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.config.types.EnvEntry -->

<p>Configures a JNDI scalar value for JNDI-based application configuration.</p>

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

<deftable-childtags>
<tr><td>env-entry-name<td>JNDI name to store the value.  Since Servlet 2.1<td>required
<tr><td>env-entry-type<td>Java type for the value.  Since Servlet 2.1<td>required
<tr><td>env-entry-value<td>Value to be stored.  Since Servlet 2.1<td>required
</deftable-childtags>

<p>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 &lt;host> context, it will
be visible to all web-apps in the host.</p>

<example title="Example resin.conf fragment">
&lt;env-entry>
  &lt;env-entry-name>greeting&lt;/env-entry-name>
  &lt;env-entry-type>java.lang.String&lt;/env-entry-type>
  &lt;env-entry-value>Hello, World&lt;/env-entry-value>
&lt;/env-entry>
</example>

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

<example title="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);
    }
  }

  ...
}
</example>

<def title="env-entry schema">
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 })
}
</def>

</defun>
  
<defun title="jndi-link" occur="*" version="Resin 1.2">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.naming.LinkProxy -->

<p>Links a foreign JNDI contexts or JNDI object.</p>

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

<deftable-childtags>
<tr><td>jndi-name<td>The JNDI name where the foreign context should be linked.  Resin 3.0<td>required
<tr><td>factory<td>Class name of the JNDI InitialContextFactory.  Since Resin 1.2<td>optional
<tr><td>foreign-name<td>Sub-context of the foreign JNDI context.  Since Resin 1.2<td>none
<tr><td>init-param<td>Configuration parameters for the JNDI environment passed to InitialContextFactory.  Since Resin 1.2<td>none
</deftable-childtags>

<example title="Linking a WebLogic EJB client bean">
&lt;jndi-link>
  &lt;jndi-name>java:comp/env/ejb/traderHome&lt;/jndi-name>
  &lt;factory>weblogic.jndi.WLInitialContextFactory&lt;/factory>
  &lt;init-param java.naming.provider.url="t3://localhost:7001"/>
  &lt;foreign-name>statelessSession/TraderHome&lt;/foreign-name>
&lt;/jndi-link>
</example>

<example title="A JNDI symbolic link EJB client bean">
&lt;jndi-link>
  &lt;jndi-name>java:comp/env/ejb/MyBean&lt;/jndi-name>
  &lt;foreign-name>/SampleBean&lt;/foreign-name>
&lt;/jndi-link>
</example>

</defun>

<defun title="reference" occur="*" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.config.types.ReferenceConfig -->

<p>Configures a JNDI ObjectFactory.</p>

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

<deftable-childtags>
<tr><td>jndi-name<td>JNDI name for the reference.  Since Resin 3.0<td>required
<tr><td>factory<td>Class name of the ObjectFactory. Resin 3.0<td>required
<tr><td>init<td>Bean-style initialization for the factory<td>none
</deftable-childtags>

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

</defun>

<defun title="resource" occur="*" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.config.types.Resource -->

<p>Configures a custom bean resource and stores in JNDI.</p>

<p>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 &lt;init> section.  Field values may
use JSP-EL expressions as well as constant strings or even complex
sub-beans.</p>

<deftable-childtags>
<tr><td>jndi-name<td>JNDI name for the resource.  Since Resin 3.0<td>required
<tr><td>type<td>Bean class implementing the resource. Since Resin 3.0<td>required
<tr><td>arg<td>Arguments to the resource's constructor.  Since Resin 3.0<td>optional
<tr><td>mbean-name<td>JMX name for management registration. Resin 3.0<td>optional
<tr><td>init<td>Bean-style initialization for the bean<td>optional
<tr><td>listener<td>Registers the bean as a listener for a JMX emitter. Resin 3.0<td>optional
<tr><td>local-transaction-optimization<td>Enables the local transaction optimization. Resin 3.0.7<td>true
</deftable-childtags>

<example>
&lt;resource jndi-name="env/test">
  &lt;type>test.MyBean&lt;/type>
  &lt;init>
    &lt;greeting>Hello&lt;/greeting>
    &lt;server>${'${'}serverId}&lt;/server>
    &lt;sub-bean>
      &lt;value>${'${2'} + 2}&lt;/value>
    &lt;/sub-bean>
  &lt;/init>
&lt;/resource>
</example>

<def title="schema">
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*)
}
</def>

</defun> 

<defun title="resource-deploy" occur="*" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.jca.ResourceDeploy -->

<p>Defines a deployment directory for .rar files.</p>

<p>Connectors and resources defined in .rar files must be deployed
before they can be configured by <a href="#connector">connector</a>.
The &lt;resource-deploy> tag specifies the directory for that deployment.
</p>

<example title="example resource-deploy">
&lt;host>
  &lt;resource-deploy path="deploy"/>

  ...
&lt;/host>
</example>

<deftable-childtags>
<tr><td>resource-deploy<td>Configures .rar deployment<td>required
<tr><td>path<td>Configures the path where users will place .rar files<td>required
<tr><td>expand-path<td>Configures the directory where Resin will expand rar files<td>the path value
</deftable-childtags>

<def title="schema">
element resource-deploy {
  (attribute path { string } | element path { string })

  & (attribute expand-path { string } | element expand-path { string })?
}
</def>

</defun>

<defun title="resource-ref" occur="*" version="Servlet 2.2">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.config.types.ResourceRef -->

<p>Declares that the application needs a resouce configuration.</p>

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

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

</defun>
</section>

<section title="Logging">
<defun title="log" occur="*">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>

<p>Configures JDK 1.4 java.util.logger logging.</p>

<p>The <a href="config|log">log configuration</a> describes
log in detail.</p>

</defun>

<defun title="stderr-log" occur="?">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>

<p>Configures the destination for <code/System.err/>.</p>

<p>The <a href="doc|config|log">log configuration</a> describes
stderr-log in detail.</p>

</defun>

<defun title="stdout-log" occur="?">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>

<p>Configures the destination for <code/System.out/>.</p>

<p>The <a href="doc|config|log">log configuration</a> describes
stderr-log in detail.</p>
</defun>
</section>

<section title="Authenticator">
<defun title="authenticator" occur='*'>
<parents>resin, server, host-default, host, web-app-default, web-app, login-config</parents>
  <!-- com.caucho.config.types.Authenticator -->

<p>Configures an authentication resource for the current context.</p>

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

<p>The authenticator class is selected with the <var/type/> attribute.  It
can be any custom class
extending <code/com.caucho.server.security.AbstractAuthenticator/>.
Configuration of the authenticator uses bean-style configuration in the
&lt;init> tag.</p>

<deftable-childtags>
<tr><td>jndi-name<td>The JNDI name where the authenticator is stored.  Since Resin 3.0<td>java:comp/env/caucho/auth
<tr><td>type<td>The implementing class for the authenticator.  Since Resin 3.0<td>required
<tr><td>init<td>A bean-style configuration section.  Since Resin 3.0<td>none
</deftable-childtags>

</defun>
</section>

<section title="Miscellaneous">
<defun title="system-property" occur="*" version="Resin 2.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>

<p>Sets a Java system property.  The effect is the same as if you
had called <a href="javadoc|java.lang.System|setProperty(String,String)"/> before starting Resin.</p>

<example>
&lt;resin&gt;
  &lt;system-property foo="bar"/>
&lt;/resin&gt;
</example>
</defun>

<defun title="javac" occur="?">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
  <!-- com.caucho.java.JavacConfig -->

<p>Configures the Java compiler for automatically compiled files.</p>

<p>The javac configuration is used for JSP, XSL, EJB and
compiling-loader configuration.</p>

<deftable-childtags>
<tr><td>compiler<td>Configures the Java compiler to use.  Since Resin 3.0<td>internal
<tr><td>args<td>Any additional arguments for the compiler.  Since Resin 3.0<td>none
<tr><td>encoding<td>Any encoding valued for the compiler.  Since Resin 3.0<td>none
</deftable-childtags>

</defun>

<defun title="dependency" occur="?" version="Resin 3.0.1">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>

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

<deftable-childtags>
<tr><td>path<td>Filesystem path to the dependent file.  Since Resin 3.0<td>required
</deftable-childtags>

<example title="web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">
  &lt;dependency path="WEB-INF/struts-config.xml"/>
  ...
&lt;/web-app>
</example>

</defun>

<defun title="dependency-check-interval" occur="?" version="Resin 3.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
<default>2s</default>

<p>Configures how often the environment context
should be checked for changes.</p>

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

<p>The interval defaults to the parent's interval.  So the web-app will
default to the host's value.</p>
</defun>

<defun title="character-encoding" occur='?' version='Resin 1.1'>
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
<default>The default value is ISO-8859-1.</default>

<p>Specifies the default character encoding for the environment.</p>


<example>
&lt;web-app id='/'&gt;
  &lt;character-encoding&gt;shift_jis&lt;/character-encoding&gt;
  ...

&lt;/web-app>
</example>
</defun>

<defun title="case-insensitive" occur='?'>
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
<default>true on Windows, false on Unix.</default>

<p>Specifies whether the environment context is case sensitive or insensitive.</p>

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

</defun>
<defun title="temp-dir" occur="?" version="Resin 1.1">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
<default>Defaults to <var/WEB-INF/tmp/></default>

<p>Application temp directory.  This is the path used in
<var/javax.servlet.context.tempdir/>.</p>
</defun>

<defun title="work-dir" occur="?" version="Resin 2.0.0">
<parents>resin, server, host-default, host, web-app-default, web-app</parents>
<default>Defaults to <var/WEB-INF/work/></default>

<p>Application work directory.  This is the directory used for
generated code like JSP, XSL and EJB classes.</p>
</defun>
</section>


</document>
