environment: class loaders, resources and jndi

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.

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

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

<connector connector-name="Test Resource">
  <connection-factory jndi-name="eis/test">
    <init>
      <value>b</value>
    </init>
  </connection-factory>
</connector>

element connector {
  connector-name { string }

  & resource-adapter?

  & connection-factory*
}

element connection-factory {
  jndi-name,

  type?,

  element init { any }?
}

element resource-adapter {
  jndi-name,

  element init { any }?
}

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

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

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

public class TestServlet extends HttpServlet {
  private String greeting;

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

  ...
}

element env-entry {
  (attribute env-entry-name { string } | 
   element env-entry-name { string }),

  (attribute env-entry-type { string } | 
   element env-entry-type { string }),

  (attribute env-entry-value { string } | 
   element env-entry-value { string })
}

<jndi-link>
  <jndi-name>java:comp/env/ejb/traderHome</jndi-name>
  <factory>weblogic.jndi.WLInitialContextFactory</factory>
  <init-param java.naming.provider.url="t3://localhost:7001"/>
  <foreign-name>statelessSession/TraderHome</foreign-name>
</jndi-link>

<jndi-link>
  <jndi-name>java:comp/env/ejb/MyBean</jndi-name>
  <foreign-name>/SampleBean</foreign-name>
</jndi-link>

<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 jndi-name="env/test">
  <type>test.MyBean</type>
  <init>
    <greeting>Hello</greeting>
    <server>${'${'}serverId}</server>
    <sub-bean>
      <value>${'${2'} + 2}</value>
    </sub-bean>
  </init>
</resource>

r_listener-Resource = element listener {
  r_mbean-name,

  r_handback*
}

r_resource = element resource {
  (r_jndi-name?

  & r_mbean-name?

  & r_mbean-interface?),

  (r_type,

  r_arg*)?,

  (r_init*

  & r_listener-Resource*)
}

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

  ...
</host>

element resource-deploy {
  (attribute path { string } | element path { string })

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

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

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

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

</web-app>

<authenticator> configures an authentication resource for the current environment context. The authenticator is used for login and also for the getUserPrincipal and isUserInRole methods of the HttpServletRequest object.

The authenticators are scoped to their containing environment. An authenticator defined in WEB-INF/resin-web.xml applies only to the web-app, while an authenticator defined in the <cluster> section of the resin.xml applies to the entire cluster. The <management> configuration provides an authenticator which is available to all applications.

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. 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 uri or class attribute. The class can be any custom class extending com.caucho.server.security.AbstractAuthenticator. The uri is a symbolic name for the authenticator class. More details on the predefined authenticators are in the Resin security documentation.

• properties: Java properties-style authentication.
• jaas: JAAS authentication.
• jdbc: JDBC password-based authentication.
• xml: XML JDBC password-based authentication.

Configuration of the authenticator uses bean-style configuration in the <init> tag.

See also: the Resin security section.

r_authenticator = element authenticator {
  (r_class | r_uri)
  & r_binding*
  & r_init?
  & r_jndi-name?
  & r_name?
  & r_scope?
}

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

  <authenticator uri="properties:password-digest=none">
    <init>
harry=quidditch,user
ron=cannons,user,prefect
    </init>
  </authenticator>

</web-app>

<bam-service> configures a BamService to listen for messages. The service is always a single instance.

<bam-service> can be used as a simple queueing service, replacing JMS queues and ejb-message-bean. By default the queue is consumed with a single thread. Unlike EJB message driven beans, <bam-service> uses a single instance like a servlet, not a pool of instances.

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

element ejb-message-bean {
  class
  & init?
  & name?
  & uri?
}

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

  <bam-service uri="caucho.log:">
    <name>log</name>
    <init>
      <name>test.Log<name>
    </init>
  </bam-service>

</web-app>

<bean> configures a custom singleton bean and stores in the WebBeans registry. <bean> is a primary configuration tag for Resin's IoC capabilities. The bean can also be optional registered in JNDI.

Custom configuration of the bean is in the <init> section. Field values may use JSP-EL expressions as well as constant strings or even complex sub-beans. More details for configuring singleton beans are in Resin IoC.

r_bean = element bean {
  r_class?
  & r_binding*
  & r_init?
  & r_jndi-name?
  & r_mbean-name?
  & r_mbean-interface?
  & r_name?
  & r_scope?
}

<web-app xmlns="http://caucho.com/ns/resin">
  <bean name="test">
    <type>test.MyBean</type>
    <init>
      <greeting>Hello</greeting>
      <server>${serverId}</server>
      <sub-bean>
        <value>${2 + 2}</value>
      </sub-bean>
    </init>
  </bean>
</web-app>

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

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

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

r_character-encoding = element character-encoding {
  string
}

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

</resin>

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

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

  & r_library-loader*

  & r_simple-loader*

  & r_tree-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> automatically compiles Java code into .class files before loading them.

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

<component> configures a component bean template and stores in the WebBeans registry. Injection of a <component> will generally create a new bean instance in constrast to the singleton <bean>. <component> is a primary configuration tag for Resin's IoC capabilities. The bean can also be optionally registered in JNDI.

Custom configuration of the component is in the <init> section. Field values may use JSP-EL expressions as well as constant strings or even complex sub-beans. More details for configuring singleton beans are in Resin IoC.

r_component = element component {
  r_class?
  & r_binding*
  & r_init?
  & r_jndi-name?
  & r_name?
  & r_scope?
}

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

  <component name="test">
    <type>test.MyBean</type>
    <init>
      <greeting>Hello</greeting>
      <server>${serverId}</server>
      <sub-bean>
        <value>${2 + 2}</value>
      </sub-bean>
    </init>
  </component>

</web-app>

r_connection-factory = element connection-factory {
  (r_class | r_uri)
  & r_binding*
  & r_init?
  & r_jndi-name?
  & r_name?

  & local-transaction-optimization?
  & max-active-time?
  & max-connections?
  & resource-adapter?
  & shareable?
}

<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 = 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 * { * }?
}

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

element database-default {
  r_database-Content
}

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

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

</web-app>

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

element dependency {
  string
}

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

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

element dependency-check-interval {
  string
}

<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> 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. More details are available in the Resin Messaging section.

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

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

  <jms-connection-factory uri="resin:"/>
  <jms-queue name="my_queue" uri="memory:"/>

  <ejb-message-bean class="qa.MyListener">
    <destination>${my_queue}</destination>
  </ejb-message-bean>

</web-app>

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

  <resource-adapter uri="activemq:"/>

  <ejb-message-bean class="qa.MyListener">
    <activation-spec uri="activemq:">
       <init physical-name="queue.test"/>
    </activation-spec uri="activemq:">
  </ejb-message-bean>

</web-app>

Configures an EJB server. See Resin EJB for more details.

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> configures an EJB @Stateful bean. The @Stateful bean is a single-threaded component bean suitable for transaction processing. See Resin EJB for more details.

The stateful-bean is registered in the Resin-IoC/WebBeans context and optionally with JNDI.

Since @Stateful beans are components, they are created at the request of the application and destroyed by the application. @Stateful beans are never singletons. For singleton-style beans, either use a <bean> or a @Stateless session bean.

@Stateful beans may optionally implement a SessionSynchronization interface for transaction callbacks.

element ejb-stateful-bean {
  class
  & init?
  & jndi-name?
  & name?
  & scope?
}

<ejb-stateless-bean> configures an EJB @Stateless bean. The @Statelesss bean is a pooled, proxied, singleton component bean suitable. See Resin EJB for more details.

The stateless-bean is registered in the Resin-IoC/WebBeans context and optionally with JNDI.

@Stateless beans are similar to <bean> singletons, but pool instances. Each instance executes a single thread at a time, unlike <bean> singletons which are multithreaded like servlets. Both styles can use the same aspect capabilities like dependency injection, transactions, and interceptors. Because @Stateless beans are singletons, they do not have a scope attribute.

element ejb-stateless-bean {
  class
  & init?
  & jndi-name?
  & name?
}

<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. As with other Resin configuration, the value can use JSP-EL expressions.

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.

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

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

element fileset {
  dir
  & exclude*
  & include*

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

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

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

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

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

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

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

The eclipse compiler requires the presence of $RESIN_HOME/lib/eclipse-compiler.jar (which is included with Resin). It is a very fast compiler that was developed as part of the Eclipse project.

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

 <javac compiler="eclipse" args="-source 1.5"/>

  ...

</resin>

The internal compiler 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.

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

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

</resin>

The javac compiler is included with the JDK. It executes that same 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:

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

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

  ...

</resin>

<jms-connection-factory> configures a JMS ConnectionFactory and registers it with Resin-IoC/WebBeans. The ConnectionFactory can be specified by it's class or a URI alias.

See Resin messaging for more information.

element jms-connection-factory {
  (class | uri)
  & init?
  & jndi-name?
  & name?
}

<jms-queue> configures a JMS Queue and registers it with Resin-IoC/WebBeans. Resin's JMS Queues implement the BlockingQueue interface and can be used directly or with the JMS ConnectionFactory.

See Resin messaging for more information.

The Queue can either be identified by the implementing class name or with a URI alias. Third-party queues using JCA will use the <resource-adapter> and either <connection-factory> or <activation-spec>.

Code sending messages to a Queue will typically use either the BlockingQueue API or JMS. Code receiving from a queue will generally use an EJB message bean.

element jms-queue {
  (class | uri)
  & init
  & jndi-name
  & name
}

<jms-topic> configures a JMS Topic and registers it with Resin-IoC/WebBeans. Resin's JMS Topics implement the BlockingTopic interface and can be used directly or with the JMS ConnectionFactory.

See Resin messaging for more information.

The Topic can either be identified by the implementing class name or with a URI alias. Third-party topics using JCA will use the <resource-adapter> and either <connection-factory> or <activation-spec>.

Code sending messages to a Topic will typically use either the BlockingTopic API or JMS. Code receiving from a topic will generally use an EJB message bean.

element jms-topic {
  (class | uri)
  & init
  & jndi-name
  & name
}

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

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

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

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

<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> configures JPA persistence defaults. More details on JPA are available on the Amber page.

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

element library-loader {
  fileset
  | path
}

element fileset {
  dir
  & exclude*
  & include*
}

See DirectoryLoader.

<log> configures JDK 1.4 java.util.logger handler.

The log configuration describes log in detail.

element log {
  archive-format?
  & format?
  & formatter?
  & handler?
  & level?
  & mbean-name?
  & name
  & path?
  & path-format?
  & rollover-count?
  & rollover-period?
  & rollover-size?
  & timestamp?
  & use-parent-handlers?
}

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

The log configuration describes log in detail.

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

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

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

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

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

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

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

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

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.

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

element resin:when {
  attribute test { string },

  context-dependent content
}

element resin:otherwise {
  context-dependent content
}

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

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

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

element resin:when {
  attribute test { string },

  context-dependent content
}

element resin:otherwise {
  context-dependent content
}

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.

element resin:if {
  attribute test { string }

  context-dependent content
}

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

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.

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

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

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

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

element resin:message {
  string
}

<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 adds an EL variable to the current context.

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

<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> is an obsolete synonym for <bean> to define custom singletons. Applications should use the <bean> syntax instead.

<resource-adapter> configures a JCA ResourceAdapter in combination with <connection-factory> for connections or <activation-spec for message listeners. See Resin messaging for typical uses.

ResourceAdapters can be deployed in .rar files, but this is not required by Resin. Instead, you can configure the ResourceAdapter directly.

A symbolic URI can be used in place of the ResourceAdapter's class name.

element resource-adapter {
  (class | uri)
  & init?
  & name?
  & jndi-name?
}

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

element resource-deploy {
  path
  & expand-directory?
  & expand-path?
  & resource-default?
}

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

    <host id="">
      <resource-deploy path="deploy"/>
    </host>
  </cluster>
</resin>

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

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

<scheduled-task> schedules a job to be executed at specific times or after specific delays. The times can be specified by a cron syntax or by a simple delay parameter. The job can be either a Runnable bean, a method specified by an EL expression, or a URL.

When specified as an IoC bean, the bean task has full IoC capabilities, including injection, @TransactionAttribute aspects, interception and @Observes.

element scheduled-task {
  class?
  & cron?
  & delay?
  & init?
  & mbean-name?
  & method?
  & name?
  & period?
  & task?
}

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

  <scheduled-task class="qa.MyTask">
    <cron>*/5</cron>
  </scheduled-task>

</web-app>

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

  <scheduled-task task="#{taskBean}">
    <cron>0 0 *</cron>
  </scheduled-task>

</web-app>

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

  <bean name="myBean" class="qa.MyBean"/>

  <scheduled-task method="#{myBean.myMethod}">
    <delay>10m</delay>
    <period>1h</period>
  </scheduled-task>

</web-app>

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

  <scheduled-task url="/cron.php">
    <cron>0 15 * * 0</cron>
  </scheduled-task>

</web-app>

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.

element servlet-hack {
  boolean
}

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

element simple-loader {
  path
  & prefix?
}

Configures the destination for System.err.

The log configuration describes stderr-log in detail.

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

Configures the destination for System.out.

The log configuration describes stderr-log in detail.

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

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

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

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

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

element temp-dir {
  string
}

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

element tree-loader {
  path
}

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

element work-dir {
  string
}