Mastering Enterprise JavaBeans™ and the Java 2 Platform, Enterprise Edition - Roman E

198 M A S T E R I N G E N T E R P R I S E J A V A B E A N S

Relationship between remove() and ejbRemove(). Note that remove() can be called on either the home object or the EJB object.

[Diagram happens to assume bean-managed persistence]

EJB Container/Server

3: Remove database data

entity bean data

Database

Figure 7.6 Destroying an entity bean’s data representation.

For session beans, this context’s interface is javax.ejb.SessionContext. For entity beans, the interface is javax.ejb.EntityContext. Both session contexts and entity contexts extend the more generic javax.ejb.EJBContext interface.

We provide a refresher of the javax.ejb.EJBContext methods in Source 7.3. Table 7.1 explains the meaning of each method.

Entity contexts add two new methods on top of the generic EJB context, shown in Source 7.4.

Let’s look at each of these methods in more detail.

Go back to the first page for a quick link to buy this book online!

Introduction to Entity Beans 199

public interface javax.ejb.EJBContext {

public abstract javax.ejb.EJBHome getEJBHome(); public abstract java.util.Properties getEnvironment();

public abstract java.security.Identity getCallerIdentity(); public abstract boolean isCallerInRole(java.security.Identity); public abstract javax.jts.UserTransaction getUserTransaction(); public abstract void setRollbackOnly();

public abstract boolean getRollbackOnly();

}

Source 7.3 The javax.ejb.EJBContext interface.

getEJBObject()

Call this to retrieve the current, client-specific EJB object that is associated with the entity bean. Remember that clients invoke on EJB objects, not on entity beans directly. Therefore you can use the returned EJB object as a way to pass a reference to yourself, simulating the this argument in Java. getEJBObject() has the same functionality as session beans.

getPrimaryKey()

getPrimaryKey() is new to entity beans. It retrieves the primary key that is currently associated with this entity bean instance. Primary keys uniquely identify an entity bean. When an entity bean is persisted in storage, the primary key can be used to uniquely retrieve the entity bean because you can never have two entity bean database data instances that have the same primary key.

Why would you ever want to call getPrimaryKey()? You’d call it whenever you want to figure out with which database data your instance is associated. Remember that entity bean instances can be reused and pooled, as we saw in Figure 7.3. When the container wants to switch an entity bean instance from one data instance to another, the container needs to passivate and activate that entity bean instance. When this happens, your bean instance may switch to a different data instance and thus a different primary key. But your entity bean instance is never told this explicitly when it’s activated. Rather, your entity bean must perform a getPrimaryKey() callback to the entity context to figure out what data it should be dealing with.

Thus, when you have an entity bean that’s performing any persistent work (with bean-managed persistence), you should be calling getPrimaryKey() whenever you need to figure out what data you’re bean is associated with. This is very useful, for example, in the following methods:

Go back to the first page for a quick link to buy this book online!

202 M A S T E R I N G E N T E R P R I S E J A V A B E A N S

Thus, it’s always important to consider bean pooling when writing your enterprise beans, and getPrimaryKey() is the key to always knowing what data your bean is representing.

Putting It All Together: Walking through an Entity Bean Life Cycle

Throughout this chapter, we’ve touched on various moments in the life cycle of an entity bean instance—when it’s created, when it’s destroyed, and how it’s used. Now that you’ve seen all the elements, let’s wrap up this chapter by examining the big picture and defining this process more concretely. The state machine diagram in Figure 7.7 illustrates the life cycle of an entity bean.

Here is what’s going on in this diagram:

1.The does not exist state represents entity bean instances that have not been instantiated yet.

2.To create a new instance, the container calls the newInstance() method on the entity bean class. This calls your entity bean’s default constructor, bringing a new instance into memory. Next, the container associates your entity bean with an entity context object—this is done via a callback that you implement, called setEntityContext(EntityContext ctx). Note that this step occurs only when the container wants to increase the available pool of entity bean instances—this is not necessarily done when a client connects.

3.After step 2, your entity bean is in a pool of other entity beans. At this point your entity bean does not have any entity bean database data loaded into it, and it does not hold any bean-specific resources, such as socket connections. Your bean instance can be used in this mode to find entity data in the database, by servicing a finder method on behalf of a client. If the container wants to reduce its pool size, it can destroy your bean. The container signals your bean instance that it is about to be destroyed by calling the unsetEntityContext() method on your bean. Once this is done, the container releases any references to your bean, and eventually, the Java garbage collector will clean up the memory your instance had been using. Therefore, your unsetEntityContext() method should prepare your bean to be cleaned up, perhaps by releasing any bean-independent resources your bean had claimed.

4.When the client wants to create some new database data (say, a new order for goods placed over the Internet), it calls a create() method on your entity bean’s home object. The container then grabs an entity bean instance from the pool, and the instance’s ejbCreate() method is called. ejbCreate() initializes the entity bean to a specific data set. For example, if a client calls

Go back to the first page for a quick link to buy this book online!

204 M A S T E R I N G E N T E R P R I S E J A V A B E A N S

5.While your bean is in the ready state, it is tied to specific data and hence a specific EJB object. If there are other entity bean instances that are views into the same database data, the container may occasionally need to synchronize your bean instance with the underlying database, so that you will always be working with the most recent data. The ejbLoad() and ejbStore() methods do this; the container calls them as appropriate, based on how you define your transactions (see Chapter 10).

6.There are two ways for your entity beans to be kicked back into the pool. If a client calls remove() on the home object, then the container will call your instance’s ejbRemove(). The underlying database data is destroyed, and so, of course, your entity bean instance will become disassociated with the client’s EJB object to which it was bound.

7.The second way your bean can return to the pool is if the EJB container decides that your client has timed out, if the container needs to use your bean to service a different client, or if the container is simply running out of resources. At this point, your bean is passivated, and the container calls your ejbStore() method to ensure the database has the most recent version of your in-memory data. Next, the container calls your ejbPassivate() method—allowing your bean instance to release all bean-specific resources. Your bean instance then enters the pool.

8.When the container wants to assign you to an EJB object again, your bean instance must be activated. The container calls your bean’s ejbActivate() method, allowing your bean to acquire bean-specific resources. The container then calls your instance’s ejbLoad() method to load the database data into your bean.

Note that there are a few other minor steps in this process, such as transactional synchronization. Overall, these stages are the essence of an entity bean instance’s life cycle. If you’ve made it this far, then congratulations! You are ready to move on from theoretical concepts to the concrete entity bean programming.

Summary

In this chapter, we’ve taken the first steps toward developing with entity beans. We started by learning about various persistence mechanisms, including object serialization, object/relational mapping, and persistence to pure object databases. We then looked at exactly what an entity bean is, and we saw the files included with an entity bean component. Next, we used our knowledge of session beans as a basis for learning entity beans. After surveying their features, we took a look at the interfaces that EJB provides for entity bean components,

Go back to the first page for a quick link to buy this book online!

Introduction to Entity Beans 205

such as the entity bean interface and the entity context interface. Finally, we stepped through the life cycle of a typical entity bean instance.

But the best is yet to come—in the next two chapters, we’ll learn hands-on about entity bean programming. Chapter 8 starts off by explaining bean-managed persistent entity beans, and it guides you through the steps in developing them using JDBC. Chapter 9 then continues with container-managed persistent entity beans. Not only will we see how the programming styles differ, but we’ll do a full comparison of the promises and realities of the two entity bean programming models. By the time you’re through, you’ll be armed to create your own entity beans in enterprise deployments.

Go back to the first page for a quick link to buy this book online!