Sun Microsystems Inc.

Entity Bean Component Contract for Bean Managed PersistenceEnterprise JavaBeans 2.0, Public Draft Overview of Bean Managed

11.1.4 Instance life cycle

Figure 39 Life cycle of an entity bean instance.

business method

An entity bean instance is in one of the following three states:

•It does not exist.

•Pooled state. An instance in the pooled state is not associated with any particular entity object identity.

•Ready state. An instance in the ready state is assigned an entity object identity.

The following steps describe the life cycle of an entity bean instance:

•An entity bean instance’s life starts when the container creates the instance using newInstance(). The container then invokes the setEntityContext() method to pass the instance a reference to the EntityContext interface. The EntityContext interface

Sun Microsystems Inc

allows the instance to invoke services provided by the container and to obtain the information about the caller of a client-invoked method.

•The instance enters the pool of available instances. Each entity bean has its own pool. While the instance is in the available pool, the instance is not associated with any particular entity object identity. All instances in the pool are considered equivalent, and therefore any instance can be assigned by the container to any entity object identity at the transition to the ready state. While the instance is in the pooled state, the container may use the instance to execute any of the entity bean’s finder methods (shown as ejbFind<METHOD>(...) in the diagram or home methods (shown as ejbHome<METHOD>(...) in the diagram). The instance does not move to the ready state during the execution of a finder or a home method.

•An instance transitions from the pooled state to the ready state when the container selects that instance to service a client call to an entity object. There are two possible transitions from the pooled to the ready state: through the ejbCreate<METHOD>(...) and ejbPostCreate<METHOD>(...) methods, or through the ejbActivate() method. The container invokes the ejbCreate<METHOD>(...) and ejbPostCreate<METHOD>(...) methods when the instance is assigned to an entity object during entity object creation (i.e. when the client invokes a create<METHOD> method on the entity bean’s home object). The container invokes the ejbActivate() method on an instance when an instance needs to be activated to service an invocation on an existing entity object—this occurs because there is no suitable instance in the ready state to service the client’s call.

•When an entity bean instance is in the ready state, the instance is associated with a specific entity object identity. While the instance is in the ready state, the container can invoke the ejbLoad() and ejbStore() methods zero or more times. A business method can be invoked on the instance zero or more times. Invocations of the ejbLoad() and ejbStore() methods can be arbitrarily mixed with invocations of business methods. The purpose of the ejbLoad and ejbStore methods is to synchronize the state of the instance with the state of the entity in the underlying data source—the container can invoke these methods whenever it determines a need to synchronize the instance’s state.

•The container can choose to passivate an entity bean instance within a transaction. To passivate an instance, the container first invokes the ejbStore method to allow the instance to synchronize the database state with the instance’s state, and then the container invokes the ejbPassivate method to return the instance to the pooled state.

•Eventually, the container will transition the instance to the pooled state. There are three possible transitions from the ready to the pooled state: through the ejbPassivate() method, through the ejbRemove() method, and because of a transaction rollback for ejbCreate(), ejbPostCreate(), or ejbRemove() (not shown in Figure 39). The container invokes the ejbPassivate() method when the container wants to disassociate the instance from the entity object identity without removing the entity object. The container invokes the ejbRemove() method when the container is removing the entity object (i.e. when the client invoked the remove() method on the entity object’s remote interface, or one of the remove() methods on the entity bean’s home interface). If ejbCreate(), ejbPostCreate(), or ejbRemove() is called and the transaction rolls back, the container will transition the bean instance to the pooled state.