Migrating from Resin 2.x
Resin 3.0

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

Feature Overview
Release Notes
Change Logs
Migrate from 2.1
Features FAQ
Old Changes
Features
Features FAQ

Migration from Resin 2.1.x will require some changes, mostly to your configuration files. Resin 3 is a significant internal redesign of Resin. As features have accumulated and Java and XML design have progressed, the old code needed a severe cleaning.

The Release Notes up until version 3.0.3 contain valuable information for migrating from 2.1. Additional notes are included below.

  1. Release Notes
  2. Validation of configuration files
  3. resin and server
    1. srun and cluster
  4. host and web-app
    1. web-app-default and host-default
  5. General
    1. logging
    2. thread dumps
    3. jars no longer included
    4. resin:include-directory
  6. Resources
    1. resource
    2. Databases
    3. authenticator and custom authentiator
  7. XML/XSL/XTP
    1. XSL/XTP search path for .xsl files

Release Notes

The release notes for 3.0.0, 3.0.1, 3.0.2, 3.0.3, and 3.0.4 contain in-depth explanations of many the changes that occured for Resin 3.

Validation of configuration files

Resin 3.0 now validates configuration files. In particular, attributes like <foo a="bar"> need the quotes. Resin 2.1 allowed illegal XML attributes, Resin 3.0 is more strict.

The Resin configuration files now have their own namespace, which is necessary for the validation. The resin.conf looks like:

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

The web.xml or resin-web.xml looks like:

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

Using the Resin namespace lets you use Resin extensions like <database> configuration. If you want to use a strict Servlet web.xml, use the J2EE namespace:

<web-app xmlns="http://java.sun.com/xml/ns/j2ee" version="2.4"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="...">
  ...
</web-app>

resin and server

The top-level configuration has changed to <resin> and <server>. These changes more closely conform to typical XML usage.

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

srun and cluster

The <srun> configuration now belongs inside a <cluster> declaration to more clearly convey how the cluster is organized. <http> is unchanged.

...
<server>
  <cluster>
    <port id="a" port="6810" index="1"/>
    <port id="b" port="6811" index="2"/>
  </cluster>

host and web-app

Resin 3.0 makes as much configuration explicit as possible, including web-app defaults.

web-apps and hosts must be explicitly configured in the resin.conf, either with <web-app> or <web-app-deploy> elements. This differs from Resin 2.1, which always included a "default" web-app and host even when not configured.

The following configuration will return a 404 message for /test.jsp because it does not have a defined root web-app. Because there's a "foo" web-app, /foo/test.jsp would work.

resin.conf
<resin xmlns="http://caucho.com/ns/resin">
  <server>
    ...
    <host id="">
      <web-app id="/foo"/>
    </host>
  </server>
</resin>

web-app-default and host-default

As part of Resin 3.0's requirement of explicit defaults, the defaults for web-apps and hosts belong in <web-app-default> and <host-default> elements. (Resin 2.1 had a confusing mechanism where configuration outside the <web-app> was a default for inside the <web-app>.)

The following configures a default <context-param> for all web-apps in the host.

...
<host id="foo.com">
  <web-app-default>

    <context-param host="foo.com"/>

  </web-app-default>
</host>
...

All of Resin's defaults, like the JSP servlet the the default <mime-mapping> configuration are in a <web-app-default> that is included explicitly from the resin.conf.

General

logging

Resin now uses the JDK 1.4 logging facility

.

The wrapper now redirects output from the java process to log/jvm.log.

There were all kinds of problems trying to use the same output file from the wrapper (which catches the stdout and stderr from the java process) and in the resin.conf (which catches the use of System.out and System.err).

thread dumps

Thread dumps from a Resin process that does not output to a terminal will appear in log/jvm.log.

jars no longer included

The jar files jaxp, dom, sax.jar, jndi.jar, and jdbc2_0-stdext.jar are already included in JDK 1.4, so Resin no longer needs to include them.

resin:include-directory

Resin 2.1 syntax
<resin:include-directory href='mywebapps' extension='.conf'/>

Resin 3.0 syntax
<resin:import>
 <fileset dir="mywebapps">
   <include>*.conf</include>
 </fileset>
</resin:import>
See <resin:import> .

Resources

resource

Custom resource configuration now uses the <resource> tag. The old <resource-ref> was an inaccurate extension of the Servlet spec's <resource-ref>. The change should avoid confusion.

<resource> configuration has the following components:

  • A jndi-name attribute for the JNDI path name
  • A type attribute for the Java class of the resource
  • An <init> element for custom configuration of the resource
  • An optional mbean-name for registering the resource as an MBean

example Hibernate configuration
<resource jndi-name="java:comp/env/hibernate">
  <type>net.sf.hibernate.jca.ManagedConnectionFactoryImpl</type>
  <init>
    <dialect>net.sf.hibernate.sql.MySQLDialect</dialect>
    <driver-class>org.gjt.mm.mysql.Driver</driver-class>
    <connection-url>jdbc:mysql://localhost:3306/test</connection-url>
  </init>
</resource>

Databases

  • Configuration of databases has changed significantly. See Databases for more information. The usage pattern for databases (the code you use to get a connection and use it) has not changed.
  • In particular, the <ping-on-xxx> have been replaced by a single <ping> and a <ping-interval>
  • Caucho is no longer developing the mysql-jdbc driver. Use the MySQL JDBC driver instead.

<database>
  <jndi-name>jdbc/mysql</jndi-name>
  <driver>
    <type>com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource</type>
    <url>jdbc:mysql://localhost:3306/dbname</url>
    <user>username</user>
    <password>password</password>
  </driver>
  ...
</database>

authenticator and custom authentiator

Authenticators, including custom authenticators are now resources. They belong outside the <login-config> element.

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

  <authenticator type="com.caucho.server.security.JdbcAuthenticator">
    <init>
      <data-source>test</data-source>
      <password-query>
        SELECT password FROM LOGIN WHERE username=?
      </password-query>
      <cookie-auth-query>
        SELECT username FROM LOGIN WHERE cookie=?
      </cookie-auth-query>
      <cookie-auth-update>
        UPDATE LOGIN SET cookie=? WHERE username=?
      </cookie-auth-update>
      <role-query>
        SELECT role FROM LOGIN WHERE username=?
      </role-query>
    </init>
  </authenticator>
  
  <login-config>
    <auth-method>FORM</auth-method>
    <realm-name>default</realm-name>
    <form-login-config>
      <form-login-page>/security/login/login.jsp</form-login-page>
      <form-error-page>/security/login/error.jsp</form-error-page>
    </form-login-config>
  </login-config>

  ...

</web-app>

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

<authenticator type="com.foo.MyAuthenticator">
 <init>
   <pool-name>jdbc/dbpkg/pool</pool-name>
 </init>
</authenticator>

<login-config>
  <auth-method>FORM</auth-method>
  <realm-name>default</realm-name>
  <form-login-config>
    <form-login-page>/security/login/login.jsp</form-login-page>
    <form-error-page>/security/login/error.jsp</form-error-page>
  </form-login-config>
</login-config>

XML/XSL/XTP

  • The XML parser is now strict about attribute values having quotes. For example, <foo bar=baz> must now be written as <foo bar='baz'> or <foo bar="baz">.

XSL/XTP search path for .xsl files

In Resin 3.0.x, much more of the configuration is explicit. Resin 2.x had a bunch of built-in defaults. One of the defaults in Resin 2.x was to search for .xsl files in WEB-INF/xsl.

In Resin 3.0.x, the XTP stylesheets are looked up in the classpath. So, to have XTP look in WEB-INF/xsl, you need to add it to the classpath. The following will do the trick:

<class-loader>
 <simple-loader path="WEB-INF/xsl"/>
</class-loader>

You can either put that directly in the <web-app> or use a <web-app-default> to add WEB-INF/xsl for all your webapps.


Old Changes
Features
Features FAQ
Copyright © 1998-2006 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.