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

</header>

  <body>
<localtoc/>

<s1 title="Overview">

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

<p>There is also more documentation
for <a href="../../doc/resin-ioc.xtp">Resin's IoC/Dependency
Injection</a>.</p>

<p>Some typical resources include:</p>
<ul>
<li>Databases</li>
<li>JMS connections</li>
<li>EJB stateful and stateless session beans</li>
<li>JCA resources</li>
</ul>

<p>Because resources are configured in the resin.conf/resin-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&gt; (which stored simple Strings or
Integers in JNDI.)</p>

</s1>

<s1 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>

</s1>

<s1 title="resin-web.xml configuration">

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

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

  &lt;bean class="test.TestResource"&gt;
    &lt;init&gt;
      &lt;value&gt;An Example Resource&lt;/value&gt;
    &lt;/init&gt;
  &lt;/bean&gt;

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

<deftable>
<tr>
 <th>tag</th>
  <th>description</th>
</tr>
<tr>
  <td>bean</td>
  <td>defines the singleton service</td>
</tr>
<tr>
  <td>class</td>
  <td>the class name of the resource bean</td>
</tr>
<tr>
  <td>init</td>
  <td>Any bean-style configuration goes here</td>
</tr>
<tr>
  <td>name</td>
  <td>the optional WebBeans name of the resource</td>
</tr>
<tr>
  <td>value</td>
  <td>The example bean's <code>setValue</code> parameter.</td>
</tr>
</deftable>

</s1>

<s1 title="Using the resource from PHP">

<p>Your PHP scripts can use any WebBeans resource by using the
<code>java_bean()</code> method.  The method will return the named
resource.</p>

<example title="test.php">
&lt;php?

$resource = java_bean("testResource");

echo "PHP resource: " . $resource . "\n";

?>
</example>

</s1>

<s1 title="Using the resource from JSP">

<p>JSP pages can also use WebBeans resource in the JSP expression
language.</p>

<example title="test.jsp">

JSP resource: ${testResource}

</example>

</s1>

<s1 title="Using the resource from a Servlet">

<p>The example uses a servlet to demonstrate the resource, but any
injectable class could use <code>@In</code> to look up and use the
resource.  Because resources are stored globally in WebBeans, they can
avoid the complexity of passing objects around or storing in the
servlet context.</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 cluster.  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.webbeans.In;

public class TestServlet extends HttpServlet {
  @In private TestResource _resource;
  
  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>

</s1>

  </body>
</document>
