TechFAQ

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 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 (ejbFind<METHOD>(...)) or any of the entity bean’s HOME methods (ejbHome<METHOD>(...)). The instance DOES NOT move to the ready state during the execution of a finder or a home method. An ejbSelect<METHOD>(...) method may be called by an entity bean’s home method while the instance is in the pooled state.

public abstract class AddressBean implements javax.ejb.EntityBean {
...

	// Customer home methods.  
	// These are wrappers of ejbSelect methods

	public Collection ejbHomeQueryZipCodes(String state)
				throws FinderException   {
		return ejbSelectZipCodes(state);
	}

	public Collection ejbHomeQueryAll()
				throws FinderException  {
		return ejbSelectAll();
	}

	public CustomerLocal ejbHomeQueryCustomer(AddressLocal addr)
				throws FinderException   {
		return ejbSelectCustomer(addr);
	}
...
}
							

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:

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 synchronize the state of the instance with the state of the entity in the underlying data source whenever it determines the need to, in the process invoking 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. An ejbSelect<METHOD> method CAN be called by a business method (or ejbLoad() or ejbStore() method) while the instance is in the READY 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 prepare itself for the synchronization of the database state with the instance’s state, and then the container invokes the ejbPassivate() method to return the instance to the POOLED state.

The container will transition the instance to the pooled state. There are THREE possible transitions from the ready to the POOLED state:

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.

The CONTAINER can REMOVE an instance in the pool by calling the unsetEntityContext() method on the instance.

The result of the EntityContext.getPrimaryKey() method MIGHT BE DIFFERENT each time an instance moves from the pooled state to the ready state, and the result of the getCallerPrincipal() and isCallerInRole(...) methods MAY BE DIFFERENT in each business method.

A RuntimeException thrown from any method of an entity bean class (including the business methods and the callbacks invoked by the container) results in the transition to the DOES NOT EXIST state.

From the caller’s perspective, the corresponding entity object CONTINUES to exist. The client CAN continue accessing the entity object through its component interface because the container can use a different entity bean instance to delegate the client’s requests.

The container is NOT REQUIRED to maintain a pool of instances in the pooled state. The pooling approach is an example of a possible implementation.