Creating the home and remote interfaces

As an enterprise bean provider, you must create two interfaces for each bean: a home interface and a remote interface. The home interface defines the methods a client application uses to create, locate, and destroy instances of an enterprise bean. The remote interface defines the business methods implemented in the bean. A client accesses these methods through the remote interface.


Creating the home interface

The home interface of an enterprise bean controls the bean's life cycle. It contains the definition of the methods to create, find, and remove an instance of an enterprise bean.

As a bean provider, you must define the home interface, but you don't implement it. The EJB container does that, generating a home object that returns a reference to the bean.

It's customary to give the home interface the same name as the bean class with the suffix Home. For example, if the enterprise bean is named Account, the home interface for Account should be AccountHome. By default, a home interface generated by JBuilder's EJB wizards follows this convention, although you have the opportunity to modify the name of the interface while using the wizard if you choose.

The EJBHome base class

Each home interface extends the javax.ejb.EJBHome interface. Here is the complete definition of EJBHome:
package javax.ejb
public interface EJBHome extends java.rmi.Remote {
    void remove(Handle handle) throws java.rmi.RemoteException, RemoveException;
    void remove(Object primaryKey) throws java.rmi.RemoteException, RemoveException;
    EJBMetaData getEJBMetaData() throws RemoteException;
    HomeHandle getHomeHandle() throws RemoteException;
}
EJBHome has two remove() methods to remove enterprise bean instances. The first remove() method identifies the instance by a handle; the second by a primary key.

A handle, a serializable bean object identifier, has the same lifetime as the enterprise bean object it's referencing. For a session bean, the handle exists only as long as the session does. For an entity bean, the handle can persist and a client can use a serialized handle to reestablish a reference to the entity object it identifies.

A client would use the second remove() method to remove an entity bean instance using its primary key.

The getEJBMetaData() returns the EJBMetaData interface of the enterprise bean object. This interface allows the client to obtain metadata information about the bean. Its purpose is to be used by development tools that build applications that use deployed enterprise beans.

Note that the EJBHome interface doesn't have any methods for creating or locating instances of an enterprise bean. Instead, you must add these methods to the home interfaces you develop for your beans. Because session beans and entity beans have different life cycles, the methods defined in their home interfaces differ.

Creating a home interface for a session bean

A session bean almost always has a single client (except occasionally for stateless session beans). When a client creates a session bean, that session bean instance exists for the use of that client only.

To create a home interface for a session bean,

When you use the JBuilder's Enterprise JavaBean wizard, JBuilder creates a home interface with one defined create() method at the same time it creates the enterprise bean class. You can then add additional create() methods to the home interface if you add additional ejbCreate() methods to your bean. Or if you have an existing enterprise bean class, use JBuilder's EJB Interfaces wizard to create a home and remote interface with signatures that match appropriately those in your bean class. For more information, see "Developing enterprise beans with JBuilder."

create() methods in session beans

A session home interface functions as a session bean factory, because it must define one or more create() methods. When the client calls create(), a new bean instance is created. According to the EJB specification, each create() method defined in the home interface must

You can use the EJB wizards to ensure that these rules are followed.

The following code sample shows two possible create() methods of a session home interface. The parts shown in bold are required:

public interface AtmHome extends javax.ejb.EJBHome {
  Atm create()
    throws java.rmi.RemoteException, javax.ejb.CreateException;
  Atm create(Profile preferredProfile)
    throws java.rmi.RemoteException, javax.ejb.CreateException;
}

Creating a home interface for an entity bean

An entity bean is designed to serve multiple clients. When a client creates an entity bean instance, any other client can use it also.

To create a home interface for an entity bean,

When you use the JBuilder's Enterprise JavaBean wizard or EJB Entity Modeler, JBuilder creates a home interface with one defined create() method at the same time it creates the enterprise bean class. You can then add additional create() methods to the home interface if you add additional ejbCreate() methods to your bean. Or if you have an existing enterprise bean class, use JBuilder's EJB Interfaces wizard to create a home and remote interface with signatures that match appropriately those in your bean class. For more information, see "Developing enterprise beans with JBuilder."

create() methods for entity beans

Like a home interface for a session bean, a home interface for an entity bean must define one or more create() methods. According to the EJB specification, each create() method you define must

Finder methods for entity beans

Because entity beans usually have long lives and can be used by multiple clients, an entity bean instance probably already exists when a client application needs it. In this case, the client doesn't need to create an entity bean instance, but it does need to locate the appropriate existing one. That's why the home interface of an entity bean defines one or more finder methods.

Session beans don't need finder methods because they serve one client, the application that created the bean. The client has no need to find the session bean instance--it already knows where the instance is.

Each entity bean home interface must define the default finder method, findByPrimaryKey(). It allows a client to locate an entity object using a primary key:

<entity bean's remote interface> findByPrimaryKey(<primary key type> key)
    throws java.rmi.RemoteException, FinderException;
findByPrimaryKey() has a single argument, the primary key. Its return type is the entity bean's remote interface. In the bean's deployment descriptor, you tell the container the type of the primary key. findByPrimaryKey() always returns a single entity object.

You can define additional finder methods in the home interface. Each finder method must have a corresponding implementation in the entity bean class for bean-managed persistence. For container-managed persistence, the container implements the finder methods. Each finder method must follow these conventions:

The following sample home interface contains two create() methods and two finder methods. The parts shown in bold are required:

public interface AccountHome extends javax.ejb.EJBHome {

  Account create(String accountID)
    throws java.rmi.RemoteException, javax.ejb.CreateException;

  Account create(String accountID, float initialBalance)
    throws java.rmi.RemoteException, javax.ejb.CreateException;

  Account findByPrimaryKey(String key)
    throws java.rmi.RemoteException, javax.ejb.FinderException;

  Account findBySocialSecurity(String socialSecurityNumber)
    throws java.rmi.RemoteException, javax.ejb.FinderException;
}


Creating the remote interface

The remote interface you create for your enterprise bean describes the business methods a client application can call. While you define the methods in the remote interface, you implement these same methods in the enterprise bean class. The clients of an enterprise bean never access the bean directly. They access its methods through its remote interface.

To create a remote interface,

When you use JBuilder's EJB wizards, JBuilder creates a remote interface that extends EJBObject for you. You can then use the Bean designer to specify which business methods in your bean you want to appear in the remote interface.

Each method defined in the remote interface must follow these rules, which are the same for both session and entity beans:

The following code sample shows the code for a sample remote interface called Atm for an ATM session bean. The Atm remote interface defines a business method called transfer(). The parts shown in bold are required:

public interface Atm extends javax.ejb.EJBObject{

  public void transfer(String source, String target, float amount)
    throws java.rmi.RemoteException, InsufficientFundsException;
}
The transfer() method declared in the Atm interface throws two exceptions: the required java.rmi.RemoteException and InsufficientFundsException, which is an exception specific to an application.

The EJBObject

The remote interface extends the javax.ejb.EJBObject interface. Here is the source code for EJBObject:
package javax.ejb;
public interface EJBObject extends java.rmi.Remote (
  public EJBHome getEJBHome() throws java.rmi.RemoteException;
  public Object getPrimaryKey() throws java.rmi.RemoteException;
  public void remove() throws java.rmi.RemoteException, java.rmi.RemoveException;
  public Handle getHandle() throws java.rmi.RemoteException;
  boolean isIdentical (EJBObject other) throws java.rmi.RemoteException;
}
The getEJBHome() method allows an application to obtain the bean's home interface. If the bean is an entity bean, the getPrimaryKey() method returns the primary key for the bean. The remove() method deletes the enterprise bean. getHandle() returns a persistent handle to the bean instance. Use isIdentical() to compare two enterprise beans.

The EJB container creates an EJBObject for the enterprise bean. Because the remote interface extends the EJBObject interface, the EJBObject the container creates includes implementations for all the methods the EJBObject interface as well as all the business methods you define in the remote interface. The instantiated EJBObject is visible over the network and it acts as a proxy for the bean. It has a stub and a skeleton. The bean itself is not visible over the network.