<document>
  <header>
    <product>resin</product>
    <title>Resin 3.1.0 Release Notes</title>
  </header>

<body>

<localtoc/>

<s1 title="Resin 3.1.x">

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

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

</s1>

<s1 title="Servlet 2.5">

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

<example title="Database configuration">
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)
  {
     ...
  }
}
</example>
  

</s1>
<s1 title="Amber capabilities">

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

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

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

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

</s1>

<s1 title="watchdog/startup changes">

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

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

<example title="starting server web-a">
unix> java -jar $RESIN_HOME/lib/resin.jar -server a start
</example>

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

<s2 title="JVM command-line arguments">

<p>With Resin 3.1, JVM command-line arguments are specified in the
resin.conf.  The watchdog JVM will read the resin.conf, select the
proper &lt;<a href="doc|server-tags.xtp#server">server</a>&gt;, and
apply the server's arguments.  As usual, the
&lt;<a href="doc|server-tags.xtp#server-default">server-default</a>&gt;
tag can provide common defaults.</p>

<example title="setting -Xmx and -Xss">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="app-tier">

    &lt;server-default>
      &lt;jvm-args>-Xmx1024m&lt;/jvm-args>
      &lt;jvm-args>-Xss1m&lt;/jvm-args>
      &lt;jvm-args>-verbosegc&lt;/jvm-args>

      &lt;http port="8080"/>
    &lt;/server-default>

    &lt;server id="app-a" address="192.168.2.1" port="6800"/>
    &lt;server id="app-b" address="192.168.2.2" port="6800"/>

    ...
  &lt;/cluster>
&lt;/resin>
</example>

</s2>

</s1>

<s1 title="resin.conf changes to cluster and server">

<p>Resin 3.1 has swapped the order of the &lt;cluster> and &lt;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.</p>

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

<p>See &lt;<a href="../doc/server-tags.xtp">server</a>&gt; tag
for the new server tags.</p>

<p>The &lt;cluster> is a collection of servers serving identical content.
So the &lt;cluster> contains a set of &lt;server> tags, plus
the &lt;<a href="doc|host-tags.xtp#host">host</a>&gt;,
&lt;<a href="doc|env-tags.xtp">resource</a>&gt;, and
the &lt;<a href="doc|webapp-tags.xtp">web-app</a>&gt; configuration
common to all servers.</p>

<p>&lt;<a href="doc|cluster-tags.xtp">cluster</a>&gt; tag
for the new cluster tags.</p>

<p>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 &lt;<a href="doc|cluster-tags.xtp#cache">cache</a>&gt;
configuration, the web-tier will serve static files without
extra overhead.</p>


<example title="resin.conf">
&lt;resin xmlns="http://caucho.com/ns/resin">
  &lt;cluster id="web-tier">
    &lt;server-default>
       &lt;user-name>resin&lt;/user-name>

       &lt;http port="80"/>
    &lt;/server-default>

    &lt;server id="web-a" address="192.168.2.10">
    &lt;server id="web-b" address="192.168.2.11">

    &lt;cache disk-size="1024m" memory-size="128m"/>

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

  &lt;cluster id="app-tier">
    &lt;root-directory>/var/www&lt;/root-directory>

    &lt;server id="app-a" address="192.168.2.20">
    &lt;server id="app-b" address="192.168.2.21">
    &lt;server id="app-c" address="192.168.2.21">

    &lt;host-default>
      &lt;web-app-deploy path="webapps"/>
    &lt;/host-default>

    &lt;host-deploy path="hosts"/>
  &lt;/cluster>
&lt;/resin>
</example>

</s1>

<s1 title="Web services capabilities and configuration">

<p>Documentation for the new web services capabilities is
in the <a href="doc|soa.xtp">web services</a> section.</p>

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

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

<p>Configuration has been simplified:</p>

<example title="&lt;web-service> configuration">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;servlet-mapping url-pattern="/hello/*"
                    servlet-class="example.HelloServiceImpl">

    &lt;!-- jndi registration for direct VM calls -->
    &lt;jndi-name>service/HelloService&lt;/jndi-name>

    &lt;!-- IoC-style configuration -->
    &lt;init>
      &lt;hello>hello, world&lt;/hello>
    &lt;/init>

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

&lt;/web-app>
</example>

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

<example title="&lt;web-service-client>">
&lt;web-app xmlns="http://caucho.com/ns/resin">

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

&lt;/web-app>
</example>


</s1>

<s1 title="JAXB for Config IoC">

<p>See <a href="../examples/jaxb-bean-config/index.xtp">JAXB Bean
Configuration tutorial</a></p>

</s1>

<s1 title="Quercus">

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

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

<p>Revamped PHP-Java type marshaling.</p>

<s2 title="Applications Running on Quercus">

<ol>

<li>DokuWiki 2006-11-06</li>
<li>Dragonfly CMS 9.0.6.1.7</li>
<li>Drupal 4.7.4</li>
<li>Gallery2</li>
<li>Joomla 1.0.11</li>
<li>Mambo</li>
<li>Mantis</li>
<li>MediaWiki</li>
<li>Phorum 5.1.16a</li>
<li>phpBB 2.0.21</li>
<li>phpMyAdmin 2.9.1.1</li>
<li>PHProjekt 5.2</li>
<li>PHP-Nuke</li>
<li>Wordpress 2.0.5</li>
<li>Xoops 2.0.16</li>
</ol>

</s2>

</s1>

<s1 title="Administration/JMX">

<s2 title="ConnectionPoolMXBean">

<p>Added <code>clear()</code> operation to clear idle connections in
the pool.</p>

</s2>
</s1>

</body>
</document>
