3 Implementing Session Beans

Implement the Session Bean

When you implement a session bean, create the following:

1. The home interfaces for the bean. The home interface defines the create method for your bean.

   1. The remote home interface extends javax.ejb.EJBHome.

   2. The local home interface extends javax.ejb.EJBLocalHome.

2. The component interfaces for the bean.

   1. The remote interface declares the methods that a client can invoke remotely. It extends javax.ejb.EJBObject.

   2. The local interface declares the methods that a collocated bean can invoke locally. It extends javax.ejb.EJBLocalObject.

3. The bean implementation includes the following:

   1. The implementation of the business methods that are declared in the component interfaces.

   2. The container callback methods that are inherited from the javax.ejb.SessionBean

   3. The ejb* methods that match the home interface create methods:

      • For stateless session beans, provide an ejbCreate method with no parameters.

      • For stateful session beans, provide an ejbCreate method with parameters matching those of the create method as defined in the home interfaces.

package hello;

import javax.ejb.*;
import java.rmi.*;

public interface HelloHome extends EJBHome
{
  public Hello create() throws CreateException, RemoteException;
}

package hello;

import javax.ejb.*;

public interface HelloLocalHome extends EJBLocalHome
{
 public HelloLocal create() throws CreateException, EJBException;
}

package hello;

import javax.ejb.*;
import java.rmi.*;

public interface Hello extends EJBObject
{
  public String sayHello(String myName) throws RemoteException;
}

package hello;

import javax.ejb.*;

public interface HelloLocal extends EJBLocalObject
{
  public String sayHello(String myName) throws EJBException;
}

package hello;

import javax.ejb.*;

public class HelloBean implements SessionBean
{
  public SessionContext ctx;

  public HelloBean()
  {    // constructor
  }

  public void ejbCreate() throws CreateException
  {   // when bean is created
  }

  public void ejbActivate()
  {    // when bean is activated
  }

  public void ejbPassivate()
  {    // when bean is deactivated
  }

  public void ejbRemove()
  {   // when bean is removed
  }

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

  public void unsetSessionContext()
  {    this.ctx = null;
  }

  public String sayHello(String myName) throws EJBException
  {
    return ("Hello " + myName);
  }
}

Create the Deployment Descriptor

After implementing and compiling your classes, you must create the standard J2EE EJB deployment descriptor for all beans in the module. The XML deployment descriptor (defined in the ejb-jar.xml file) describes the EJB module of the application. It describes the types of beans, their names, and attributes. The structure for this file is mandated in the DTD file, which is provided at " http://java.sun.com/dtd/ejb-jar_2_0.dtd".

Any EJB container services that you want to configure is also designated in the deployment descriptor. For information about data sources and JTA, see the Oracle Application Server Containers for J2EE Services Guide. For information about security, see the Oracle Application Server Containers for J2EE Security Guide.

After creation, place the deployment descriptors for the EJB application in the META-INF directory that is located in the same directory as the EJB classes. See Figure 3-1 for more information.

The following example shows the sections that are necessary for the Hello example, which implements both a remote and a local interface.

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd">

<ejb-jar>
   <display-name>hello</display-name>
   <description>
      An EJB app containing only one Stateless Session Bean
   </description>
   <enterprise-beans>
      <session>
         <description>no description</description>
         <display-name>HelloBean</display-name>
         <ejb-name>HelloBean</ejb-name>
         <home>hello.HelloHome</home>
         <remote>hello.Hello</remote>
         <local-home>hello.HelloLocalHome</local-home>
         <local>hello.HelloLocal</local>
         <ejb-class>hello.HelloBean</ejb-class>
         <session-type>Stateless</session-type>
         <transaction-type>Container</transaction-type>
      </session>
   </enterprise-beans>

   <assembly-descriptor>
      <container-transaction>
         <method>
            <ejb-name>HelloBean</ejb-name>
            <method-name>*</method-name>
         </method>
         <trans-attribute>Supports</trans-attribute>
      </container-transaction>
      <security-role>
         <role-name>users</role-name>
      </security-role>
   </assembly-descriptor>
</ejb-jar>

Archive the EJB Application

After you have finalized your implementation and created the deployment descriptors, archive your EJB application into a JAR file. The JAR file should include all EJB application files and the deployment descriptor.

For example, to archive your compiled EJB class files and XML files for the Hello example into a JAR file, perform the following in the ../hello/ejb_module directory:

% jar cvf helloworld-ejb.jar .

This archives all files contained within the ejb_module subdirectory within the JAR file.

Modify the Application.XML File

The application.xml file acts as the manifest file for the application and contains a list of the modules that are included within your enterprise application. You use each <module> element defined in the application.xml file to designate what comprises your enterprise application. Each module describes one of three things: EJB JAR, Web WAR, or any client files. Respectively, designate the <ejb>, <web>, and <java> elements in separate <module> elements.

• The <ejb> element specifies the EJB JAR filename.

• The <web> element specifies the Web WAR filename in the <web-uri> element, and its context in the <context> element.

• The <java> element specifies the client JAR filename, if any.

As Figure 3-1 shows, the application.xml file is located under a META-INF directory under the parent directory for the application. The JAR, WAR, and client JAR files should be contained within this directory. Because of this proximity, the application.xml file refers to the JAR and WAR files only by name and relative path—not by full directory path. If these files were located in subdirectories under the parent directory, then these subdirectories must be specified in addition to the filename.

Figure 3-1 Archive Directory Format

Description of the illustration primer3.gif

For example, the following example modifies the <ejb>, <web>, and <java> module elements within application.xml for the Hello EJB application that also contains a servlet that interacts with the EJB.

<?xml version="1.0"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN" "http://java.sun.com/j2ee/dtds/application_1_2.dtd">
<application>
  <display-name>helloworld j2ee application</display-name>
  <description>
     A sample J2EE application that uses a Helloworld Session Bean
     on the server and calls from java/servlet/JSP clients.
  </description>
  <module>
    <ejb>helloworld-ejb.jar</ejb>
  </module>
  <module>
    <web>
      <web-uri>helloworld-web.war</web-uri>
      <context-root>/helloworld</context-root>
    </web>
  </module>
  <module>
    <java>helloworld-client.jar</java>
  </module>
</application>

Create the EAR File

Create the EAR file that contains the JAR, WAR, and XML files for the application. Note that the application.xml file serves as the EAR manifest file.

To create the helloworld.ear file, execute the following in the hello directory contained in Figure 3-1:

% jar cvf helloworld.ear . 

This step archives the application.xml, the helloworld-ejb.jar, the helloworld-web.war, and the helloworld-client.jar files into the helloworld.ear file.

Object Types Enabled for Passivation

For serialization (during passivation) to the secondary storage to be successful, the conversational state of a bean must consist of only primitive values and the following special types:

• serializable objects

• null

• a reference to a component interface (EJBObject or EJBLocalObject)

• a reference to a home interface (EJBHome or EJBLocalHome)

• a reference to the SessionContext object

• a reference to the environment naming context

• a reference to the UserTransaction interface

• a reference to a resource manager connection factory

The bean developer is responsible for ensuring that all fields are of these types within the ejbPassivate() method. Any transient or non-serializable field should be set to null in this method.

Storage of Passivated EJBs

When OC4J passivates the stateful session bean, it is placed in the directory and filename designated by the persistence-filename attribute of the <session-deployment> element in the OC4J deployment descriptor. Passivation uses space within this directory to store the passivated beans. The default is the application-deployments/persistence directory. If passivation allocates large amounts of disk space, you may need to change the directory to a place on your system where you have the space available or turn off passivation.