<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" xml:lang="en" xml:id="ejb2.session.desc"><info><title>EJB 2.1 Session Beans Description</title></info>
  

  <section xml:id="ejb2.session.intro"><info><title>Introduction</title></info>
    

    <para>A Session Bean is composed of the following parts, which are
    developed by the Enterprise Bean Provider:</para>

    <itemizedlist>
      <listitem><para>
         The 

        <emphasis role="bold">Component Interface</emphasis>

         is the client view of the bean. It contains all the "business methods" of the bean. 
      </para></listitem>

      <listitem><para>
         The 

        <emphasis role="bold">Home Interface</emphasis>

         contains all the methods for the bean life cycle (creation, suppression) used by the client application. 
      </para></listitem>

      <listitem><para>
         The 

        <emphasis role="bold">bean implementation class</emphasis>

         implements the business methods and all the methods (described in the EJB specification), allowing the bean to be managed in the container. 
      </para></listitem>

      <listitem><para>
         The 

        <emphasis role="bold">deployment descriptor</emphasis>

         contains the bean properties that can be edited at assembly or deployment time. 
      </para></listitem>
    </itemizedlist>

    <para>Note that, according to the EJB 2.1 specification, the couple
    "Component Interface and Home Interface" may be either local or remote.
    <emphasis role="bold">Local Interfaces</emphasis> (Home and Component) are
    to be used by a client running in the same JVM as the EJB component.
    Create and finder methods of a local or remote home interface return local
    or remote component interfaces respectively. An EJB component can have
    both remote and local interfaces, even if typically only one type of
    interface is provided.</para>

    <para>The description of these elements is provided in the following
    sections.</para>

    <note>
      <para>in this documentation, the term "Bean" always means "Enterprise
      Bean."</para>
    </note>

    <para>A session bean object is a short-lived object that executes on
    behalf of a single client.There are <emphasis role="bold">stateless</emphasis> and <emphasis role="bold">stateful
    session beans</emphasis>. Stateless beans do not maintain state across
    method calls. Any instance of stateless beans can be used by any client at
    any time. Stateful session beans maintain state within and between
    transactions. Each stateful session bean object is associated with a
    specific client. A stateful session bean with container-managed
    transaction demarcation can optionally implement the <emphasis role="bold">SessionSynchronization </emphasis>interface. In this case, the
    bean objects will be informed of transaction boundaries. A rollback could
    result in a session bean object's state being inconsistent; in this case,
    implementing the SessionSynchronization interface may enable the bean
    object to update its state according to the transaction completion
    status.</para>
  </section>

  <section xml:id="ejb2.session.home"><info><title>The Home Interface</title></info>
    

    <para>A Session bean's home interface defines one or more
    <methodname>create(...)</methodname> methods. Each
    <methodname>create</methodname> method must be named create and must match
    one of the <methodname>ejbCreate</methodname> methods defined in the
    enterprise Bean class. The return type of a
    <methodname>create</methodname> method must be the enterprise Bean's
    remote interface type. The home interface of a stateless session bean must
    have one <methodname>create</methodname> method that takes no arguments.
    All the exceptions defined in the throws clause of an
    <methodname>ejbCreate</methodname> method must be defined in the throws
    clause of the matching <methodname>create</methodname> method of the home
    interface. A remote home interface extends the
    <interfacename>javax.ejb.EJBHome</interfacename>
    interface, while a local home interface extends the
    <interfacename>javax.ejb.EJBLocalHome</interfacename>
    interface.</para>

    <section><info><title>Example</title></info>
      

      <para>The following examples use a Session Bean named Op.</para>

      <para> <screen>   public interface OpHome extends EJBHome {
        Op create(String user) throws CreateException, RemoteException;
    }</screen> A local home interface could be defined as follows (LocalOp
      being the local component interface of the bean):<screen>
    public interface LocalOpHome extends EJBLocalHome {
        LocalOp create(String user) throws CreateException;
    }</screen></para>
    </section>
  </section>

  <section xml:id="ejb2.session.component"><info><title>The Component Interface</title></info>
    

    <para>The Component Interface is the client's view of an instance of the
    session bean. This interface contains the business methods of the
    enterprise bean. The interface must extend the
    <interfacename>javax.ejb.EJBObject</interfacename>
    interface if it is remote, or the
    <interfacename>javax.ejb.EJBLocalObject</interfacename>
    if it is local. The methods defined in a remote component interface must
    follow the rules for Java RMI (this means that their arguments and return
    value must be valid types for java RMI, and their throws clause must
    include the <classname>java.rmi.RemoteException</classname>). For each
    method defined in the component interface, there must be a matching method
    in the enterprise Bean's class (same name, same arguments number and
    types, same return type, and same exception list, except for
    RemoteException). </para>

    <section><info><title>Example</title></info>
      

      <para><screen>    public interface Op extends EJBObject {
        public void buy (int Shares)  throws RemoteException;
        public int  read ()           throws RemoteException;
    }
    </screen> The same type of component interface could be defined as a local
      interface (even if it is not considered good design to define the same
      interface as both local and remote): <screen>  public interface LocalOp extends EJBLocalObject {
        public void buy (int Shares);
        public int  read ();
    }</screen> </para>
    </section>
  </section>

  <section xml:id="ejb2.session.bean"><info><title>The Enterprise Bean Class</title></info>
    

    <para>This class implements the Bean's business methods of the component
    interface and the methods of the
    <interfacename>SessionBean</interfacename>
    interface, which are those dedicated to the EJB environment. The class
    must be defined as public and may not be abstract. The Session Bean
    interface methods that the EJB provider must develop are the
    following:</para>

    <itemizedlist>
      <listitem>
        <para>public void
        <methodname>setSessionContext</methodname>(SessionContext ic);</para>

        <para>This method is used by the container to pass a reference to the
        SessionContext to the bean instance. The container invokes this method
        on an instance after the instance has been created. Generally, this
        method stores this reference in an instance variable.</para>
      </listitem>

      <listitem>
        <para>public void <methodname>ejbRemove</methodname>();</para>

        <para>This method is invoked by the container when the instance is in
        the process of being removed by the container. Since most session
        Beans do not have any resource state to clean up, the implementation
        of this method is typically left empty.</para>
      </listitem>

      <listitem>
        <para>public void <methodname>ejbPassivate</methodname>();</para>

        <para>This method is invoked by the container when it wants to
        passivate the instance. After this method completes, the instance must
        be in a state that allows the container to use the Java Serialization
        protocol to externalize and store the instance's state.</para>
      </listitem>

      <listitem>
        <para>public void <methodname>ejbActivate</methodname>();</para>

        <para>This method is invoked by the container when the instance has
        just been reactivated. The instance should acquire any resource that
        it has released earlier in the ejbPassivate() method.</para>
      </listitem>
    </itemizedlist>

    <para>A stateful session Bean with container-managed transaction
    demarcation can optionally implement the
    <interfacename>javax.ejb.SessionSynchronization</interfacename>
    interface. This interface can provide the Bean with transaction
    synchronization notifications. The Session Synchronization interface
    methods that the EJB provider must develop are the following:</para>

    <itemizedlist>
      <listitem>
        <para>public void afterBegin();</para>

        <para>This method notifies a session Bean instance that a new
        transaction has started. At this point the instance is already in the
        transaction and can do any work it requires within the scope of the
        transaction.</para>
      </listitem>

      <listitem>
        <para>public void afterCompletion(boolean committed);</para>

        <para>This method notifies a session Bean instance that a transaction
        commit protocol has completed and tells the instance whether the
        transaction has been committed or rolled back.</para>
      </listitem>

      <listitem>
        <para>public void beforeCompletion();</para>

        <para>This method notifies a session Bean instance that a transaction
        is about to be committed.</para>
      </listitem>
    </itemizedlist>

    <section xml:id="ejb2.session.example"><info><title>Example</title></info>
      

      <para><screen>package sb;

import java.rmi.RemoteException;
import javax.ejb.EJBException;
import javax.ejb.EJBObject;
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;
import javax.ejb.SessionSynchronization;
import javax.naming.InitialContext;
import javax.naming.NamingException;

// This is an example of Session Bean, stateful, and synchronized.

public class OpBean implements SessionBean, SessionSynchronization {

    protected int total = 0;        // actual state of the bean
    protected int newtotal = 0;        // value inside Tx, not yet committed.
    protected String clientUser = null;
    protected SessionContext sessionContext = null;

    public void  ejbCreate(String user) {
        total = 0;
        newtotal = total;
        clientUser = user;
    }

    public void ejbActivate() {
        // Nothing to do for this simple example
    }    

    public void ejbPassivate() {
        // Nothing to do for this simple example
    }

    public void ejbRemove() {
        // Nothing to do for this simple example
    }

    public void setSessionContext(SessionContext sessionContext) {
        this.sessionContext = sessionContext;
    }

    public void afterBegin() {
        newtotal = total;
    }

    public void beforeCompletion() {
        // Nothing to do for this simple example

        // We can access the bean environment everywhere in the bean,
        // for example here!
        try {
            InitialContext ictx = new InitialContext();
            String value = (String) ictx.lookup("java:comp/env/prop1");
            // value should be the one defined in ejb-jar.xml
        } catch (NamingException e) {
            throw new EJBException(e);
        }
    }

    public void afterCompletion(boolean committed) {
        if (committed) {
            total = newtotal;
        } else {
            newtotal = total;
        }
    }

    public void buy(int s) {
        newtotal = newtotal + s;
        return;
    }

    public int read() {
        return newtotal;
    }
}
      </screen></para>
    </section>
  </section>

</section>