Resin Documentation

resin 3.1.0 release notes

Resin 3.1.x is a development branch. New capabilities will be added along with bug fixes for future versions of the Resin 3.1.x branch.

Deployments which need a Resin version with only bug fixes should use the Resin 3.0.x branch.

Resin 3.1 adds Servlet 2.5 support. The Servlet 2.5 specification adds annotation-based injection to servlets, filters, and listeners. Servlets can now mark a field as a @Resource and Resin will assign the configured database, bean, or service to the field, avoiding the need for a JNDI lookup.

package example;

import javax.annotation.Resource;
import javax.servlet.*;
import javax.sql.*;

public class MyServlet extends GenericServlet {
  @Resource(name="jdbc/mysql")
  private DataSource _database;

  public void service(ServletRequest req, ServletResponse res)
  {
     ...
  }
}

With Resin 3.1, the JPA features have been reviewed. Amber now provides a near to complete and stable implementation of the JPA specification.

JPA queries are fully supported, including queries with parameters, named queries, and subqueries. The javax.persistence.Query API is also supported, including date/time (temporal) data types.

Embedded properties and optimistic-locking with version fields have been added to Amber in Resin 3.1. Also, inheritance combined with many-to-one, one-to-many, one-to-one, and many-to-many relationships have been reviewed and are now totally stable following the final release of the JPA specification.

Finally, an object relational mapping file (orm.xml) can now be merged together with annotations, when present. In other words, with Resin 3.1, the set of JPA features supported by Amber is near to complete, i.e., only a few unusual features will be added to the next release.

Resin 3.1 now uses a Java watchdog process to manage Resin instances for reliability. Like the older 3.0 wrapper.pl, it detects if the instance has stopped and restarts it automatically.

Because the watchdog is now a Java process, the Resin start and stop can now use a Java -jar command:

unix> java -jar $RESIN_HOME/lib/resin.jar -server a start

Also, because the Resin instance is started from Java itself, the JVM command-line arguments must now be specified in the resin.conf.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="app-tier">

    <server-default>
      <jvm-args>-Xmx1024m</jvm-args>
      <jvm-args>-Xss1m</jvm-args>
      <jvm-args>-verbosegc</jvm-args>

      <http port="8080"/>
    </server-default>

    <server id="app-a" address="192.168.2.1" port="6800"/>
    <server id="app-b" address="192.168.2.2" port="6800"/>

    ...
  </cluster>
</resin>

Resin 3.1 has swapped the order of the <cluster> and <server> configuration tags to make the resin.conf more powerful and understandable. (The old Resin 3.0 syntax is still allowed for backwards compatibility.) In addition, the new configuration matches the JMX MXBeans more cleanly. With Resin 3.1, all servers in a load-balancing configuration can be defined in a single resin.conf.

A <server> configures a Resin JVM instance. It defines the <http> and cluster ports to listen to, JVM arguments, thread limits, keepalives and timeouts. In other words <server> configures JVM instance information which changes from instance to instance.

See <server> tag for the new server tags.

The <cluster> is a collection of servers serving identical content. So the <cluster> contains a set of <server> tags, plus the <host>, <resource>, and the <web-app> configuration common to all servers.

<cluster> tag for the new cluster tags.

The following example shows a basic load-balancing configuration in Resin 3.0 with a set of web-tier servers load balancing to a larger set of app-tier servers. Since the web-tier includes a proxy <cache> configuration, the web-tier will serve static files without extra overhead.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="web-tier">
    <server-default>
       <user-name>resin</user-name>

       <http port="80"/>
    </server-default>

    <server id="web-a" address="192.168.2.10">
    <server id="web-b" address="192.168.2.11">

    <cache disk-size="1024m" memory-size="128m"/>

    <host id="">
      <web-app id="/">
        <rewrite-dispatch>
          <load-balance regexp="" cluster="app-tier"/>
        </rewrite-dispatch>
      </web-app>
    </host>
  </cluster>

  <cluster id="app-tier">
    <root-directory>/var/www</root-directory>

    <server id="app-a" address="192.168.2.20">
    <server id="app-b" address="192.168.2.21">
    <server id="app-c" address="192.168.2.21">

    <host-default>
      <web-app-deploy path="webapps"/>
    </host-default>

    <host-deploy path="hosts"/>
  </cluster>
</resin>

Documentation for the new web services capabilities is in the web services section.

Resin has updated its configuration for web services like Hessian, and has extended the web service capabilities to include SOAP and VM-local requests.

Applications can write to standard @WebService APIs, using JAXB annotations for marshalled XML (or marshalled Hessian), and export the services as Hessian, SOAP or Rest.

Configuration has been simplified:

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

  <servlet-mapping url-pattern="/hello/*"
                    servlet-class="example.HelloServiceImpl">

    <!-- jndi registration for direct VM calls -->
    <jndi-name>service/HelloService</jndi-name>

    <!-- IoC-style configuration -->
    <init>
      <hello>hello, world</hello>
    </init>

    <!-- soap, hessian, burlap protocols -->
    <protocol type="hessian">
      <api-class>example.HelloService</api-class>
    </protocol>
  </servlet-mapping>

</web-app>

The client proxy can now be configured as well. Applications can now write to the client APIs without worrying about proxy generation.

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

<web-service-client jndi-name="hessian/HelloService">
  <url>hessian:http://localhost:8080/hello-world/hello/</url>
  <interface>example.HelloService</interface>
</web-service-client>

</web-app>

See JAXB Bean Configuration tutorial

Quercus now supports the i18n and l10n features of PHP. This includes gettext, iconv, and multi-byte strings. In addition, Quercus has PHP6 Unicode support in anticipation of the upcoming release of PHP6.

Added Java serialization support for Quercus/PHP types. Hessian/Burlap will be able to serialize/deserialize Quercus objects with no problem.

Revamped PHP-Java type marshaling.