<document>
  <header>
    <product>resin</product>
    <title>A Simple Resource Bean</title>
    <type>tutorial</type>
    <description>Resources are beans configured in the resin.conf or web.xml and stored in JNDI.  The tutorial shows the configuration of a trivial bean as a resource and looking it up using JNDI.</description>
 <tutorial-startpage>index.jsp</tutorial-startpage>

</header>

  <body>
<summary/>
<section title="Resources">

<p>A resource in Resin is any bean configured in the
resin.conf or web.xml.  Resources are generally stored in JNDI.  Because
resources can be any Java class conforming to the bean configuration
patterns, resources provide a flexible configuration.</p>

<p>Some typical resources include:</p>
<ul>
<li>Databases
<li>JMS connections
<li>The EJB server
<li>JCA resources
</ul>

<p>Because resources are configured in the resin.conf/web.xml and are
created before any servlets start, they are very convenient for globally
available beans, even allowing for more complex configuration beans extending
the idea of &lt;env-entry> (which stored simple Strings or
Integers in JNDI.)</p>

<subsection title="The TestResource bean">

<p>The <code>TestResource</code> bean is almost as simple as possible.
It has a single String configuration parameter and does nothing but
print its value using <code>toString()</code>.</p>

<example title="TestResource.java">
package test;

public class TestResource {
  private String _value = "default";

  public void setValue(String value)
  {
    _value = value;
  }

  public String toString()
  {
    return "TestResource[" + _value + "]";
  }
}
</example>

<p>In other words, you have lots of flexibility of things to configure
as resources.</p>

</subsection>

<section title="web.xml configuration">

<p>The web.xml (or resin.conf) configures the resource with the
&lt;resource> tag.  The resource is created and stored in the
environment where it is defined.  So a resource configured in the
&lt;host> will be available for all web-apps in that host and a
resource configured in a &lt;web-app> will only be available for that
&lt;web-app>.</p>

<example title="web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">
  &lt;resource jndi-name="test/basic" type="test.TestResource">
    &lt;init>
      &lt;value>An Example Resource&lt;/value>
    &lt;/init>
  &lt;/resource>
&lt;/web-app>
</example>

<deftable>
<tr><th>tag<th>description
<tr><td>resource<td>defines the resource
<tr><td>name<td>the JNDI name of the resource (in java:comp/env)
<tr><td>type<td>the class name of the resource bean
<tr><td>init<td>Any bean-style configuration goes here
<tr><td>value<td>The example bean's <code>setValue</code> parameter.
</deftable>

</section>

<section title="Using the resource">

<p>The example uses a servlet to demonstrate the resource, but any
class could use JNDI to look up and use the resource.  Because resources
are stored in JNDI, they can avoid the complexity of passing objects
around or storing in the servlet context.</p>

<p>Because JNDI is just a storage tree, the example looks up the
resource once and then stores it in a private field.</p>

<p>If you save the resource, it's important that the saved field is reloaded
when the web-app restarts.  The resource has the
same lifetime as its environment: web-app, host or server.  When that
environment closes, the resource is no longer valid and must be discarded.
In particular, it is important to store any resource in an object's field,
<b>not</b> in a static field or static hashtable.</p>

<example title="TestServlet.java">
package test;

import java.io.IOException;
import java.io.PrintWriter;

import javax.servlet.ServletException;

import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import javax.naming.InitialContext;
import javax.naming.Context;
import javax.naming.NamingException;

public class TestServlet extends HttpServlet {
  private TestResource _resource;

  public void init()
    throws ServletException
  {
    try {
      Context ic = new InitialContext();

      _resource = (TestResource) ic.lookup("java:comp/env/test/basic");
    } catch (NamingException e) {
      throw new ServletException(e);
    }
  }
  
  public void doGet(HttpServletRequest req, HttpServletResponse res)
    throws ServletException, IOException
  {
    PrintWriter out = res.getWriter();

    out.println("Resource: " + _resource);
  }
}
</example>
<results>
Resource: TestResource[An example resource]
</results>

</section>

</section>

<section title="Compatibility">

<p>Because the resource beans are just Java classes, the resources
themselves are independent of Resin.  The configuration, of course,
is dependent on Resin.</p>

<p>You can configure resources in other server engines by creating
a load-on-startup servlet that creates your resource and
stores them into JNDI.  Although that is less convenient than Resin's resource
configuration, it will work with other servlet engines.  So you can
start creating and using resources without worrying excessively about
compatibility issues.</p>

</section>

  </body>
</document>
