Resin's configuration files support JSP EL expressions in several contexts, basic control structures for conditional processing, and several useful functions.

Environment Variables

Each Environment in Resin has an associated set of EL objects and functions. The EL Environment is inherited, the objects available in host are also available in web-app.

<host regexp="www.([^.]+).com">
  <root-directory>/opt/www/${'${'}host.regexp[1]}</root-directory>

  <context-param server-id="${'${'}server.name}"/>

  <web-app id="/">
    <document-directory>webapps/ROOT</document-directory>
  </web-app>
</host>

Servlet/Filter bean-style initialization

EL expressions can be used to configure servlets and filters. init-param values can use JSP EL expressions, including the ability to use system properties.

Servlets, filters, and resources can be configured like beans with setter methods are called directly (See Bean-style init).

One example use use for the bean-style servlet initialization is to avoid JNDI lookup inside the servlet code. For example, a servlet that that uses a JDBC DataSource might look like:

package test;

...

public class TestServlet extends HttpServlet {
  private DataSource _dataSource;

  /**
   * Bean setter is called to configure the servlet
   * before the init() method.
   */
  public void setDataSource(DataSource dataSource)
  {
    _dataSource = dataSource;
  }

  ...
}

The servlet is configured as follows:

<web-app>
  <allow-servlet-el/>

  <servlet servlet-name='test'
           servlet-class='test.TestServlet'>
    <init>
      <data-source>${'${'}jndi:lookup("java:comp/env/jdbc/test")}</data-source>
    </init>
  </servlet>

  ...
</web-app>

The %lt;data-source%gt; xml tag corresponds to the setDataSource method of the bean. More infomation on this powerful pattern is in the Bean-style init section of the documentation.

Control Structures

The resin.conf and web.xml configuration files can use control structures. The syntax of the control structures is deliberately similar to the control structures used in JSTL.

These can be useful to create a resin.conf which works for both testing and deployment, depending on an environment parameter. When possible, users should avoid using the control tags when possible to keep their configuration files as simple as possible.

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="http://caucho.com/ns/resin/core">
  <resin:choose>
  <resin:when test="\${mode='development'}">
    <resin:log>Development Mode</resin:log> 
  </resin:when>
  <resin:when test="\${mode='deploy'}">
    <resin:log>Deployment Mode</resin:log> 
  </resin:when>
  <resin:otherwise>
    <resin:log>Unknown Mode \${mode}</resin:log>
  </resin:otherwise>
  <resin:choose>
</web-app>

The source code for the control elements is found in com.caucho.config.core.

resin:set

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

<resin:set var="name" value="\${value}"/>

resin:if

resin:if executes part of the configuration file conditionally.

<resin:if test="\${expr}">
  ...
<resin:if>

resin:choose

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

resin:otherwise

resin:log

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

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

resin:import

resin:import is used to read 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 <server> will have a target with a top-level of <server>.

resin:env

resin:env creates a new environment for a section of the configuration file. Some users may want to use this to create resources or databases with custom <class-loader> tags.

resin:env is tricky and only required for some extraordinary circumstances. Using it correctly requires a good understanding of classloaders.

Here is an example of a solution for the situation where a custom access logging class requires an old version of a jar that the web application uses as well. The requirement is that the example.MyAccessLog use an old version of the classes in Foo.jar, webapps use a newer version of the jar.

In a normal circumstance, access-log is used in the <host> environment. If the example.MyAccessLog uses a class from a jar file oldversion-Foo.jar, oldversion-Foo.jar needs to available to the classloader for the <host> environment. Because a %lt;web-app> inherits the classes of the <host>, the webapp will end up with the Foo.jar classes from the host's classloader; WEB-INF/lib/Foo.jar will not provide the classes because they have already been defined in the parent (host) classloader.

The following example solves the problem by using resin:env to create an environment just for the instantiation of the example.MyAccessLog class.

<host id=''>
  <resin:env>
   <class-loader>
     <library-loader path="/opt/lib/oldversion-Foo.jar"/>
   </class-loader>

   <access-log resin:type="example.MyAccessLog"/>
  </resin:env>

  ...

  <web-app>
    <!-- WEB-INF/lib can contain Foo.jar and the classes are not overridden 
         by the classes in oldversion-Foo.jar.
       -->
    ...
  </web-app>
</host>

Functions

Static functions are available in EL expressions. Resin also makes utility objects avilable as EL variables that provide functions as methods.

jndi

jndi:lookup

The configuration EL supports a the static function jndi:lookup. jndi:lookup can be used to lookup a JNDI value for the configuration.

<servlet servlet-name='foo'
         servlet-class='qa.FooServlet'>
  <init>
    <data-source>${'${'}jndi:lookup("java:comp/env/jdbc/test")}</data-source>
  </init>
</servlet>

fmt

The EL Environment contains a fmt object, which has a number of useful formatting methods.

fmt.timestamp()

Format a timestamp string.

fmt.timestamp(format[,date])

msg="The current date and time is ${'${'}fmt.timestamp('%Y/%m/%d %H:%M:%S.%s')}"
msg="time=${'${'}fmt.timestamp('[%Y/%m/%d %H:%M:%S.%s]')}"

format contains regular characters, which are just copied to the output string, and percent codes which are substituted with time and date values.

fmt.sprintf()

Format a string using a sprintf-like format string.

fmt.sprintf(format[,arg1, arg2 ... argN])

sprintf accepts a series of arguments, applies to each a format specifier from `format', and returns the formatted data as a string. `format' is a string containing two types of objects: ordinary characters (other than `%'), which are copied unchanged to the output, and conversion specifications, each of which is introduced by `%'. (To include `%' in the output, use `%%' in the format string).

A conversion specification has the following form:

%[FLAGS][WIDTH][.PREC][TYPE]

TYPE is required, the rest are optional.

The following TYPE's are supported:

Intepret the word `integer' to mean the java type long. Since java does not support unsigned integers, all integers are treated the same.

The following optional FLAGS are supported:

The optional WIDTH argument specifies a minium width for the field. Spaces are used unless the `0' FLAG was used to indicate 0 padding.

The optional PREC argument is introduced with a `.', and gives the maximum number of characters to print; or the minimum number of digits to print for integer and hex values; or the maximum number of significant digits for `g' and `G'; or the number of digits to print after the decimal point for floating points.