<document>
<header>
<type>tutorial</type>
<tutorial-startpage>stateless</tutorial-startpage>
<title>Local Stateless Session Hello</title>
<description>

<p>Stateless sessions make database queries and updates robust by
setting transaction boundaries at each business method.
This <var>stateless session</var> bean example annotates a single
business method with a SUPPORTS transaction attribute, marking the
method as a read-only transaction boundary.</p>

<p>See also:</p>
<ul>
<li>The <a href="doc|resin-ejb.xtp">Resin-EJB</a> reference.
</li></ul>

</description>
</header>

<body>
<localtoc/>

<s1>
<p>A Hello, World example for EJB 3.0 is much simpler than for earlier
versions of EJB.  To implement the EJB you need to implement:</p>

<ul>
<li>A local interface</li>
<li>The bean implementation</li>
</ul>

<p>To configure Resin to be a server for the EJB you need to:</p>

<ul>
<li>Configure the ejb-stateless-bean</li>
<li>Inject the bean into the application servlet</li>
</ul>

<p>In this tutorial, a simple "Hello" EJB is created and
deployed within Resin.</p>
</s1>

<s1 title="Files in this tutorial">
<deftable>
<tr>
  <th>File</th>
  <th>Description</th>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/web.xml"/></td>
  <td>web.xml configuration</td>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/classes/example/Hello.java"/></td>
  <td>The local interface for the stateless session bean</td>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/classes/example/HelloBean.java"/></td>
  <td>The implementation for the stateless session bean</td>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/classes/example/HelloServlet.java"/></td>
  <td>The client for the stateless session bean</td>
</tr>
</deftable>
</s1>

<s1 title="Local Interface">

<p>The remote interface defines the client view of the bean.
It declares all the business methods.  Our
only business method is the <code>hello</code> method.</p>

<example title="Hello.java">
package example;

public interface Hello {
  public String hello();
}
</example>

</s1>

<s1 title="Bean Implementation">

<p>The second class for EJBs is the bean implementation class.  It implements
the functionality provided by the remote interface.</p> 

<example title="HelloBean.java">
package example;

import javax.ejb.Stateless;
import javax.ejb.TransactionAttribute;
import static javax.ejb.TransactionAttributeType.SUPPORTS;

import javax.webbeans.Named;

@Stateless
public class HelloBean implements Hello {
  @Named("greeting")
  private String _greeting;

  @TransactionAttribute(SUPPORTS)
  public String hello()
  {
    return _greeting;
  }
}
</example>

<s2 title="@Stateless">

<p>The @Stateless annotation marks the bean as a stateless session
bean.  Resin will create a stub implementing <code>Hello</code> and
store it in the WebBeans directory with type <code>Hello</code> and
name <code>@Named("HelloBean")</code>.</p>

<p>The @Stateless annotation can have an optional <code>name</code>
value which overrides the default name of "HelloBean".</p>

</s2>

<s2 title="@Named">

<p>The <a href="doc|webbeans-annotations.xtp#@Named">@javax.webbeans.Named</a>
annotation tells Resin to lookup the greeting <code>String</code>
in the WebBeans directory with the name binding "greeting" when the
session bean is created.</p>

<p>In this example, the greeting is configured with an &lt;env-entry&gt;
in the web.xml.</p>

</s2>

<s2 title="Alternate Dependency Injection">

<p>In some cases, it may be clearer to configure the session bean directly,
rather than using WebBeans injection.  Instead of creating a separate
&lt;env-entry>, you can configure the greeting value using XML
straight from the resin-web.xml file.</p>

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

  &lt;ejb-stateless-bean class="qa.TestBean">
    &lt;init>
      &lt;greeting>Hello, World from web.xml&lt;/greeting>
    &lt;/init>
  &lt;/ejb-stateless-bean&gt;

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

</s2>

<s2 title="@TransactionAttribute">

<p>Managing transactions is the primary purpose of stateless
session beans.  Transactions are a more powerful version of
a <code>synchronized</code> lock used to protect database integrity.
<a href="doc|ejb-annotations.xtp#@TransactionAttribute">@TransactionAttribute</a>
marks the transaction boundary for each business method.</p>

<example>
@javax.ejb.TransactionAttribute(SUPPORTS)
public String hello()
</example>

<p>The <code>hello()</code> business method uses SUPPORTS because it's
a read-only method.  It doesn't need to start a new transaction on its
own, but will participate in any transaction that already exists.</p>

<p>The REQUIRED transaction value starts up a new transaction if none
already exists.  It's used when updating database values.</p>

<deftable>
<tr>
  <th>TransactionAttribute</th>
  <th>meaning</th>
</tr>
<tr>
  <td>REQUIRED</td>
  <td>Start a new transaction if necessary</td>
</tr>
<tr>
  <td>SUPPORTS</td>
  <td>Don't start a new transaction, but use one if it exists</td>
</tr>
</deftable>

</s2>

</s1>

<s1 title="Configuring the EJB stateless bean">

<p><code>&lt;ejb-stateless-bean&gt;</code> configure the session bean
from the resin-web.xml.
The &lt;ejb-stateless-bean&gt; entry will
look at the bean's annotations to enhance the class.</p>

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

  &lt;env-entry env-entry-name="greeting"
             env-entry-type="java.lang.String"
             env-entry-value="Hello, World."/&gt;

  &lt;ejb-stateless-bean class="qa.TestBean"/>

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

<p>The &lt;ejb-stateless-bean&gt; can optionally configure the bean
directly with an &lt;init&gt; tag as described in the alternate
dependency injection section.</p>

</s1>

<s1 title="Client">

<example title="HelloServlet.java">
import javax.webbeans.In;

public class HelloServlet extends GenericServlet {
  @In private Hello _hello;

  public void service(HttpServletRequest req, HttpServletResponse res)
    throws IOException, ServletException
  {
    PrintWriter out = res.getWriter();
    
    out.println(_hello.hello());
  }
}
</example>

<s2 title="@EJB">

<p>The <a href="doc|webbeans-annotations.xtp#@In">@In</a> annotation tells
Resin to look for a <code>Hello</code> component in the WebBeans directory.
</p>

<p>The servlet could also lookup the Hello bean with JNDI in the
<code>init()</code> method or use an &lt;init&gt; configuration in the
web.xml:

<example title="alternative configuration">
&lt;servlet servlet-name="hello" servlet-class="example.HelloServlet"&gt;
  &lt;init hello="${HelloBean}"/&gt;
&lt;/servlet&gt;
</example>

</p></s2>

</s1>

</body>
</document>
