Developing Session Beans

You develop EJB components for the OC4J environment in the same way as in any other standard J2EE environment. Here are the steps to develop EJBs:

Implement the Session Bean—Develop your EJB with its home interfaces, component interfaces, and bean implementation
Create the Deployment Descriptor—Create the standard J2EE EJB deployment descriptor for all beans in your EJB application.
Archive the EJB Application—Archive your EJB files into a JAR file.

Implement the Session Bean

When you implement a session bean, create the following:

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

Creating the Home Interfaces

The home interfaces (remote and local) are used to create the bean instance; thus, they define the create method for your bean. The session bean can define the create method in the following ways:

EJB Type	Create Parameters
Stateless Session Bean	Can have only a single `create` method, with no parameters.
Stateful Session Bean	Can have one or more `create` methods, each with its own defined parameters.

For each create method, a corresponding ejbCreate method is defined in the bean implementation.

Remote Invocation

Any remote client invokes the EJB through its remote interface. The client invokes the create method that is declared within the remote home interface. The container passes the client call to the ejbCreate method—with the appropriate parameter signature—within the bean implementation. You can use the parameter arguments to initialize the state of the new EJB object.

The remote home interface must extend the javax.ejb.EJBHome interface.
All create methods may throw the following exceptions:
- javax.ejb.CreateException
- javax.ejb.EJBException or another RuntimeException

Example 3-1 Remote Home Interface for Session Bean

The following code sample illustrates a remote home interface for a stateless session bean called HelloHome.

package hello;

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

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

Local Invocation

An EJB can be called locally from a client that exists in the same container. Thus, a collocated bean, JSP, or servlet invokes the create method that is declared within the local home interface. The container passes the client call to the ejbCreate method—with the appropriate parameter signature—within the bean implementation. You can use the parameter arguments to initialize the state of the new EJB object.

The local home interface must extend the javax.ejb.EJBLocalHome interface.
All create methods may throw the following exceptions:
- javax.ejb.CreateException
- javax.ejb.EJBException or another RuntimeException

Example 3-2 Local Home Interface for Session Bean

The following code sample shows a local home interface for a stateless session bean called HelloLocalHome.

package hello;

import javax.ejb.*;

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

Creating the Component Interfaces

The component interfaces define the business methods of the bean that a client can invoke.

Creating the Remote Interface

The remote interface defines the business methods that a remote client can invoke. Here are the requirements for developing the remote interface:

The remote interface of the bean must extend the javax.ejb.EJBObject interface, and its methods must throw the java.rmi.RemoteException exception.
You must declare the remote interface and its methods as public for remote clients.
The remote interface, all its method parameters, and return types must be serializable. In general, any object that is passed between the client and the EJB must be serializable, because RMI marshals and unmarshals the object on both ends.
Any exception can be thrown to the client, as long as it is serializable. Runtime exceptions, including EJBException and RemoteException, are transferred back to the client as remote runtime exceptions.

Example 3-3 Remote Interface Example for Hello Session Bean

The following code sample shows a remote interface called Hello with its defined methods, each of which will be implemented in the stateless session bean.

package hello;

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

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

Creating the Local Interface

The local interface defines the business methods of the bean that a local (collocated) client can invoke.

The local interface of the bean must extend the javax.ejb.EJBLocalObject interface.
You declare the local interface and its methods as public.

Example 3-4 Local Interface for Hello Session Bean

The following code sample contains a local interface called HelloLocal with its defined methods, each of which will be implemented in the stateless session bean.

package hello;

import javax.ejb.*;

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

Implementing the Bean

The bean contains the business logic for your application. It implements the following methods:

The signature for each of these methods must match the signature in the remote or local interface, except that the bean does not throw the RemoteException. Since both the local and the remote interfaces use the bean implementation, the bean implementation cannot throw the RemoteException.
The lifecycle methods are inherited from the SessionBean interface. These include the ejb<Action> methods, such as ejbActivate, ejbPassivate, and so on.
The ejbCreate methods that correspond to the create method(s) that are declared in the home interfaces. The container invokes the appropriate ejbCreate method when the client invokes the corresponding create method.
Any methods that are private to the bean or package used for facilitating the business logic. This includes private methods that your public methods use for completing the tasks requested of them.

Example 3-5 Hello Stateless Session Bean Implementation

The following code shows the bean implementation for the Hello example.

Note:

You can download the stateless session bean example from the OC4J sample code page at http://www.oracle.com/technology/tech/java/oc4j/demos/ on the OTN Web site.

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);
  }
}

Note:

You can download this example on OTN from the OC4J sample code page at http://www.oracle.com/technology/tech/java/oc4j/demos/ on the OTN Web site.

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.

Example 3-6 XML Deployment Descriptor for Hello Bean

The following is the deployment descriptor for a version of the Hello example that uses a stateless session bean. This example defines both the local and remote interfaces. You do not have to define both interface types; you may define only one of them.

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

Note:

You can download this example on OTN from the OC4J sample code page at http://www.oracle.com/technology/tech/java/oc4j/demos/ on the OTN Web site.

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.

Note:

If you have included a Web application as part of this enterprise Java application, follow the instructions for building the Web application in the Oracle Application Server Containers for J2EE User's Guide .

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.