Overview

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

Because of the large number of changes, developers should stress test their application with Resin 3.0.0 thoroughly before deploying it.

We are calling the Resin 3.0.x series "beta". The "production" versions will be the Resin 3.1.x series. The two reasons for calling the code "beta" is the large number of changes, and because we are expecting to add a great deal of features to following 3.0.x releases. For many users, the stability of 3.0.x will be sufficient for deployment, but we wanted to give an extra warning to make sure that people stress tested their applications before deploying on 3.0.x.

Configuration Changes

Backward Compatibility

As much as possible, Resin 3.0.0 configuration is expected to provide backward compatibility. In most cases, the Resin 2.1.x configuration should work with Resin 3.0. If not, it should be reported as a bug. However, backward compability only applies when validation is disabled. In other words, if the configuration specifies the xmlns="http://caucho.com/ns/resin" namespace, only the new configuration will be accepted.

The primary exceptions are handling of web-app and host defaults. Resin 3.0.0 has a <web-app-default> and a <host-default> elements. It is now no longer legal to put web-app configuration in the <host> or the <server> sections.

In addition, there is no longer any default web-app or host. In other words, if the resin.conf has no <host id=''> or <web-app id='/'>, then requests to an unknown host will fail with a 404 file not found exception.

Top-level and validation

Resin now uses Relax-NG to validate configuration files. This should help find configuration errors faster. The Resin configuration XML namespace is http://caucho.com/ns/resin. All configuration files using Resin extensions should use that namespace. In addition, Resin understands the new J2EE namespace, http://java.sun.com/xml/ns/j2ee. Configuration files using that namespace must conform exactly to the j2ee specification.

The Relax-NG schema are contained in the resin.jar and resin-ee.jar.

com/caucho/server/resin/env.rnc

environment/resource configuration

com/caucho/server/resin/resin.rnc

resin.conf definition

com/caucho/server/webapp/web-xml.rnc

J2EE web.xml definition

com/caucho/server/webapp/resin-web-xml.rnc

Resin web.xml definition

com/caucho/server/ejb/ejb-jar.rnc

J2EE ejb-jar definition

com/caucho/jsp/cfg/jsp-tld.rnc

J2EE JSP .tld file definition

com/caucho/server/ejb/resin-ejb.rnc

Resin ejb definition

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

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

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

tag name changes

Some tags have had some name changes to more accurately reflect their meanings. If the xmlns="http://caucho.com/ns/resin" is specified, the old names are no longer allowed. If the old <caucho.com> is used, they will be allowed.

"Environment" configuration

Resin's configuration is now organized into "Environments". Each environment has its own classloader, JNDI space, resources, logs, system properties, etc. The Environment is just a generalization of Resin 2.1's class-loader context for <http-server>, <host>, and <web-app>. Now, any context could have its own environment: EJB servers, the outer <resin> declaration, even individual session beans.

Any of the class loader and resource configuration is allowed in any environment. See the environment configuration for the list.

class loader configuration

Class loading configuration has been split from the old classpath into a new set of class loading implementations: compiling-loader, simple-loader, library-loader, and make-loader. These are primarily intended to make class loader configuration more clear.

reference configuration

reference configures JNDI ObjectFactories, while resource configures bean objects directly. Several third-party components expect to be configured as ObjectFactory references instead of configured as beans.

database configuration

With the exception of replacing <reference-ref> with the new <database>, database configuration is similar to the old style. <driver-class> and <driver-url> are the new primary subtags of the <database> configuration.

For transactions, <xa>true</xa> configures the DataSource as transactional.

ejb-server configuration

<ejb-server> now replaces the resource configuration for com.caucho.ejb.EJBServer.

web-app-default and host-default

Resin's support for web-app defaults and host defaults is now more consistent and robust. All the defaults, including *.jsp and the configuration of WEB-INF/classes and WEB-INF/lib, are now implemented using web-app-default and host-default. The distribution puts these in $RESIN-HOME/conf/app-default.xml.

All the configuration items in web-app-default are applied to the web-app at initialization time. Since web-app-default items are applied first, the later web.xml definitions will override them.

web-app-deploy

.war deployment has been generalized from the simple war-dir in Resin 2.1. "webapps" directories can now be subdirectories of a web-app. For example, doc/servlet/tutorial is an expansion directory. All the tutorial examples are separate web-apps added automatically.

root-directory and document-directory

The configuration of directories for server, host, and web-app has been cleaned up to remove some confusion.

The <server> has only a root-directory. The server's root-directory specifies the top-level location for log files, caching, etc.

The <host> has a root-directory and a document-directory. The root-directory defaults to the server's root-directory if none is specified. The document-directory is the location for the host's documents.

The <web-app> has only a document-directory. It replaces the app-dir configuration.

JSP-EL and Bean-Style Configuration

All configuration in Resin is now based on bean-style configuration using XML to configure beans. Each tag in all the configuration files corresponds to a setXXX or addXXX or createXXX method in a bean.

The configuration allows JSP-EL expressions in any context where primitive values are allowed. So any string or path can be configured with JSP-EL using variables like ${'${'}serverId}.

Servlets and Filters can be configured with <init> blocks that use the full power of Resin's configuration. So the following configuration would be possible:

<servlet servlet-name='test'>
  <servlet-class>test.TestServlet</servlet-class>
  <init>
    <greeting>Hello, World</greeting>
  </init>
</servlet>

JDK 1.4 logging

Resin's logging is now integrated with the JDK 1.4 java.util.logging classes. The log configuration configures the Logger classes. So applications which use JDK 1.4 will automatically get integration with Resin's log configuration.

threads, TCP, and "nonblocking" I/O

Resin's threading and TCP accept implementation has been rewritten. All ports for a <server> now share the same pool of worker threads.

For the most part, this change should be invisible to most users.

On Unix, Resin has JNI support for "nonblocking" I/O for keepalive connections. (Resin 3.0 uses select instead of a true nonblocking call.) This new support means Resin can support many more keepalive connections without dedicating any threads.

In other words, an application could have 500 keepalive connections waiting for a client response and only need 5-10 active threads to process that response.

This support is not yet available for Windows. Under Unix, you must ./configure, make, and make install the libexec/libresin.so to get the new keepalive support.

bin/resin has been removed

Most of the capabilities of bin/resin are now handled by JNI. The <user-name> and <group-name> support have not yet been added to Resin 3.0.x. Older versions of Linux will need to use an alternative method of changing the user. Newer Linux versions will be able to use the JNI-based <user-name> once that's reintroduced.

JavaScript for JSP support has been dropped

Since the JavaScript for JSP was used by too few users, it no longer makes sense to continue support.

In addition, the JSP-EL and JSTL tag libraries make the need for a separate dynamically-typed language less important.

Significant plugin changes

The plugins, mod_caucho and isapi_srun.dll, have been changed significantly. The plugin configurations are truly "beta" quality as more work is needed to bring them up to the usual Resin standards.

If you intend to deploy with Resin 3.0.0-beta, it is highly recommended that you use Resin standalone instead of using Apache or IIS. The quality issues are expected to be resolved by 3.0.1.

The plugins now use the HMUX protocol to talk from Apache/IIS to the Resin backend.

The plugins also now query the backend for their configuration. They no longer read the resin.conf independendly. (This is the part that's very new.)

Cluster support

Resin's load balancing and session backup has been cleaned up and generalized somewhat. <srun> ports now belong in a <cluster> definition. This should make the configuration a bit clearer.

<cluster>
  <srun id='' host='127.0.0.1' port='6802'/>
</cluster>

The appropriate load balance servlet is now com.caucho.servlets.LoadBalanceServlet. It uses the HMUX protocol as the plugins do.

package changes

The Caucho servlets are now in com.caucho.servlets. The filters are in com.caucho.filters.

The authentication classes are in com.caucho.server.security.

We do plan to implement backward compatibility classes for those who have used custom authenticators, but this has not yet been done.

JSP 2.0 and Servlet 2.4 drafts

The next versions of the JSP and Servlet specs are currently in the draft stage. Resin 3.0 does implement the new specs, but may not yet be fully up to date on the latest drafts.