6.1. Introducing Entity Beans
Our example entity bean models the customer data for the Music Collection shopping application. We'll delay describing it until after we've characterized entity beans in general.
An entity bean is an in-memory representation of persistent data. The persistence mechanism is either coded by the bean developer (bean-managed persistence) or provided by the container (container-managed persistence). For both bean-managed and container-managed entity beans, the EJB container manages life cycles and keeps the beans synchronized with the underlying database. Because multiple clients may share an entity bean (and possibly alter its state), the container and the bean developer must make sure that any updates occur within an appropriate transaction. In this chapter we present an entity bean example with bean-managed persistence. In the next chapter we discuss Container-Managed Persistence (CMP). We begin by exploring an entity bean's properties.
Properties of Entity Beans
An entity bean is quite different from a session bean. In general, we use a session bean to model a business process. A session bean contains the business logic to accomplish one or more tasks. For example, we've seen a Loan (session) EJB that calculates monthly payments for a long-term, fixed-rate loan. An entity bean, on the other hand, represents business data, and in general, does not provide the capability to model a business process. From that standpoint, we characterize an entity bean as containing minimal logic and being “data heavy.”
Persistent and Shareable
Entity beans are persistent. Furthermore, the bean is always synchronized with the database, allowing access by multiple clients. The J2EE architecture provides two ways to persist the data: BMP and CMP. With BMP, the bean provider writes the database access code, either directly in the bean implementation class, or callable through a data access object (DAO). Database access is typically achieved through JDBC calls. However, there is nothing to preclude the bean provider from accessing a nonrelational database system. In fact, one compelling reason for using BMP is that you may have a nonrelational database system and are thus prevented from using container-managed persistence. (We discuss additional points for choosing between BMP and CMP under “Properties of CMP Entity Beans” on page 278.)
Local and Remote Interfaces
Like session beans, entity beans may have either a remote or local interface (or both). For bean-managed persistence, it is a good idea to implement the remote interface for convenient testing (it is more convenient to test from a stand-alone application client, which is necessarily remote) and a local interface for production. We recommend local access to entity beans through a “business smart” session bean. Because entity bean access tends to be many fine-grained calls which read or update persistent variables, performance improves if these calls are local. This avoids RMI overhead and decreases network traffic. The session bean front end is called the Session Facade Pattern, which we present in this chapter.
EJB Methods and Database Access
With entity beans, specific EJB methods cause certain database operations. Table 6.1 summarizes these methods and their associated database behaviors. We discuss these methods in more detail in the upcoming sections.
| Method | Database Access |
|---|---|
| ejbCreate() | Inserts new record. Returns primary key to container. |
| ejbFindByPrimaryKey() | Selects record with specified primary key. Returns primary key to container. |
| ejbFindXXX() | Selects one or more records. Returns primary key or collection of primary keys to container. |
| ejbHomeXXX() | Custom database access (select or update) not tied to any specific primary key. |
| ejbLoad() | Selects (refresh in-memory persistent variables). |
| ejbStore() | Updates (store persistent variables). |
| ejbRemove() | Deletes record. |
Primary Key and Finder Methods
All entity beans have a unique primary key and a method in the home (or local home) interface called findByPrimaryKey(). Method findByPrimaryKey() maps to ejbFindByPrimaryKey() in the entity bean's implementation class. An entity bean's client invokes method findByPrimaryKey() to gain access to the bean's business methods (which are generally data access or data update methods). Furthermore, a client can “find” entity beans by other criteria, depending on the finder methods specified in the home interface.
With session beans, the only way to obtain an object that implements the remote or local interface is through the home interface create() methods. With entity beans, however, finder methods also obtain an object that implements the remote (or local) interface. We use a finder method when the record already exists in the database. We use create() when we want to insert a new record in the database.
Our Customer EJB has several finder methods. Method findByCustomerName() allows the client to specify a String name as an argument and method findAll() returns a collection of Customer entity beans to the client. The finder methods defined will depend on the data that the entity bean represents. The finder methods in the home interface map to ejbFindXXX() methods in the bean implementation class. For example, findByCustomerName() maps to ejbFindByCustomerName() and findAll() maps to ejbFindAll(). In BMP, the bean provider writes the appropriate SQL Select queries to implement the ejbFindXXX() methods. The queries may access more than one database table if the entity bean pulls its persistent fields from related tables.
Create Methods
Entity beans may also have one or more create() methods. Like session beans, create() methods in the home (or local home) interface map to ejbCreate() methods in the bean implementation class. Unlike session beans, however, implementation code for ejbCreate() results in database insert commands. Thus, invoking create() for an entity bean not only creates an instance of the entity bean, but also creates a corresponding record in the underlying database. If an insert attempts to create a record with a duplicate primary key, the database software throws an SQLException; the bean implementation code will, in turn, throw a CreateException.
Home Methods
Entity beans also have home methods. Clients access an entity bean's home methods through the home or local home interface. These methods, therefore, cannot access a specific entity bean. Rather, home methods perform a “bean-wide” query, calculation, or update. This is analogous to a Java class method in that a client can invoke the method with the notation class.method() without instantiating an object.
In our Customer EJB, for instance, we provide a home method called getTotalCustomers() that counts the number of records in our Customer database. While we must access the database to perform this method, it doesn't require an entity bean instantiation by the container. Home methods map to ejbHomeXXX() methods in the bean implementation class. This particular method, then, maps to ejbHomeGetTotalCustomers(). (The word “home” is a bit overused here. Although clients also access finder and create methods through the home interface, “home methods” refer specifically to these bean-wide business methods implemented by ejbHomeXXX() methods in the bean implementation class.)
EJB Methods
The entity bean's implementation class must implement the EntityBean interface. This interface includes the “EJB” methods that the EJB container invokes to manage an entity bean instance. While we've seen some of these methods with our session bean examples (such as ejbActivate() and ejbPassivate()), entity beans have two additional important methods whose job is to synchronize the entity bean instance with its underlying database. These methods are ejbLoad() and ejbStore(). In BMP, the bean developer must provide the database access code to read the database with ejbLoad() and write new values to the database with ejbStore(). Client code never calls these methods directly. They are called by the EJB container to make sure that any business method that affects the entity bean will be correctly applied to the underlying database and that the entity bean and database are properly synchronized.
Let's proceed now to our entity bean example.