Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


 

Resin Documentation

home company blog docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

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>

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>

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:Jndi="java:comp/env/my-name">
    <my-attribute>my-value</my-attribute>
  </mypkg:MyBean>
  ...
</web-app>  

<case-insensitive>

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>

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>

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

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

<compiling-loader> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
argsAdditional arguments to be passed to the Java compiler. Resin 3.0
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.0
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
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>

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

<database> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
backup-driverConfigures a backup database driver. If Resin can't connect to any of the main drivers, it will use one of the. backups
close-dangling-connectionsIf an application does not close a Connection by the end of the request, Resin will close it automatically an issue a warning.true
commit-on-timeouttrue to commit the transaction on timeout, false to rollbackfalse
<connection>Defines initialization attributes for new connections, e.g. setting the transaction-isolation.true
connection-wait-timeWhen max-connections has been reached, how long Resin will wait for a connection to become idle before giving up.10min
driverConfigures the database driver, giving the driver's class name as well as its JDBC URL and any other configuration.required
jndi-nameThe JNDI name to register the connection's DataSource under. The name can be relative to java:comp/env.
max-active-timeThe maximum time Resin will allow a connection to remain open before forcing a close.6h
max-close-statementsThe maximum number of Statements Resin will hold to automatically close when the Connection closes.256
max-connectionsThe maximum number of Connections allowed.128
max-create-connectionsThe maximum number of connection creation allowed at one time.5
max-idle-countThe maximum number of Connections in the idle pool.1024
max-idle-timeThe maximum time a connection will spend in the idle pool before closing.30s
max-overflow-connectionsThe number of extra connection creation if the number of connections exceeds to pool size.0
max-pool-timeThe total time a connection can be used before it is automatically closed instead of returned to the idle pool.24h
nameThe IoC name to save the ConnectionFactory as, used with @Named to inject the resource.
passwordThe JDBC password for the connection.
pingIf true, Resin will ping the database before returning a connection from the pool (if ping-interval is exceeded).false
ping-intervalHow often an idle connection should ping the database to ensure it is still valid.1s
ping-queryA custom query used to ping the database connection.
ping-tableA table used to ping the database connection.
prepared-statement-cache-sizeHow many PreparedStatements to save in the prepared statement cache.0
save-allocation-stack-traceIf true, saves the location of the connection allocation as a stack trace.false
spyEnables spy logging of database statements. The logging occurs with name="com.caucho.sql" and level="fine".false
transaction-timeoutSets the transaction timeout.none
userSets the authentication user.
wrap-statementsIf true, Resin wraps statements and automatically closes them on connection close.true
xaEnables 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-rmWorkaround 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?
  & commit-on-timeout?
  & 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>

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

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

<dependency> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
pathFilesystem path to the dependent file. Since Resin 3.0required
<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>

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>

<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
ATTRIBUTEDESCRIPTIONDEFAULT
activation-specConfigures a custom message-listener driver
classClassname of the listener beanrequired
destinationQueue or Topic for JMS message receiving
destination-typejavax.jms.Queue or javax.jms.Topic
initIoC configuration for the listener bean
message-consumer-maxThe 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>

Configures an EJB server.

<ejb-server> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
auto-compileenables auto-compilation of EJB stubs and skeletonstrue
create-database-schemaenables JPA auto-creation of missing database tablesfalse
data-sourcespecifies the default database for JPA
config-directoryspecifies a directory containing *.ejb configuration files
ejb-descriptorpath to a *.ejb file to load
ejb-jarpath to a jar file containing a META-INF/ejb-jar.xml with EJBs
jndi-prefixprefix for JNDI registration of EJBs
validate-database-schemaverifies the actual database tables against the JPA definitionstrue
jms-connection-factoryspecifies the default JMS ConnectionFactory for message beans
xa-data-sourcespecifies a separate database for transactionsdata-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>

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

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

<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
ATTRIBUTEDESCRIPTIONDEFAULT
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
<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
ATTRIBUTEDESCRIPTIONDEFAULT
dirthe starting directoryrequired
includean include patterndo not include all files
excludean exclude patterndo 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>

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
ATTRIBUTEDESCRIPTIONDEFAULT
argsextra arguments to pass to the compiler
compilerthe compiler name: eclipse, internal, or a command-line
encodingthe character encoding to useutf-8
max-batchthe maximum number of source files to batch into one compilation64
<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>

<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
ATTRIBUTEDESCRIPTIONDEFAULT
factoryClass name of the JNDI InitialContextFactory. Since Resin 1.2optional
foreign-nameThe target name of the symbolic link, or the sub-context of the foreign JNDI context. Since Resin 1.2none
init-paramConfiguration parameters for the JNDI environment passed to InitialContextFactory. Since Resin 1.2none
jndi-nameThe JNDI name to use for the link. Resin 3.0required
<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>

<jpa-persistence> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
create-database-schemaIf true, Amber will automatically create the database schemafalse
cache-sizeSize of the entity cache32k
data-sourcedatabase used for JTA
jdbc-isolationJDBC isolation level used for connections
read-data-sourceData source to be used for read-only queriesdata-source
validate-database-schemaenables validation of the database tables on startupfalse
xa-data-sourcedatabase to use in transactionsdata-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>

<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
ATTRIBUTEDESCRIPTIONDEFAULT
filesetAn ant-style fileset
pathFilesystem path for the class loader. Since Resin 3.0required
<library-loader> schema
element library-loader {
  fileset
  | path
}

element fileset {
  dir
  & exclude*
  & include*
}

<logger>

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

The log configuration describes log in detail.

<logger> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
levelthe java.util.logging level: finest, finer, fine, config, info, warning, severeinfo
namethe java.util.logging name, typically a classnamerequired
use-parent-handlersif true, parent handlers are also invokedtrue
<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>

<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
ATTRIBUTEDESCRIPTIONDEFAULT
authenticatorsets a custom javamail authenticator, either with EL or a custom resin:type bean
debugsets the mail.debug flag
fromsets the mail.from property
hostsets the mail.host property
imap-hostsets the mail.imap.host property
imap-portsets the mail.imap.port property
imap-usersets the mail.imap.user property
initIoC configuration for other properties
jndi-nameJNDI name to store the mail Session
nameResin-IoC/WebBeans @Named value
passwordsets the password for authentication
pop3-hostsets the mail.pop3.host property
pop3-portsets the mail.pop3.port property
pop3-usersets the mail.pop3.user property
propertiesgeneral mail properties in property file format
smtp-hostsets the mail.smtp.host property
smtp-portsets the mail.smtp.port property
smtp-usersets the mail.smtp.user property
store-protocolsets the mail.store.protocol property
transport-protocolsets the mail.transport.protocol property
usersets 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>

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

<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.
<remote-client> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
classClass name of the protocol implementationrequired (or uri)
initIoC initialization for the protocol implementation
name@Named binding for Resin-IoC
jndi-nameJNDI binding name
uriShortcut alias name for the protocol class
remote-client protocols
URIDESCRIPTION
cxf:url=http://foo.com/hello/cxfDefines a cxf service. See http://wiki.caucho.com/CXF for more information.
burlap:url=http://foo.com/hello/burlapDefines a burlap service at http://foo.com/hello/burlap
hessian:url=http://foo.com/hello/hessianDefines a hessian service at http://foo.com/hello/hessian
xfire:url=http://foo.com/hello/cxfDefines 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
ATTRIBUTEDESCRIPTION
resin:whenA configuration section executed when matching a test condition
resin:otherwiseA 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
ATTRIBUTEDESCRIPTIONDEFAULT
testthe test to performrequired
<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
ATTRIBUTEDESCRIPTIONDEFAULT
patha path to a fileeither path or fileset is required
fileseta fileset describing all the files to import.either path or fileset is required
optionalif true, no error when file does not existfalse
<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/resin/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
ATTRIBUTEDESCRIPTIONDEFAULT
varname of the variable to setrequired
valuevaluerequired
<resin:set> schema
element set {
  var
  & 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 var="root" value="/var/resin"/>

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

    ...
  </cluster>
</resin>

<resource>

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

<resource-ref>

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

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>

<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
ATTRIBUTEDESCRIPTIONDEFAULT
pathFilesystem path for the class loader. Since Resin 3.0required
prefixClass package prefix to only load to a subset of classes. Resin 3.0none
<simple-loader> schema
element simple-loader {
  path
  & prefix?
}

<stderr-log>

Configures the destination for System.err.

The log configuration describes stderr-log in detail.

<stderr-log> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
archive-formatdefines a format string for log rollover
pathsets the VFS path for the log file
path-formatsets a pattern for creating the VFS path for the messages
rollover-countsets the maximum number of rollover files
rollover-periodsets the number of days before a log file rollover 1m
rollover-sizesets the maximum log size before a rollover1g
timestampsets 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>

Configures the destination for System.out.

The log configuration describes stderr-log in detail.

<stdout-log> Attributes
ATTRIBUTEDESCRIPTIONDEFAULT
archive-formatdefines a format string for log rollover
pathsets the VFS path for the log file
path-formatsets a pattern for creating the VFS path for the messages
rollover-countsets the maximum number of rollover files
rollover-periodsets the number of days before a log file rollover 1m
rollover-sizesets the maximum log size before a rollover1g
timestampsets 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>

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>

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>

<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
ATTRIBUTEDESCRIPTIONDEFAULT
pathFilesystem path for the class loader. Since Resin 3.0required
<tree-loader> schema
element tree-loader {
  path
}

<work-dir>

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
}

Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.