<authenticator configures an authentication resource for the current environment.

Resin's servlet authentication uses an authentication resource to validate user login and to provide single-signon capability. The authenticator is configured in the environment context where it is shared. So an authenticator configured in the web-app only applies to the web-app, but an authenticator configured in the host will apply to all hosts.

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

<bean> configures a custom bean resource and stores in JNDI. <bean> is a synonym for <bean>.

Resources are beans stored in JNDI. The resources can be created from any Java class that conforms to the bean conventions. Configuration of the resource is in the <init> section. Field values may use JSP-EL expressions as well as constant strings or even complex sub-beans.

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

r_bean = element bean {
  (jndi-name?
  & mbean-name?
  & mbean-interface?
  & var?),

  (type, arg*)?,

  (init | listener)*
}

element listener {
  mbean-name,

  handback*
}

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

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

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

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

<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 xmlns="http://caucho.com/ns/resin">

<connector> configures a JCA resource adapter and its associated connection factories.

The resource adapter/connector will have been added as a rar file (see resource-deploy. The <connector> configures that rar resource.

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

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

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

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

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

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

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

  ...
}

element env-entry {
  env-entry-name,

  env-entry-type,

  env-entry-value
}

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

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

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.

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

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.

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

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.conf with the javac configuration option:

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

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

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

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

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

The log configuration describes log in detail.

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

The log configuration describes log in detail.

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

<reference> configures a JNDI ObjectFactory.

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

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

<resin:if> executes part of the configuration file conditionally.

<resin:choose> implements an if, elsif, else.

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

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

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

<resin:import> reads configuration information from another file. The target file is validated by a schema where the schema depends on the location of the resin:import.

A resin:import in <cluster> will have a target with a top-level of <server>.

<resin:import> is a key capability of the resin.conf file. User configuration files like web.xml and resin-web.xml are implemented by <resin:import>.

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

<resin:log> logs a message to the given log file. The content of the element is the message.

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

  <resin:log>Starting server \${server.name}</resin:log>
</web-app>

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

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

<resin:otherwise> is the catch-all configuration for a <resin:choose> block when none of the <resin:when> items match.

<resin:when> conditionally configures a block within a <resin:choose> block. If the test matches, Resin will use the enclosed configuration.

<resource> configures a custom bean resource and stores in JNDI. <resource> is a synonym for <bean>.

Resources are beans stored in JNDI. The resources can be created from any Java class that conforms to the bean conventions. Configuration of the resource is in the <init> section. Field values may use JSP-EL expressions as well as constant strings or even complex sub-beans.

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

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

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

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

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

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

Configures the destination for System.err.

The log configuration describes stderr-log in detail.

Configures the destination for System.out.

The log configuration describes stderr-log in detail.

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

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

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

<web-service-client> configures a proxy to a web-service. It uses a Java interface and a URL to select the web-service.

The URL is defined as: encoding:location, where location is typically a HTTP URL.

See the hello world tutorial for an example.

element web-service-client {
  jndi-name
  & url
  & interface
}

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