resources: class loaders, environment and ioc

Environment tags configure class-loaders, logging, authentication and resources like databases, JMS queues, EJB servers, and web service clients. Many of the resources are stored in JNDI or in EL variables for later assembly.

Any environment resource can appear in any of Resin environments: <resin>, <cluster>, <host> and <web-app>. Resources configured at parent levels are shared among all children, so a database can share connection pools for all web-apps or an authenticator can provide single-signon.

<authenticator>

child of cluster,host,web-app

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

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

XmlAuthenticator in resin-web.xml

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

<bean>

child of cluster,host,web-app

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

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

MyBean in resin-web.xml

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

<case-insensitive>

child of resin,cluster,host,web-app

default true on Windows, false on Unix.

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

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

<case-insensitive> schema

r_case-insensitive = element case-insensitive {
  r_boolean-Type
}

<character-encoding>

child of resin,cluster,host,web-app

default The default value is ISO-8859-1.

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

<character-encoding> schema

r_character-encoding = element character-encoding {
  string
}

Example: utf-8 as default character encoding

<resin xmlns="http://caucho.com/ns/resin">
  <character-encoding>utf-8</character-encoding>
  ...

</resin>

<class-loader>

child of resin,cluster,host,web-app

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

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

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

<class-loader> Attributes
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.

<class-loader> schema

r_class-loader = element class-loader {
  r_compiling-loader*

  & r_library-loader*

  & r_simple-loader*

  & r_tree-loader*
}

Example: WEB-INF/resin-web.xml defined <class-loader>

<web-app xmlns="http://caucho.com/ns/resin">
  <prologue>
    <class-loader>
      <compiling-loader path="WEB-INF/classes"/>

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

<compiling-loader>

child of class-loader

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

<compiling-loader> Attributes
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

Example: WEB-INF/resin-web.xml <compiling-loader>

<web-app xmlns="http://caucho.com/ns/resin">
  <prologue>
    <class-loader>
      <compiling-loader path="WEB-INF/classes"
                        source="WEB-INF/src"/>
    </class-loader>
  </prologue>
</web-app>

<database>

child of resin,cluster,host,web-app

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

<database> Attributes
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> schema

database = element database {
  backup-driver*
  & close-dangling-connections?
  & connection?
  & connection-wait-time?
  & driver+
  & jndi-name?
  & max-active-time?
  & max-close-statements?
  & max-connections?
  & max-create-connections?
  & max-idle-count?
  & max-idle-time?
  & max-overflow-connections?
  & max-pool-time?
  & name?
  & password?
  & ping?
  & ping-interval?
  & ping-query?
  & ping-table?
  & prepared-statement-cache-size?
  & save-allocation-stack-trace?
  & spy?
  & transaction-timeout?
  & user?
  & wrap-statements?
  & xa?
  & xa-forbid-same-rm?
}

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

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

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

Example: WEB-INF/resin-web.xml database

<web-app xmlns="http://caucho.com/ns/resin">

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

</web-app>

<database-default>

child of resin,cluster,host,web-app

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

<database-default> schema

element database-default {
  r_database-Content
}

Example: WEB-INF/resin-web.xml idle-time defaults

<web-app xmlns="http://caucho.com/ns/resin">

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

</web-app>

<dependency>

child of resin,cluster,host,web-app

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

<dependency> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
path	Filesystem path to the dependent file. Since Resin 3.0	required

<dependency> schema

element dependency {
  string
}

Example: struts dependency

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

<dependency-check-interval>

child of resin,cluster,host,web-app

default 2s

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

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

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

<dependency-check-interval> schema

element dependency-check-interval {
  string
}

Example: deployment dependency-check-interval

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">
    <dependency-check-interval>1h<dependency-check-interval>

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

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

<ejb-message-bean>

child of resin,cluster,host,web-app

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

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

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

<ejb-message-bean> Attributes
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

<ejb-message-bean> schema

element ejb-message-bean {
  class
  & init?
  & (activation-spec?
     | (destination?
        & destination-type?
        & destination-name?
        & message-consumer-max?)
    )
}

<ejb-server>

child of resin,cluster,host,web-app

Configures an EJB server.

<ejb-server> Attributes
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

<ejb-server> schema

element ejb-server {
  auto-compile
  & create-database-schema
  & data-source
  & config-directory
  & ejb-descriptor
  & ejb-jar
  & jndi-prefix
  & validate-database-schema
  & jms-connection-factory
  & xa-data-source
}

<ejb-stateful-bean>

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

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

Stateful bean in resin-web.xml

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

  <mypkg:MyBean>
    <ee:Stateful/>

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

</web-app>

<ejb-stateless-bean>

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

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

Stateless bean in resin-web.xml

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

  <mypkg:MyBean>
    <ee:Stateless/>

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

</web-app>

<env-entry>

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

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

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

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

<env-entry> Attributes
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

<env-entry> schema

element env-entry {
  description*,

  env-entry-name,

  env-entry-type,

  env-entry-value
}

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

Example: WEB-INF/resin-web.xml with env-entry

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

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

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

Example: GreetingServlet.java

import java.io.*;
import javax.naming.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class TestServlet extends HttpServlet {
  private String greeting;

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

  ...
}

<fileset>

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

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

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

<fileset> schema

element fileset {
  dir
  & exclude*
  & include*

Matching jars in WEB-INF/lib (non-recursive)

<fileset dir="WEB-INF/lib">
  <include name="*.jar"/>
</fileset>

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

Matching jars in WEB-INF/lib (recursive)

<fileset dir="WEB-INF/tree">
  <include name="**/*.jar"/>
</fileset>

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

<javac>

child of resin,cluster,host,web-app

default internal

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

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

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

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

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

<javac> schema

element javac {
  args*
  & compiler
  & encoding?
  & max-batch?
}

Internal compiler

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

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

</resin>

javac JDK compiler

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

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

  ...

</resin>

<jndi-link>

child of resin,cluster,host,web-app

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

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

<jndi-link> Attributes
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

<jndi-link> schema

element jndi-link {
  jndi-name
  & factory?
  & foreign-name?
  & init-param*
}

Example: A JNDI symbolic link for a DataSource

<web-app xmlns="http://caucho.com/ns/resin"dd>
  <database jndi-name="jdbc/oracle">
    ...
  </database>

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

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

Example: A JNDI foreign context for all EJB

<web-app xmlns="http://caucho.com/ns/resin">
  <jndi-link jndi-name='java:comp/env/ejb'>
    <factory>com.caucho.ejb.hessian.HessianContextFactory</factory>
    <init-param java.naming.provider.url='http://ejb.hogwarts.com:80/hessian'/>
  </jndi-link>
</web-app>

Example: A JNDI foreign context for selected EJB

<web-app xmlns="http://caucho.com/ns/resin">
  <jndi-link jndi-name='java:comp/env/remote-ejb'>
    <factory>com.caucho.ejb.hessian.HessianContextFactory</factory>
    <init-param java.naming.provider.url='http://ejb.hogwarts.com:80/hessian'/>
  </jndi-link>

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

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

<jpa-persistence>

child of resin,cluster,host,web-app

<jpa-persistence> Attributes
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

<jpa-persistence> schema

element jpa-persistence {
  create-database-schema?
  & cache-size?
  & cache-timeout?
  & data-source?
  & jdbc-isolation?
  & persistence-unit*
  & persistence-unit-default*
  & read-data-source?
  & validate-database-schema?
  & xa-data-source?
}

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

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

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

<library-loader>

child of class-loader

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

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

See DirectoryLoader.

<library-loader> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
fileset	An ant-style fileset
path	Filesystem path for the class loader. Since Resin 3.0	required

<library-loader> schema

element library-loader {
  fileset
  | path
}

element fileset {
  dir
  & exclude*
  & include*
}

<logger>

child of resin,cluster,host,web-app

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

The log configuration describes log in detail.

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

<logger> schema

element logger {
  name
  & level?
  & use-parent-handlers?
}

Example: compilation logging

<resin xmlns="http://caucho.com/ns/resin">
  <log name="" level="all" path="log/debug.log"/>
  <logger name="com.caucho.java" level="fine"/>

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

Example: logging to a JMS queue

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

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

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

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

</web-app>

<mail>

child of resin,cluster,host,web-app

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

<mail> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
authenticator	sets a custom javamail authenticator, either with EL or a custom resin:type bean
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
password	sets the password for authentication
pop3-host	sets the mail.pop3.host property
pop3-port	sets the mail.pop3.port property
pop3-user	sets the mail.pop3.user property
properties	general mail properties in property file format
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

<mail> schema

element mail {
  authenticator?
  & debug?
  & from?
  & host?
  & imap-host?
  & imap-port?
  & imap-user?
  & init?
  & jndi-name?
  & name?
  & pop3-host?
  & pop3-port?
  & pop3-user?
  & smtp-host?
  & smtp-port?
  & smtp-user?
  & store-protocol?
  & transport-protocol?
  & user?
}

Example: mail

<web-app xmlns="http://caucho.com/ns/resin">

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

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

<reference>

child of resin,cluster,host,web-app

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

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

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

<reference> schema

element reference {
  factory 
  & jndi-name
  & init-param*
}

Example: Hessian client reference

<web-app xmlns="http://caucho.com/ns/resin">

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

</web-app>

<remote-client>

child of cluster,host,web-app

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

<remote-client> Attributes
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

remote-client protocols
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.

remote-client

element remote-client {
  (class|uri)
  & name?
  & jndi-name?
  & interface
}

<resin:choose>

resin:choose implements an if, elsif, else.

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

<resin:choose> Attributes
ATTRIBUTE	DESCRIPTION
resin:when	A configuration section executed when matching a test condition
resin:otherwise	A fallback section executed when the tests fail

<resin:choose> schema

element resin:choose {
  resin:when*,
  resin:otherwise
}

element resin:when {
  attribute test { string },

  context-dependent content
}

element resin:otherwise {
  context-dependent content
}

Example: resin:choose usage pattern

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

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

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

<resin:if>

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

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

<resin:if> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
test	the test to perform	required

<resin:if> schema

element resin:if {
  attribute test { string }

  context-dependent content
}

Example: enable debugging for -Ddevelopment

<resin xmlns="http://caucho.com/ns/resin"
        xmlns:core="http://caucho.com/ns/resin/core">

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

  ...
</resin>

<resin:import>

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

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

<resin:import> Attributes
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

<resin:import> schema

element import {
  (path | fileset)
  & optional?
}

element fileset {
  dir
  & exclude*
  & include*
}

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

Example: import implementation of WEB-INF/web.xml

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

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

  </cluster>
</resin>

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

Example: adding host.xml in host-deploy

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

    <host-deploy path="/var/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.

Example: Bean IoC fileset in resin-web.xml

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:core="http://caucho.com/ns/resin/core">

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

</web-app>

<resin:message>

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

<resin:message> schema

element resin:message {
  string
}

logging in resin-web.xml

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core">

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

</web-app>

<resin:set>

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

<resin:set> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
var	name of the variable to set	required
value	value	required

<resin:set> schema

element set {
  name
  & value
  & default
  & attribute * { string }
}

Example: resin:set in resin.xml

<resin xmlns="http://caucho.com/ns/resin"
          xmlns:resin="http://caucho.com/ns/resin/core">
  <resin:set name="root" value="/var/www"/>

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

    ...
  </cluster>
</resin>

<resource>

child of resin,cluster,host,web-app

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

<resource-ref>

child of resin,cluster,host,web-app

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

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

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

<resource-ref> schema

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

<scheduled-task>

child of web-app

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

ScheduledTask in resin-web.xml

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

  <resin:ScheduleTask>
    <cron>* * 23 * *</cron>
    
    <task>
      <mypkg:MyBean/>
    </task>
  </resin:ScheduleTask>
  
</web-app>

<servlet-hack>

child of class-loader

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

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

<servlet-hack> schema

element servlet-hack {
  boolean
}

<simple-loader>

child of class-loader

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

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

<simple-loader> Attributes
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

<simple-loader> schema

element simple-loader {
  path
  & prefix?
}

<stderr-log>

child of resin,cluster,host-default,host,web-app-default,web-app

Configures the destination for System.err.

The log configuration describes stderr-log in detail.

<stderr-log> Attributes
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

<stderr-log> schema

element stderr-log {
  (path | path-format)
  & archive-format?
  & rollover-period?
  & rollover-size?
  & rollover-count?
  & timestamp?
}

<stdout-log>

child of resin,cluster,host-default,host,web-app-default,web-app

Configures the destination for System.out.

The log configuration describes stderr-log in detail.

<stdout-log> Attributes
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

<stdout-log> schema

element stdout-log {
  (path | path-format)
  & archive-format?
  & rollover-period?
  & rollover-size?
  & rollover-count?
  & timestamp?
}

<system-property>

child of resin,cluster,host,web-app

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

<system-property> schema

element system-property {
  attribute * { string }+
}

Example: setting system property

<resin xmlns="http://caucho.com/ns/resin">
  <system-property foo="bar"/>
</resin>

<temp-dir>

child of resin,cluster,host-default,host,web-app-default,web-app

default Defaults to WEB-INF/tmp

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

<temp-dir> schema

element temp-dir {
  string
}

<tree-loader>

child of class-loader

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

<tree-loader> Attributes
ATTRIBUTE	DESCRIPTION	DEFAULT
path	Filesystem path for the class loader. Since Resin 3.0	required

<tree-loader> schema

element tree-loader {
  path
}

<work-dir>

child of resin,config,host,web-app

default Defaults to WEB-INF/work

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

<work-dir> schema

element work-dir {
  string
}