Creating Enterprise JavaBeans

To create an EJB, you must perform the following steps:

1. Create a remote interface for the bean. The remote interface declares the methods that a client can invoke. It must extend javax.ejb.EJBObject.

2. Create a home interface for the bean. The home interface must extend javax.ejb.EJBHome. In addition, it defines the create method for your bean.

3. Implement the bean. This includes the following:
   1. The implementation for the methods declared in your remote interface.

   2. The methods defined in either the javax.ejb.SessionBean or javax.ejb.EntityBean interfaces. For the differences between these types of beans, see "Definition of an Entity Bean".

   3. The ejbCreate method with parameters matching those of the create method defined of the home interface.

4. Create the bean deployment descriptor. The deployment descriptor specifies properties for the bean. See Chapter 4, "Creating Deployment Files".

5. Create an ejb-jar file containing the bean, the remote and home interfaces, and the deployment descriptor. The ejb-jar file must define all beans within your application. Refer to Chapter 4, "Creating Deployment Files" for more details.

Requirements for Remote and Home Interface Implementation

Requirement	Description
RMI conformance	Because the javax.ejb.EJBObject and javax.ejb.EJBHome interfaces extend java.rmi.Remote, they must be compliant with the Remote Method Invocation (RMI) specification. This means that their methods can only use the data types allowed in RMI, and that methods in both interfaces must throw the java.rmi.RemoteException exception. You can get the RMI specifications from the JavaSoft site, http://www.javasoft.com.
Naming conventions	The interface names, method names, and constants defined within these interfaces cannot start with an underbar (_) or contain a dollar sign ($). In addition, the application and bean names can include the slash sign (/).

Creating the Remote Interface

The remote interface of a bean provides an interface for the methods that the client will invoke. That is, the remote interface defines the methods that you implement for remote access.

1. The bean's remote interface must extend the javax.ejb.EJBObject interface, which has the following definition:

   public interface javax.ejb.EJBObject extends java.rmi.Remote {
   
         public abstract EJBHome getEJBHome()
   
   	throws java.rmi.RemoteException   // returns reference to home 
   
   		 // interface for this bean
   
         public abstract Handle getHandle()
   
   	throws java.rmi.RemoteException // returns serializeable handle 
   
         public abstract Object getPrimaryKey()
   
   	throws java.rmi.RemoteException // returns key to an entity bean
   
         public abstract boolean isIdentical(EJBObject obj)
   
   	throws java.rmi.RemoteException
   
         public abstract void remove()
   
   	throws java.rmi.RemoteException, RemoveException //remove EJB object
   
   }
   
   
   

   You do not need to implement the methods in the EJBObject interface; these methods are implemented for you by the container.

   Function	Description
   getEJBHome()	Retrieves the object reference for the home interface associated with this particular bean. Note that you cannot typecast the returned object to the home interface type. See "Using the getEJBHome Method" for more information.
   getHandle()	A serializable Java representation of the EJB object reference can be obtained using the getHandle method of the remote interface. The handle can be serialized and used to re-establish a connection to the same object. With session beans, the connection is re-established as long as the bean instance is still active; with entity beans, the connection is re-established irregardless of whether the bean is active or not. You use the getEJBObject method within the Handle class to retrieve the bean instance.
   getPrimaryKey()	The getPrimaryKey method retrieves the primary key associated with the EJB EntityBean.
   isIdentical()	Tests that the object calling this method and the object in the argument are identical (as far as the container is concerned). This identifies that both objects are the same for all purposes.
   remove()	Deactivates the EJB bean. This, in turn, destroys the session bean instance (if stateful).

2. The signature for each method in the remote interface must match the signature in the bean implementation.

3. The remote interface must be declared as public.

4. You do not declare public variables in the remote interface. Only the public methods are declared.

5. Any exception can be thrown to the client, as long as it is serializable. Runtime exceptions are transferred back to the client as a remote runtime exception.

Example

The following code sample shows a remote interface called Employee, which declares the getEmployee method, which will be implemented in the bean.

package employee;

import employee.EmpRecord;
import javax.ejb.EJBObject;
import java.rmi.RemoteException;

public interface Employee extends EJBObject  {
  public EmpRecord getEmployee (int empNumber)
       throws java.sql.SQLException, EmpException, RemoteException;
}

Creating the Home Interface

The home interface should define the appropriate create method for your bean. The home interface specifies one or more create methods. For each create method, a corresponding ejbCreate method must be defined in the remote interface. All of the create methods return the bean type; all of the ejbCreate methods return void.

The client invokes the create method declared within the home interface. The container turns around and calls the ejbCreate method, with the appropriate parameter signature, within your bean implementation. The parameter arguments can be used to initialize the state of a new EJB object.

1. The home interface must extend the javax.ejb.EJBHome interface which has the following definition:

   public interface javax.ejb.EJBHome extends java.rmi.Remote {
         public abstract EJBMetaData getEJBMetaData();
         public abstract void remove(Handle handle);
         public abstract void remove(Object primaryKey);
   

   }

   The methods in the EJBHome interface are implemented by the container. A client can remove an EJB object using the remove methods defined in either of its home or remote interfaces.

2. A bean's home interface can also be used to retrieve metadata information about the bean through the javax.ejb.EJBMetaData interface or remove the bean instance, given a handle.

3. All create methods must throw the following exceptions:
   • javax.ejb.CreateException

   • either java.rmi.RemoteException or javax.ejb.EJBException

     Note: The deployejb tool publishes a reference to the home object in the database. See the Oracle8i Java Tools Reference for a full description of deployejb.

Example

The following code sample shows a home interface called EmployeeHome. The create method contains no arguments.

package employee;

import javax.ejb.EJBObject;
import java.rmi.RemoteException;

public interface EmployeeHome extends EJBHome {
  public Employee create()
       throws CreateException, RemoteException;
}

Creating the Exception Class

Some methods in the Employee class can throw the EmpException exception. For an exception to be transported from the object to the client, you need to define a class for the exception.

The following code defines an exception class and is found in EmpException.java.

package employee;

public class EmpException extends RemoteException
{
  public EmpException(String msg)
  {
   super(msg);
  }
}

---