<document>
  <header>
    <product>resin-ee</product>
    <title>Resin EJB 3.0</title>
    <type>contents</type>

    <description><p>Resin's EJB support is integrated
    with <a href="resin-ioc.xtp">Resin IoC</a>.  This integration means
    plain Java beans can use EJB annotations and interception, EJBs can
    use Resin IoC annotations, and both kinds of beans can be configured
    directly from the <code>resin-web.xml</code> or discovered by classpath
    scanning.</p>
    </description>

  </header>

  <body>

<localtoc/>

<s1 title="See Also">
<ul>
  <li>For persistence, see <a href="amber.xtp">Amber</a>.</li>
  <li><a href="resin-ioc.xtp">Resin IoC</a> for more information on dependency injection.</li>
  <li>See <a href="../examples/ejb-stateless/index.xtp">session tutorial</a></li>
</ul>
</s1>

<s1 title="Overview">

<p>Resin's EJB support is integrated with <a href="resin-ioc.xtp">Resin
IoC</a>.  This integration means plain Java beans can use EJB annotations
and interception, EJBs can use Resin IoC annotations, and both kinds of
beans can be configured directly from the <code>resin-web.xml</code>
or discovered by classpath scanning.</p>

<p>So it's best to think of EJBs as a set of orthogonal capabilities that
are available to any registered bean.  The basic capability types are:</p>

<ul>
<li><b>Lifecycle model:</b> Java, <code>@Stateless</code>, <code>@Stateful</code>,
or <code>@MessageDriven</code>.
Resin-managed objects like Servlets and Filters are POJO model beans.</li>
<li><b>Dependency injection:</b> injection annotations <code>@In</code>, <code>@Named</code>, <code>@EJB</code>, <code>@PersistenceUnit</code>, etc are
available to all beans.</li>
<li><b>Registration:</b> all beans are registered in a unified typed-namespace
registry (i.e. the registration half of dependency injection.)</li>
<li><b>Lifecycle events:</b> the <code>@PostConstruct</code> and <code>@PreDestroy</code></li>
<li><b>Predefined aspects:</b> the <code>@TransactionAttribute</code>, <code>@RunAs</code>, <code>@RolesAllowed</code>, etc. annotations are
available to all beans.</li>
<li><b>Custom interceptors:</b> EJB-style <code>@AroundInvoke</code>, and <code>@Interceptors</code>, as well
as WebBeans-style <code>@Interceptor</code> and <code>@InterceptorBindingType</code> are available to all beans.</li>
<li><b>Event handling:</b> the WebBeans <code>@Observes</code> capability is available to all beans.</li>
</ul>
</s1>

<s1 title="Hello, World">

<p>The Hello, World example is the smallest example deploying and using
a <code>@Stateless</code> session bean.  The bean is configured in
the <code>resin-web.xml</code> and used in <code>MyServlet</code> with
the WebBeans <code>@In</code> providing dependency injection.</p>

<example title="Example: Bean.java">
package demo;

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

<example title="Example: @Stateless MyBean.java">
package demo;

import javax.ejb.*;

@Stateless
public class MyBean implements Bean {
  public String hello()
  {
    return "hello, world";
  }
}
</example>

<example title="Example: MyServlet.java">
package demo;

import java.io.*;
import javax.servlet.*;
import javax.webbeans.*;

public MyServlet extends GenericServlet {
  @In private Bean _bean;

  public void service(ServletRequest, ServletResponse res)
    throws ServletException, IOException
  {
    PrintWriter out = res.getWriter();

    out.println(_bean.hello());
  }
}
</example>

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

  &lt;bean class="demo.MyBean"/>

  &lt;servlet-mapping url-pattern="/test"
                   servlet-class="demo.MyServlet"/>

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

</s1>

<s1 title="EJB Models">

<p>Resin's EJB integration provides four lifecycle choices: plain Java,
<code>@Stateless</code>, <code>@Stateful</code>, and <code>@MessageDriven</code>.</p>

<ul>
<li>Java: multithreaded, single instance, with no special method calling code by default, e.g. Servlets, Filters or <code>@Component</code> instances.</li>
<li><code>@Stateless</code>: pooled instances, each is single-threaded,
REQUIRED transactions and classloader environment enabled by default.</li>
<li><code>@Stateful</code>: enforced single-threaded instances.
REQUIRED transactions and classloader environment enabled by default.
Only <code>@Stateful</code> beans can implement the
<code>SessionSynchronization</code> interface.</li>
<li><code>@MessageDriven</code>: pool instances, each single-threaded,
specifically tailored for JMS/Messaging tasks
(See <a href="resin-messaging">Resin messaging</a>.) REQUIRED transactions
and classloader environment enabled by default.</li>
</ul>

<s2 title="Java">

<p>A Java bean is a multithreaded instance, e.g. a servlet or filter.
Because it's multithreaded, application developers must take extra care
to handle their own synchronization.  In particular, threads must
not store thread-specific data in Java bean fields and should generally
avoid using static fields.</p>

<p>Java beans can use all the EJB and
<a href="resin-ioc.xtp">Resin-IoC</a> aspects, including
<code>@TransactionAttribute</code>, can use EJB <code>@Interceptor</code>
classes, and Resin-Ioc <code>@InterceptorBinding</code>.  They can handle
events with the <code>@Observes</code> annotation, and add lifecycle
callbacks with <code>@PostConstruct</code> and <code>@PreDestroy</code>.</p>

</s2>

<s2 title="@Local">

<p>The <code>@Local</code> annotation marks an interface of a bean as the
exposed proxy API.  Since <code>@Stateless</code> and <code>@Stateful</code>
beans are proxy-based, they need an interface to expose to users of the
bean.  If the bean implements exactly in interface, it's chosen by default,
otherwise the developer needs to mark the interface to export.</p>

<deftable title="Local attributes">
<tr>
  <th>Field</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>Lists the interfaces to export for the bean.</td>
  <td></td>
</tr>
</deftable>

<def title="javax.ejb.Local">
@Target(TYPE)
@Retention(RUNTIME)
public @interface Local {
  Class []value() default {};
}
</def>

</s2>

<s2 title="@MessageDriven">

<p>MessageDriven beans receive messages from a Queue, using a pooled,
single-threaded model like @Stateless beans.</p>

<p>See <a href="resin-messaging.xtp">Resin messaging</a> for more information.</p>

<p>The MessageDriven bean connects with the messaging provider through
an <a href="http://wiki.caucho.com/ActivationSpec">ActivationSpec</a>.
For JMS, the activation spec specifies the JMS Queue.</p>

<deftable title="MessageDriven attributes">
<tr>
  <th>Field</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>activationConfig</td>
  <td>Default properties for the ActivationSpec, e.g. the
JMS Queue name or destination type.</td>
  <td></td>
</tr>
<tr>
  <td>description</td>
  <td>An optional description of the bean, typically for the benefit of administration</td>
  <td></td>
</tr>
<tr>
  <td>mappedName</td>
  <td>An optional provider-specific name.  Resin doesn't use this</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td>The EJB's name</td>
  <td>The classname of the bean</td>
</tr>
<tr>
  <td>messageListenerInterface</td>
  <td>Defines the interface to be used to receive messages.  The interface
will match the messaging-provider's API, e.g. JMS
uses <code>javax.jms.MessageListener</code>.</td>
  <td></td>
</tr>
</deftable>

<def title="javax.ejb.MessageDriven">
@Target(TYPE)
@Retention(RUNTIME)
public @interface Stateful {
  String name() default "";
  Class messageListenerInterface() default Object.class;
  ActivationConfigProperty []activationConfig() default {};
  String mappedName() default "";
  String description() default "";
}
</def>

</s2>

<s2 title="@Remote">

<p>The <code>@Local</code> annotation marks an interface of a bean as the
exposed proxy API for remoting.  See <a href="resin-remoting.xtp">Resin
remoting</a> for more information on exposing beans as remote objects
for protocols such as Hessian, Burlap, and SOAP.</p>

<deftable title="Remote attributes">
<tr>
  <th>Field</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>Lists the interfaces to export for the bean.</td>
  <td></td>
</tr>
</deftable>

<def title="javax.ejb.Remote">
@Target(TYPE)
@Retention(RUNTIME)
public @interface Remote {
  Class []value() default {};
}
</def>

</s2>

<s2 title="SessionSynchronization">

<p>The <code>SessionSynchronization</code> interfaces tells Resin to
enlist a <code>@Stateful</code> session bean in the current transaction.
Before the transaction starts its commit processing, the bean will receive
a callback message, allowing it to coordinate any data persistence.  When
the transaction either commits or rollsback, the bean will receive another
callback indicating success or failure, allowing the bean to complete
any transaction processing.</p>

<p>Only <code>@Stateful</code> session beans can
implement <code>SessionSynchronization</code> because the bean itself will
be registered with the transaction.  The unique capability makes
stateful session beans valuable for transaction processing.</p>

<deftable title="SessionSynchronization methods">
<tr>
  <th>Method</th>
  <th>Description</th>
</tr>
<tr>
  <td>afterBegin</td>
  <td>Called when the transaction starts</td>
</tr>
<tr>
  <td>beforeCompletion</td>
  <td>The transaction will call <code>beforeCompletion</code> before it
starts the two-phase commit, allowing the bean to flush any cached data
if necessary.</td>
</tr>
<tr>
  <td>afterCompletion</td>
  <td>The transaction will call <code>afterCompletion</code>
when the transaction completes, reporting whether the transaction
completed with a successful commit or a rollback.
</td>
</tr>
</deftable>

<def title="javax.ejb.SessionSynchronization">
public interface SessionSynchronization {
  public void afterBegin()
    throws EJBException, RemoteException;
  
  public void beforeCompletion()
    throws EJBException, RemoteException;
  
  public void afterCompletion(boolean committed)
    throws EJBException, RemoteException;
}
</def>

</s2>

<s2 title="@Stateful">

<p>A stateful session bean is a single-threaded instance.  Applications
will need to create a new stateful instance for each thread or request.</p>

<deftable title="Stateful attributes">
<tr>
  <th>Field</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>description</td>
  <td>An optional description of the bean, typically for the benefit of administration</td>
  <td></td>
</tr>
<tr>
  <td>mappedName</td>
  <td>An optional provider-specific name.  Resin doesn't use this</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td>The EJB's name used for jndi and Resin IoC registration</td>
  <td>The classname of the bean</td>
</tr>
</deftable>

<def title="javax.ejb.Stateful">
@Target(TYPE)
@Retention(RUNTIME)
public @interface Stateful {
  String name() default "";
  String mappedName() default "";
  String description() default "";
}
</def>
</s2>

<s2 title="@Stateless">

<p>A stateless session bean is a pooled proxy, where each request gets
its own bean instance.</p>

<deftable title="Stateless attributes">
<tr>
  <th>Field</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>description</td>
  <td>An optional description of the bean, typically for the benefit of administration</td>
  <td></td>
</tr>
<tr>
  <td>mappedName</td>
  <td>An optional provider-specific name.  Resin doesn't use this</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td>The EJB's name used for jndi and Resin IoC registration</td>
  <td>The classname of the bean</td>
</tr>
</deftable>

<def title="javax.ejb.Stateless">
@Target(TYPE)
@Retention(RUNTIME)
public @interface Stateless {
  String name() default "";
  String mappedName() default "";
  String description() default "";
}
</def>
</s2>

</s1>

<s1 title="Aspect Annotations">

<s2 title="@AroundInvoke">

<p><code>@AroundInvoke</code> marks an interception method on the
bean or an interceptor class.  The interceptor is invoked while
processing a business method.</p>

<def title="javax.interceptor.AroundInvoke">
@Target(METHOD)
@Retention(RUNTIME)
public @interface AroundInvoke {
}
</def>

<example title="Example: @AroundInvoke method">
import javax.interceptor.*;

public class MyBean {
  @AroundInvoke
  protected Object log(InvocationContext cxt)
    throws Exception
  {
    System.out.println("Before: " + cxt.getMethod());

    Object value = cxt.proceed();

    System.out.println("After: " + cxt.getMethod());

    return value;
  }

  public String hello()
  {
    return "hello, world";
  }
}
</example>

</s2>

<s2 title="@DenyAll">

<p><code>@DenyAll</code> annotation marks a method as forbidden to all
users.</p>

<def title="javax.annotation.security.DenyAll">
@Target({METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface DenyAll {
}
</def>
</s2>

<s2 title="@Interceptor">

<p><code>@Interceptor</code> marks a class as an interceptor using
WebBeans-style interception.  The class will normally also have
an <code>@AroundInvoke</code> method as well as any
<code>InterceptorBindingType</code> annotations.</p>

<def title="javax.webbeans.Interceptor">
@Target({TYPE})
@Retention(RUNTIME)
public @interface Interceptor {
}
</def>

</s2>

<s2 title="@InterceptorBindingType">

<p><code>@InterceptorBindingType</code> is a WebBeans meta-annotation for
creating interceptor binding types.  Applications will use
<code>@InterceptorBindingType</code> to create application-specific
interceptors.  The WebBeans-style of interception decouples the
interception declaration from the interceptor classes, in contrast
with the EJB-style which specifies the interceptor class directly.</p>

<def title="javax.webbeans.InterceptorBindingType">
@Target({TYPE})
@Retention(RUNTIME)
public @interface InterceptorBindingType {
}
</def>

</s2>

<s2 title="@Interceptors">

<p><code>@Interceptors</code> marks an method or class as being
intercepted by the named classes.  The interceptor classes will
implement an <code>@AroundInvoke</code> method to process the
<code>InvocationContext</code>.</p>

<deftable title="@Interceptors properties">
<tr>
  <th>Value</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>Lists the interceptor classes to apply to the method.</td>
</tr>
</deftable>

<def title="javax.interceptor.Interceptors">
@Target({TYPE,METHOD})
@Retention(RUNTIME)
public @interface Interceptors {
  public Class []value();
}
</def>

<example title="Example: @Interceptor method">
import javax.interceptor.*;

public class MyBean {
  @Interceptors(MyInterceptor.class)
  public String hello()
  {
    return "hello, world";
  }
}

public class MyInterceptor {
  @AroundInvoke
  protected Object log(InvocationContext cxt)
    throws Exception
  {
    System.out.println("Before: " + cxt.getMethod());

    Object value = cxt.proceed();

    System.out.println("After: " + cxt.getMethod());

    return value;
  }
}
</example>

</s2>

<s2 title="InvocationContext">

<p>The <code>InvocationContext</code> API is used by invocation
methods to examine the calling context, and possibly set parameters.
A no-op interceptor would just call the <code>proceed()</code> method.</p>

<deftable title="InvocationContext methods">
<tr>
  <th>Method</th>
  <th>Description</th>
</tr>
<tr>
  <td>getContextData</td>
  <td>Returns a map containing any context information</td>
</tr>
<tr>
  <td>getMethod</td>
  <td>Returns the called API method</td>
</tr>
<tr>
  <td>getParameters</td>
  <td>Returns the Java parameters for the call</td>
</tr>
<tr>
  <td>getTarget</td>
  <td>Returns the target object, i.e. the Java object that will
receive the call after all the interceptors complete.</td>
</tr>
<tr>
  <td>proceed</td>
  <td>Call the next interceptor in the chain, or call the final object
at the end of the chain.</td>
</tr>
<tr>
  <td>setParameters</td>
  <td>Sets the Java parameters for the call</td>
</tr>
</deftable>

<def title="javax.interceptor.InvocationContext">
public interface InvocationContext {
  public Object proceed() throws Exception;

  public Map&lt;String, Object> getContextData();
  public Method getMethod();
  public Object[] getParameters() throws IllegalStateException;
  public void setParameters(Object[] parameters) throws IllegalStateException;
  public Object getTarget();
}
</def>
</s2>

<s2 title="@PermitAll">

<p><code>@PermitAll</code> annotation marks a method as allowed for all
users.</p>

<def title="javax.annotation.security.PermitAll">
@Target({METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface PermitAll {
}
</def>
</s2>

<s2 title="@RolesAllowed">

<p><code>@RolesAllowed</code> lists all the roles (i.e. permissions) allowed
to access the method.  If the user in the security context does not match
the role, an exception will be thrown.</p>

<deftable title="RolesAllowed properties">
<tr>
  <th>Value</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>Lists the roles (permissions) that are allowed.</td>
</tr>
</deftable>

<def title="javax.annotation.security.RolesAllowed">
@Target({TYPE,METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RolesAllowed {
  String []value();
}
</def>
</s2>

<s2 title="@RunAs">

<p><code>@RunAs</code> changes the security context user to a defined
role.  Security tests within the context of the <code>@RunAs</code> will
match the specified role.</p>

<deftable title="RunAs properties">
<tr>
  <th>Value</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>The role name to run as.</td>
</tr>
</deftable>

<def title="javax.annotation.security.RunAs">
@Target({TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RunAs {
  String value();
}
</def>
</s2>

<s2 title="@TransactionAttribute">

<p>Defines the transaction boundary for business methods.  The
default value is REQUIRED.  If @TransactionAttribute annotates the class,
it defines the default value. </p>

<p>All Resin-managed beans can use <code>@TransactionAttribute</code>:
@Stateful, @Stateless, @MessageDriven and plain Java beans.</p>

<deftable title="TransactionAttributeType">
<tr>
  <th>Value</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>
<tr>
  <td>MANDATORY</td>
  <td>Require the caller to have started a transaction</td>
</tr>
<tr>
  <td>NEVER</td>
  <td>Forbid the caller to have started a transaction</td>
</tr>
<tr>
  <td>REQUIRESNEW</td>
  <td>Always start a new transaction, suspending the old one</td>
</tr>
<tr>
  <td>NOTSUPPORTED</td>
  <td>Suspend any active transaction</td>
</tr>
</deftable>

<ul>
<li>SUPPORTS is typically used for read-only methods</li>
<li>REQUIRED is typically used for updating (read/write) methods</li>
</ul>

<def title="javax.ejb.TransactionAttribute">
@Target({TYPE,METHOD})
@Retention(RUNTIME)
public @interface TransactionAttribute {
  TransactionAttributeType value() default REQUIRED;
}
</def>

</s2>

</s1>

<s1 title="Dependency Injection Annotations">

<s2 title="@EJB" type="defun">

<p>Configures an EJB values for a field or method.</p>

<p>@EJB is essentially a @Resource where it's known that the
result is an EJB interface.</p>

<deftable-childtags>
<tr><td>jndiName</td><td>The jndi name of the resource</td><td>The field name
</td></tr></deftable-childtags>

<def title="javax.ejb.EJB">
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface EJB {
  String name() default "";
  String businessInterface() default "";
  String jndiName() default "";
}
</def>

<p>In the following exaple, Resin will call <code>setFoo</code>
method with the bean in "java:comp/env/ejb/foo" before the
session is started.</p>

<example title="Example: @EJB method injection">
@EJB
void setFoo(example.Test test)
{
  _test = test;
}
</example>

</s2>

<s2 title="@Resource" type="defun">

<p><code>@Resource</code> provides JNDI-based resource injection.
<code>@Resource</code> can also be used at the Class level to
declare a dependency in cases where the session bean loads the
JNDI value by itself.</p>

<p>In general, it's better to use the WebBeans
annotations: <code>@In</code>, <code>@Named</code>
or custom <code>@BindingType</code> annotations, since they use the
type-safe WebBeans registry instead of JNDI.  <code>@Resource</code>
is supported for backwards compatibility.</p>

<deftable-childtags>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>authenticationType</td>
  <td>What kind of authentication is expected for the resource: APPLICATION or
CONTAINER</td>
  <td>CONTAINER</td>
</tr>
<tr>
  <td>description</td>
  <td>An optional description of the resource</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td>The jndi-name of the resource</td>
  <td>java:comp/env/<var>class-name</var>#<var>field-name</var></td>
</tr>
<tr>
  <td>type</td>
  <td>The class of the expected resource</td>
  <td>The field type</td>
</tr>
<tr>
  <td>shareable</td>
  <td>True if the bean follows JCA shareability requirements.</td>
  <td>true</td>
</tr>
<tr>
  <td>mappedName</td>
  <td>The produce-specific name of the resource</td>
  <td>The field name</td>
</tr>
</deftable-childtags>

<def title="javax.ejb.Resource">
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface Resource {
  AuthenticationType authenticationType() CONTAINER;
  String description() default "";
  String mappedName() default "";
  String name() default "";
  boolean shareable() default true;
  Class&lt;?> type() default Object.class;
}
</def>

<p>In the following exaple, Resin will call <code>setDataSource</code>
method with the data source in "java:comp/env/jdbc/test" before the
session is started.  The "java:comp/env/jdbc" full name
is inferred from the DataSource type.</p>

<deftable title="default JNDI names">
<tr>
  <th>Resource Type</th>
  <th>JNDI Prefix</th>
</tr>
<tr>
  <td>javax.sql.DataSource</td>
  <td>java:comp/env/jdbc</td>
</tr>
<tr>
  <td>javax.mail.*</td>
  <td>java:comp/env/mail</td>
</tr>
<tr>
  <td>javax.ejb.EntityManager</td>
  <td>java:comp/EntityManager</td>
</tr>
<tr>
  <td>javax.transaction.UserTransaction</td>
  <td>java:comp/UserTransaction</td>
</tr>
<tr>
  <td>javax.ejb.EJBHome</td>
  <td>java:comp/env/ejb</td>
</tr>
<tr>
  <td>javax.jms.*</td>
  <td>java:comp/env/jms</td>
</tr>
</deftable>

<example>
@Resource(name="test")
void setDataSource(javax.sql.DataSource dataSource)
{
  _dataSource = dataSource;
}
</example>

</s2>

</s1>

  </body>
</document>
