Control structures, EL Variables, and Functions
Resin 3.0

Features
Installation
Configuration
Web Applications
IOC/AOP
Resources
JSP
Servlets and Filters
Portlets
Databases
Admin (JMX)
CMP
EJB
Amber
EJB 3.0
Security
XML and XSLT
XTP
JMS
Performance
Protocols
Third-party
Troubleshooting/FAQ

index
howto
resin.conf
env
web-app
log
el control
Bean Config
Common Tasks
Relax Schema
Config FAQ
Scrapbook
log
Configuration
Bean Config

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

  1. Environment Variables
  2. Servlet/Filter bean-style initialization
  3. Control Structures
    1. resin:set
    2. resin:if
    3. resin:choose
      1. resin:when
      2. resin:otherwise
    4. resin:log
    5. resin:import
    6. resin:env
  4. Functions
    1. jndi
      1. jndi:lookup
    2. fmt
      1. fmt.timestamp()
      2. fmt.sprintf()

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

Environment variables
variableattributemeaning
Var System properties, e.g. ${Var["resin.home"]}
server Server properties
 nameThe server id, as specified in -server id
 rootDirThe server root directory, $SERVER_ROOT
 docDirThe server document directory
host Virtual host properties
 urlThe host's canonical URL
 nameThe host name
 rootDirThe host's root directory
 docDirThe host's document directory
 warDirThe host's war directory
 warExpandDirThe host's war expansion directory
 regexpRegular expression values for host regexp matches
app web-app properties
 urlThe web-app's canonical URL
 nameThe web-app name
 contextPathThe web-app's context path
 docDirThe web-app's document directory
 regexpRegular expression values for web-app url-regexp matches

Servlet/Filter bean-style initialization2.1.3

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:

Servlet using JDBC
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:

Example configuration
<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 bena. More infomation on this powerful pattern is in the Bean-style init section of the documentation.

Control Structures3.0.7

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 package com.caucho.config.core .

resin:set

Resin 3.0.7

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

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

AttributeMeaningdefault
namename of the variable to setrequired
valuevaluerequired

resin:if

Resin 3.0.7

resin:if executes part of the configuration file conditionally.

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

AttributeMeaningdefault
testthe test to perform

resin:choose

Resin 3.0.7

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>

AttributeMeaningdefault
resin:when
resin:choose

resin:when

Resin 3.0.7

child of: resin:choose

AttributeMeaningdefault
testthe test to perform

resin:otherwise

Resin 3.0.7

child of: resin:choose

AttributeMeaningdefault
testthe test to perform

resin:log

Resin 3.0.7

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 3.0.7

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

AttributeMeaningdefault
patha path to a fileeither path or fileset is required
fileseta <fileset> either path or fileset is required
optionalif true, no error when file does not existfalse

resin:env

Resin 3.0.7

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.

configuring JNDI
<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])

ParameterMeaningdefault
formatthe format string (see below)required
datean object with class java.util.Date or class java.util.Calendar or class com.caucho.util.QDate the current date and time

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.

CodeMeaning
%aday of week (short)
%Aday of week (verbose)
%bday of month (short)
%Bday of month (verbose)
%cJava locale date
%dday of month (two-digit)
%H24-hour (two-digit)
%I12-hour (two-digit)
%jday of year (three-digit)
%mmonth (two-digit)
%Mminutes
%pam/pm
%Sseconds
%smilliseconds
%Wweek in year (three-digit)
%wday of week (one-digit)
%yyear (two-digit)
%Yyear (four-digit)
%Ztime zone (name)
%ztime zone (+/-0800)

fmt.sprintf()

Format a string using a sprintf-like format string.

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

ParameterMeaningdefault
formatthe format string (see below)required
arg1..argNthe values used for the conversions in the format stringn/a

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:

%%a percent sign
%ca character with the given number
%sa string, a null string becomes "#null"
%za string, a null string becomes the empty string ""
%da signed integer, in decimal
%oan integer, in octal
%uan integer, in decimal
%xan integer, in hexadecimal
%Xan integer, in hexadecimal using upper-case letters
%ea floating-point number, in scientific notation
%Ea floating-point number, like %e with an upper-case "E"
%fa floating-point number, in fixed decimal notation
%ga floating-point number, in %e or %f notation
%Ga floating-point number, like %g with an upper-case "E"
%pa pointer (outputs a value like the default of toString())

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:

0If the TYPE character is an integer leading zeroes are used to pad the field width instead of spaces (following any indication of sign or base).
+Include a `+' with positive numbers.
(a space)use a space placeholder for the `+' that would result from a positive number
-The result of is left justified, and the right is padded with blanks until the result is `WIDTH' in length. If you do not use this flag, the result is right justified, and padded on the left.
#an alternate display is used, for `x' and `X' a non-zero result will have an "0x" prefix; for floating point numbers the result will always contain a decimal point.
jescape a string suitable for a Java string, or a CSV file. The following escapes are applied: " becomes \", newline becomes \n, return becomes \r, \ becomes \\.
vescape a string suitable for CSV files, the same as `j' with an additional " placed at the beginning and ending of the string
mescape a string suitable for a XML file. The following escapes are applied: < becomes &lt;, > becomes &gt; & becomes &amp; ' becomes &#039, " becomes &034;

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.


log
Configuration
Bean Config
Copyright © 1998-2005 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.