Entity Bean Client Interfaces
Building and using home and remote client interfaces for entity beans is very similar to building and using home and remote client interfaces for session beans. In fact, except for an additional type of finder method that needs to be added to the entity bean home interface definition, only a few small subtle semantic differences exist. I describe how to build entity bean interfaces and how clients access these interfaces next.
Entity Bean Remote Interfaces
Entity bean remote interfaces encapsulate the client's view of an entity bean. The approach by which entity bean remote interfaces are developed is identical to that of session bean remote interfaces. Entity bean interfaces typically consist of getters and setters for retrieving and establishing data to be associated with an entity bean, but they can also have other arbitrary application-specific interfaces defined for them.
Entity Bean Remote Interface Logical Architecture
This section describes how to build and use entity bean remote interfaces. Figure 3 depicts the basic logical architecture for building and using remote EJB client interfaces to distributed entity EJBs.
Figure 3 Entity bean remote interface architecture.
All application-specific interfaces to distributed EJB objects, such as MyEntityEJB, shown in the figure, must extend the javax.ejb.EJBObject interface. As with session beans, entity beans employ underlying stubs, skeletons, and container-management services for implementing distributed and managed access to server-side entity EJBs from client-side interfaces. The only real difference between entity bean and session bean remote interfaces lies in a few subtle semantic differences, as I discuss next.
As with session bean remote interfaces, an application-specific remote EJB interface must be created for each entity bean component. This interface provides the distributed interface usable by entity bean clients to invoke the application-specific logic of entity beans. For each distributable application-specific method on an entity bean server-side component, such as MyEntityEJBean.someMethod(), an associated application-specific method must be defined on the EJB client-side remote interface, such as MyEntityEJB.someMethod(). As a side effect of their distributable nature, each method in the application-specific remote interface should declare that it can throw a java.rmi.RemoteException. Of course, such rules apply only to server-side component methods that you want to make distributable. In addition to application-specific interfaces on an EJB remote interface, a set of methods inherited from EJBObject can be invoked on a remote entity bean object.
Entity Bean Home Interfaces
Entity bean clients use home interfaces to create, find, and remove entity beans. Creation of entity beans actually relates to the insertion of a new entry into a data source (for example, a new row in a database table). Interfaces for finding entity beans provide a mechanism of querying for data-source entries; results are returned in an object-oriented manner (that is, in terms of entity bean objects). Removing an entity bean involves deleting its associated data-source entry in the database. This section describes how to create and utilize entity bean interfaces to perform these basic functions as well as additional supporting functionality.
Entity Bean Home Interface Logical Architecture
Figure 4 depicts the architecture behind creating entity bean home interfaces and shows how clients may use these interfaces. To obtain handles to application-specific EJB home interface objects, such as MyEntityEJBHome, which must extend the standard javax.ejb.EJBHome interface, I use JNDI to look up named home references. Server-side skeletons and the container handle mapping calls from entity bean client stubs that implement application-specific home interfaces on a particular entity bean instance. Home interfaces can also be used to persist their handles for later reconstruction and to obtain metadata about the EJBs that they create.
Figure 4 Entity bean home interface architecture.
The means by which clients look up entity bean home objects is identical to the means by which they look up session bean home objects. JNDI is used whether your client operates inside a J2EE container or whether it operates outside a container in a standalone fashion. If a client operates inside a J2EE container, <ejb-ref> elements can be used to refer to EJB home interfaces during lookup. Entity beans that want to act as clients to other EJBs define <ejb-ref> elements within their <entity> element definition inside an ejb-jar.xml file.
A series of one or more create(...) methods is defined on the custom home interface to represent the different ways in which the associated entity bean data-source entry can be created. A single create(...) method must be defined on the home interface for each ejbCreate(...) method defined on the entity bean implementation. Each version of a create(...) method returns an instance of the entity bean's remote interface (for example, MyEntityEJB) and contains zero or more input parameters related to the specific types of initialization parameters needed by the associated ejbCreate(...) methods. Each create(...) method must also be defined to throw a java.rmi.RemoteException and a javax.ejb.CreateException. Additionally, each create(...) method must be defined to throw any application-specific exceptions that have been defined for its associated ejbCreate(...) method.
The create() methods are not the only application-specific methods that can be defined on an entity bean home interface. A collection of finder methods is also defined that enables the client to query for existing entity beans. A findXXX(...) method on the entity bean home interface must exist for each ejbFindXXX(...) method that exists on the entity bean implementation. For CMP entity beans, because no ejbFindXXX(...) methods are explicitly defined on an entity bean implementation, the valid findXXX(...) methods can be determined from the entity bean deployment descriptor (as we'll soon learn in the last section). Each findXXX(...) method defined on the entity bean client home interface should also declare that RemoteException and FinderException objects can be thrown back to the client.
All entity bean home interfaces must define at least one findByPrimaryKey() method because all entity beans must define an ejbFindByPrimaryKey() method. The findByPrimaryKey() method must be defined so that it returns a handle to an entity bean remote object (for example, MyEntityEJB). The container handles associating the primary key returned from the ejbFindByPrimaryKey() entity bean method to an actual bean instance and returned entity bean client remote interface stub. The other findXXX(...) methods must also be defined to match each associated ejbFindXXX(...) method, and they should have the same input and output parameters. The difference on the client side is that the Enumeration or Collection object returned from findXXX(...) contains implementations of entity bean remote objects instead of primary keys contained in the collections returned from associated ejbFindXXX(...) methods on server-side entity bean implementations.