Environment: Class Loaders, Resources and JNDIResin 3.0
Resin 3.0

Features
Installation
Configuration
Web Applications
IOC/AOP
Resources
JSP
Quercus
Servlets and Filters
Databases
Admin (JMX)
CMP
EJB
Amber
EJB 3.0
Security
XML and XSLT
XTP
JMS
Performance
Protocols
Third-party
Troubleshooting/FAQ

index
howto
resin.conf
env
web-app
log
el control
Bean Config
Common Tasks
Relax Schema
Config FAQ
Scrapbook
resin.conf
Configuration
web-app

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.

  1. Classloaders
    1. class-loader
    2. compiling-loader
    3. library-loader
    4. tree-loader
    5. make-loader
    6. servlet-hack
    7. simple-loader
  2. Clustering
    1. cluster
    2. cluster-definition
  3. Resources
    1. connector
    2. database
    3. ejb-server
    4. env-entry
    5. jndi-link
    6. reference
    7. resource
    8. resource-deploy
    9. resource-ref
  4. Logging
    1. log
    2. stderr-log
    3. stdout-log
  5. Authenticator
    1. authenticator
  6. Miscellaneous
    1. system-property
    2. javac
    3. dependency
    4. dependency-check-interval
    5. character-encoding
    6. case-insensitive
    7. temp-dir
    8. work-dir

Classloaders

class-loader

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

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>
  <class-loader>
    <compiling-loader path="WEB-INF/classes"/>

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

compiling-loader

Resin 3.0

child of: class-loader

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

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

AttributeMeaningdefault
argsAdditional arguments to be passed to the Java compiler. Resin 3.0none
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.0none
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

library-loader

Resin 3.0

child of: class-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.

AttributeMeaningdefault
pathFilesystem path for the class loader. Since Resin 3.0required
See class com.caucho.loader.DirectoryLoader .

tree-loader

Resin 3.0

child of: class-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.

AttributeMeaningdefault
pathFilesystem path for the class loader. Since Resin 3.0required
See class com.caucho.loader.TreeLoader .

make-loader

Resin 3.0

child of: class-loader

Configures a custom make-style loader.

servlet-hack

Resin 3.0

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.

simple-loader

Resin 3.0

child of: class-loader

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

AttributeMeaningdefault
pathFilesystem path for the class loader. Since Resin 3.0required
prefixClass package prefix to only load to a subset of classes. Resin 3.0none

Clustering

cluster

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

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.

AttributeMeaningdefault
ididentifies the cluster for later reference. Since Resin 3.0none
srunconfigures the srun port and protocol for a cluster server. Since Resin 3.0none
cluster-groupspecialized configuration for sub-clusters. Since Resin 3.0none
cluster-refan identifier for a previous cluster-definition to use for the cluster. Since Resin 3.0none

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

cluster-definition

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

Defines a cluster for later use by cluster-ref.

AttributeMeaningdefault
ididentifies the cluster for later reference. Since Resin 3.0required
srunconfigures the srun port and protocol for a cluster server. Since Resin 3.0none
cluster-groupspecialized configuration for sub-clusters. Since Resin 3.0none

Resources

connector

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

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 Example
<connector connector-name="Test Resource">
  <connection-factory jndi-name="eis/test">
    <init>
      <value>b</value>
    </init>
  </connection-factory>
</connector>

AttributeMeaningdefault
connectorConfigures a connectorrequired
connector-nameSpecifies the rar connector's display-namerequired
resource-adapterConfigures the resource-adapteroptional
connection-factoryConfigures a connection-factoryoptional
jndi-nameJNDI name for a resource-adapter or connection-factoryrequired
typeFor connectors with multiple connection-factories, specifies the connection-factoryoptional
local-transaction-optimizationEnables the local transaction optimization. Resin 3.0.7true
initBean-style initializationoptional
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 }?
}

database

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

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.

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

ejb-server

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

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

env-entry

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

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.

AttributeMeaningdefault
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

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 resin.conf fragment
<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.

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

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

jndi-link

Resin 1.2

child of: resin, server, host-default, host, web-app-default, web-app

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.

AttributeMeaningdefault
jndi-nameThe JNDI name where the foreign context should be linked. Resin 3.0required
factoryClass name of the JNDI InitialContextFactory. Since Resin 1.2optional
foreign-nameSub-context of the foreign JNDI context. Since Resin 1.2none
init-paramConfiguration parameters for the JNDI environment passed to InitialContextFactory. Since Resin 1.2none

Linking a WebLogic EJB client bean
<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>

A JNDI symbolic link EJB client bean
<jndi-link>
  <jndi-name>java:comp/env/ejb/MyBean</jndi-name>
  <foreign-name>/SampleBean</foreign-name>
</jndi-link>

reference

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

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.

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

resource

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

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.

AttributeMeaningdefault
jndi-nameJNDI name for the resource. Since Resin 3.0required
typeBean class implementing the resource. Since Resin 3.0required
argArguments to the resource's constructor. Since Resin 3.0optional
mbean-nameJMX name for management registration. Resin 3.0optional
initBean-style initialization for the beanoptional
listenerRegisters the bean as a listener for a JMX emitter. Resin 3.0optional
local-transaction-optimizationEnables the local transaction optimization. Resin 3.0.7true

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

resource-deploy

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app

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.

example resource-deploy
<host>
  <resource-deploy path="deploy"/>

  ...
</host>

AttributeMeaningdefault
resource-deployConfigures .rar deploymentrequired
pathConfigures the path where users will place .rar filesrequired
expand-pathConfigures the directory where Resin will expand rar filesthe path value
schema
element resource-deploy {
  (attribute path { string } | element path { string })

  & (attribute expand-path { string } | element expand-path { string })?
}

resource-ref

Servlet 2.2

child of: resin, server, host-default, host, web-app-default, web-app

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.

Logging

log

child of: resin, server, host-default, host, web-app-default, web-app

Configures JDK 1.4 java.util.logger logging.

The log configuration describes log in detail.

stderr-log

child of: resin, server, host-default, host, web-app-default, web-app

Configures the destination for System.err.

The log configuration describes stderr-log in detail.

stdout-log

child of: resin, server, host-default, host, web-app-default, web-app

Configures the destination for System.out.

The log configuration describes stderr-log in detail.

Authenticator

authenticator

child of: resin, server, host-default, host, web-app-default, web-app, login-config

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.

AttributeMeaningdefault
jndi-nameThe JNDI name where the authenticator is stored. Since Resin 3.0java:comp/env/caucho/auth
typeThe implementing class for the authenticator. Since Resin 3.0required
initA bean-style configuration section. Since Resin 3.0none

Miscellaneous

system-property

Resin 2.0

child of: resin, server, host-default, host, web-app-default, web-app

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

<resin>
  <system-property foo="bar"/>
</resin>

javac

child of: resin, server, host-default, host, web-app-default, web-app

Configures the Java compiler for automatically compiled files.

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

AttributeMeaningdefault
compilerConfigures the Java compiler to use. Since Resin 3.0internal
argsAny additional arguments for the compiler. Since Resin 3.0none
encodingAny encoding valued for the compiler. Since Resin 3.0none

dependency

Resin 3.0.1

child of: resin, server, host-default, host, web-app-default, web-app

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

AttributeMeaningdefault
pathFilesystem path to the dependent file. Since Resin 3.0required

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

dependency-check-interval

Resin 3.0

child of: resin, server, host-default, host, web-app-default, web-app
default: 2s

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.

character-encoding

Resin 1.1

child of: resin, server, host-default, host, web-app-default, web-app
default: The default value is ISO-8859-1.

Specifies the default character encoding for the environment.

<web-app id='/'>
  <character-encoding>shift_jis</character-encoding>
  ...

</web-app>

case-insensitive

child of: resin, server, host-default, host, web-app-default, web-app
default: true on Windows, false on Unix.

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.

temp-dir

Resin 1.1

child of: resin, server, host-default, host, web-app-default, web-app
default: Defaults to WEB-INF/tmp

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

work-dir

Resin 2.0.0

child of: resin, server, host-default, host, web-app-default, web-app
default: Defaults to WEB-INF/work

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


resin.conf
Configuration
web-app
Copyright © 1998-2006 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.