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.
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.
To create a home interface for a session bean,
javax.ejb.EJBHome
.
create()
method signature for each ejbCreate()
method in the bean, matching the number and type of arguments exactly.
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. 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
create()
.
ejbCreate()
method in the session bean class. The number and types of arguments for each create()
method must match its corresponding ejbCreate()
method in the session bean class.
java.rmi.RemoteException
.
javax.ejb.CreateException
.
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; }
To create a home interface for an entity bean,
javax.ejb.EJBHome
.
create()
method signature for each ejbCreate()
method in the bean, matching the signatures exactly.
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. According to the EJB specification, each create()
method you define must
java.rmi.RemoteException
.
javax.ejb.CreateException
.
create()
.
ejbCreate()
method in the session bean class. The number and types of arguments for each create()
method must match its corresponding ejbCreate()
method in the session bean class.
ejbCreate()
and ejbPostCreate()
methods in the entity bean class. In other words, the set of exceptions for the create()
method must be a superset of the union of exceptions for both the ejbCreate()
and ejbPostCreate()
methods. The return type of the ejbCreate()
method is the primary key class.
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:
java.util.Enumeration
and java.util.Collection
.
java.rmi.RemoteException
.
javax.ejb.FinderException
.
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; }
To create a remote interface,
javax.ejb.EJBObject
.
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:
java.rmi.RemoteException
.
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.
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.