TechFAQ

public void setEntityContext(EntityContext 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 [primary key class] 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 invokes the ejbCreate<METHOD>(...) method whose signature matches the create<METHOD>(...) method invoked by the client.

Prior to invoking the ejbCreate<METHOD>(...) method provided by the Bean Provider, the container MUST ensure that the values that will be initially returned by the instance’s get methods for container-managed fields will be the Java language defaults (e.g. 0 for integer, null for pointers), except for collection-valued cmr-fields, which MUST have the empty collection (or set) as their value.

The container is responsible for calling the ejbCreate<METHOD>(...) method, for obtaining the primary key fields of the newly created entity object persistent representation, and for creating an entity EJBObject reference and/or EJBLocalObject reference for the newly created entity object. The Container MUST establish the primary key BEFORE it invokes the ejbPostCreate<METHOD>(...) method.

The entity object created by the ejbCreate<METHOD> method MUST have a unique primary key. This means that the primary key MUST be different from the primary keys of all the existing entity objects within the same home. However, it is legal to reuse the primary key of a previously removed entity object. The container MAY, but is NOT REQUIRED to, throw the DuplicateKeyException on the Bean Provider’s attempt to create an entity object with a duplicate primary key.

The container may create the representation of the entity in the database immediately, or it CAN DEFER it to a later time (for example to the time after the matching ejbPostCreate<METHOD>(...) has been called, or to the end of the transaction), depending on the caching strategy that it uses.

The container then invokes the matching ejbPostCreate<METHOD>(...) method with the SAME arguments on the instance to allow the instance to fully initialize itself. The instance can discover the primary key by calling getPrimaryKey() on its entity context object.

Finally, the container returns the entity object’s remote interface (i.e., a reference to the entity EJBObject) to the client if the client is a remote client or the entity object’s local interface (i.e., a reference to the entity EJBLocalObject) if the client is a local client.

The container MUST invoke ejbCreate<METHOD> and ejbPostCreate<METHOD> and create the representation of the persistent instance in the database in the transaction context determined by the transaction attribute of the matching create<METHOD>(...) method.

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(), getEJBLocalObject(), 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 instance if the instance invokes the getPrimaryKey(), getEJBLocalObject(), 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 the ejbRemove() method in response to a client-invoked remove(...) operation on the entity bean’s home or component interface or as the result of a cascade-delete operation. The instance is in the READY STATE when ejbRemove() is invoked and it will be entered into the POOL when the method completes.

The container synchronizes the instance’s state before it invokes the ejbRemove method. This means that the persistent state of the instance at the beginning of the ejbRemove method is the SAME as it would be at the beginning of a business 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).

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(), getEJBLocalObject(), or getEJBObject() method on its EntityContext in the ejbRemove() method).

After the entity Bean Provider’s ejbRemove() method returns, and in the same transaction context, the Container removes the entity bean instance from all relationships in which it participates and then removes the entity object’s persistent representation.

The container may delete the representation of the entity in the database immediately, or it can defer it to a later time (for example to the end of the transaction), depending on the caching strategy that it uses.

The container MUST ensure that the ejbRemove method and database delete operations are performed in the transaction context determined by the transaction attribute of the invoked remove method.

public void ejbLoad();

When the container needs to synchronize the state of an enterprise bean instance with the entity object’s state in the database, the container calls the ejbLoad() method. Depending on its caching strategy, the container may first read the entity object’s state from the database, before invoking the ejbLoad() method, or it may use a lazy loading strategy in making this state visible to the instance.

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.

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();

When the container needs to synchronize the state of the entity object in the database with the state of the enterprise bean instance, the container calls the ejbStore() method on the instance. 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.

The container MUST invoke this method in the SAME transaction context as the previous ejbLoad or ejbCreate<METHOD> method invoked on the instance. All business methods invoked between the previous ejbLoad or ejbCreate<METHOD> method and this ejbStore method are also invoked in the SAME transaction context.

After the ejbStore() method returns, the container may store the persistent state of the instance to the database, depending on its caching strategy. If the container uses a lazy storing caching strategy, it is the container’s responsibility to write the representation of the persistent object to the database in the same transaction context as that of the ejbStore method.

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

The implementation of the ejbFind<METHOD>(...) method is SUPPLIED BY THE CONTAINER.

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 with any entity object identity) for the execution of the ejbFind<METHOD>(...) method. If there is no instance in the pooled state, the container creates one and calls the setEntityContext(...) method on the instance before dispatching the finder method.

The container must invoke the ejbFind<METHOD>(...) method in the transaction context determined by the transaction attribute of the matching find<METHOD>(...) method.

The Container is responsible for ensuring that updates to the states of all entity beans in the same transaction context as the ejbFind<METHOD>(...) method are visible in the results of the ejbFind<METHOD>(...) method. Before invoking the ejbFind<METHOD>(...) method, the container must therefore first synchronize the state of any entity bean instances that are participating in the same transaction context as is used to execute the ejbFind<METHOD>(...) by invoking the ejbStore() method on those entity bean instances.

After the ejbFind<METHOD>(...) method completes, the instance remains in the pooled state. The container may, but is NOT REQUIRED to, immediately activate the objects that were located by the finder using the transition through the ejbActivate() method.

If the ejbFind<METHOD>(...) method is declared to return a single primary key, the container creates an entity EJBObject (EJBLocalObject) reference for the primary key and returns it to the client (local client). If the ejbFind<METHOD>(...) method is declared to return a collection of primary keys, the container creates a collection of entity EJBObject (EJBLocalObject) references for the primary keys returned from the ejbFind<METHOD>(...), and returns the collection to the client (local client).

The implementations of the finder methods are generated at the entity bean deployment time using the container provider’s tools.

public abstract [some type] ejbSelect<METHOD>(...);

A SELECT METHOD is a query method that is NOT DIRECTLY EXPOSED to the client in the home or component interface. The Bean Provider typically calls a select method within a business method or home method.

A select method executes in the transaction context determined by the transaction attribute of the invoking business method.

The container is responsible for ensuring that all updates to the states of all entity beans in the same transaction context as the ejbSelect<METHOD> method are visible in the results of the ejbSelect<METHOD> method.

The implementations of the select methods are generated at the entity bean deployment time using the container provider’s tools.

public [some type] ejbHome<METHOD>(...);

The container invokes the ejbHome<METHOD>(...) method on an instance when a client invokes a matching <METHOD>(...) home 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 with any entity object identity) for the execution of the ejbHome<METHOD>(...) method. If there is no instance in the pooled state, the container creates one and calls the setEntityContext(...) method on the instance before dispatching the home method.

After the ejbHome<METHOD>(...) method completes, the instance remains in the POOLED state.

The container must invoke the ejbHome<METHOD>(...) method in the transaction context determined by the transaction attribute of the matching <METHOD>(...) home method.