Sun Microsystems Inc.

9.1.4 Instance life cycle

Figure 23 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 Microsystem 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). The instance does not move to the ready state during the execution of a finder 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(...) and ejbPostCreate(...) methods, or through the ejbActivate() method. The container invokes the ejbCreate(...) and ejbPostCreate(...) methods when the instance is assigned to an entity object during entity object creation (i.e. when the client invokes a create 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 two possible transitions from the ready to the pooled state: through the ejbPassivate() method and through the ejbRemove() method. 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).

•When the instance is put back into the pool, it is no longer associated with an entity object identity. The container can assign the instance to any entity object within the same entity bean home.

•An instance in the pool can be removed by calling the unsetEntityContext() method on the instance.