Sun Microsystems Inc.

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

11.1.5.2 Container’s view:

This subsection describes the container’s view of the state management contract. The container must call the following methods:

•public void setEntityContext(ec);

The container invokes this method to pass a reference to the EntityContext interface to the entity bean instance. The container must invoke this method after it creates the instance, and before it puts the instance into the pool of available instances.

The container invokes this method with an unspecified transaction context. At this point, the EntityContext is not associated with any entity object identity.

•public void unsetEntityContext();

The container invokes this method when the container wants to reduce the number of instances in the pool. After this method completes, the container must not reuse this instance.

The container invokes this method with an unspecified transaction context.

•public PrimaryKeyClass ejbCreate<METHOD>(...); public void ejbPostCreate<METHOD>(...);

The container invokes these two methods during the creation of an entity object as a result of a client invoking a create<METHOD>(...) method on the entity bean’s home interface.

The container first invokes the ejbCreate<METHOD>(...) method whose signature matches the create<METHOD>(...) method invoked by the client. The ejbCreate<METHOD>(...) method returns a primary key for the created entity object. The container creates an entity EJBObject reference for the primary key. The container then invokes a matching ejbPostCreate<METHOD>(...) method to allow the instance to fully initialize itself. Finally, the container returns the entity object’s remote interface (i.e. a reference to the entity EJBObject) to the client.

The container must invoke the ejbCreate<METHOD>(...) and ejbPostCreate<METHOD>(...) methods in the transaction context determined by the transaction attribute of the matching create<METHOD>(...) method, as described in subsection 16.7.2.

•public void ejbActivate();

The container invokes this method on an entity bean instance at activation time (i.e., when the instance is taken from the pool and assigned to an entity object identity). The container must ensure that the primary key of the associated entity object is available to the instance if the instance invokes the getPrimaryKey() or getEJBObject() method on its EntityContext interface.

The container invokes this method with an unspecified transaction context.

Note that instance is not yet ready for the delivery of a business method. The container must still invoke the ejbLoad() method prior to a business method.

•public void ejbPassivate();

The container invokes this method on an entity bean instance at passivation time (i.e., when the instance is being disassociated from an entity object identity and moved into the pool). The container must ensure that the identity of the associated entity object is still available to the

Sun Microsystems Inc

instance if the instance invokes the getPrimaryKey() or getEJBObject() method on its entity context.

The container invokes this method with an unspecified transaction context.

Note that if the instance state has been updated by a transaction, the container must first invoke the ejbStore() method on the instance before it invokes ejbPassivate() on it.

•public void ejbRemove();

The container invokes this method before it ends the life of an entity object as a result of a client invoking a remove operation.

The container invokes this method in the transaction context determined by the transaction attribute of the invoked remove method.

The container must ensure that the identity of the associated entity object is still available to the instance in the ejbRemove() method (i.e. the instance can invoke the getPrimaryKey() or getEJBObject() method on its EntityContext in the ejbRemove() method).

The container must ensure that the instance’s state is synchronized from the state in the database before invoking the ejbRemove() method (i.e. if the instance is not already synchronized from the state in the database, the container must invoke ejbLoad before it invokes ejbRemove).

•public void ejbLoad();

The container must invoke this method on the instance whenever it becomes necessary for the instance to synchronize its instance state from its state in the database. The exact times that the container invokes ejbLoad depend on the configuration of the component and the container, and are not defined by the EJB architecture. Typically, the container will call ejbLoad before the first business method within a transaction to ensure that the instance can refresh its cached state of the entity object from the database. After the first ejbLoad within a transaction, the container is not required to recognize that the state of the entity object in the database has been changed by another transaction, and it is not required to notify the instance of this change via another ejbLoad call.

The container must invoke this method in the transaction context determined by the transaction attribute of the business method that triggered the ejbLoad method.

•public void ejbStore();

The container must invoke this method on the instance whenever it becomes necessary for the instance to synchronize its state in the database with the state of the instance’s fields. This synchronization always happens at the end of a transaction. However, the container may also invoke this method when it passivates the instance in the middle of a transaction, or when it needs to transfer the most recent state of the entity object to another instance for the same entity object in the same transaction (see Subsection 16.8).

The container must invoke this method in the same transaction context as the previously invoked ejbLoad or ejbCreate<METHOD> method.

•public primary key type or collection ejbFind<METHOD>(...);

The container invokes the ejbFind<METHOD>(...) method on an instance when a client invokes a matching find<METHOD>(...) method on the entity bean’s home interface. The container must pick an instance that is in the pooled state (i.e. the instance is not associated