Oracle8i Enterprise JavaBeans Developer's Guide and Reference Release 3 (8.1.7) Part Number A83725-01 |
Library | Service | Contents | Index

## 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 Appendix A, "XML Deployment Descriptors".

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 Appendix A, "XML Deployment Descriptors" 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);
      }
    }

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index