Sun Microsystems Inc

Instance life cycle contract between the bean, the container, and the persistence managerEnterprise JavaBeans 2.0, Public Draft Entity

9.6.7.1 Single-object select methods

Some select methods are designed to return at most one value. In general, when defining a single-object select method, the entity Bean Provider must be sure that the select method will always return only a single object or value. If the query specified by the select method returns multiple values of the designated type, the Persistence Manager must throw a FinderException.

The Bean Provider will typically define a select method as a multi-object select method.

9.6.7.2 Multi-object select methods

Some select methods are designed to return multiple values. For these multi-object select methods, the result type of the ejbSelect<METHOD>(...) or ejbSelect<METHOD>InEntity method defined in the entity bean’s implementation class is a collection of objects.

The Bean Provider uses the Java™ 2 java.util.Collection interface or java.util.Set interface to define a collection type for the result type of a select method. The type of the members of the collection is determined by the type of the SELECT clause of the corresponding EJB QL query. If the Bean Provider uses the java.util.Collection interface, the collection of values returned by the Persistence Manager may contain duplicates.

The Bean Provider must use the PortableRemoteObject.narrow(...) method to convert the objects contained in the collections returned by the select method of another entity bean’s remote interface type.

The following is an example of a multi-object select method definition in the OrderBean class:

// OrderBean implementation class

public abstract class OrderBean implements javax.ejb.EntityBean{

...

public abstract java.util.Collection ejbSelectAllOrderedProducts(Date date)

throws FinderException{

// internal finder method to find all products ordered

...

};

public abstract java util Collection ejbSelectProductsForOrderInEntity()

throws FinderException{

//internal finder method to find products for a specific

//order instance

...

}

}

9.6.8 Standard application exceptions for Entities

The EJB specification defines the following standard application exceptions:

Sun Microsystems Inc.

•javax.ejb.CreateException

•javax.ejb.DuplicateKeyException

•javax.ejb.FinderException

•javax.ejb.ObjectNotFoundException

•javax.ejb.RemoveException

This section describes the use of these exceptions by entity beans with container managed persistence. The responsibilities for throwing the exceptions apply to the data access methods generated by the Persistence Manager Provider’s tools.

9.6.8.1 CreateException

From the client’s perspective, a CreateException (or a subclass of CreateException) indicates that an application level error occurred during the create<METHOD>(...) operation. If a client receives this exception, the client does not know, in general, whether the entity object was created but not fully initialized, or not created at all. Also, the client does not know whether or not the transaction has been marked for rollback. (However, the client may determine the transaction status using the

UserTransaction interface.)

Both the Persistence Manager and the Bean Provider may throw the CreateException (or subclass of CreateException) from the ejbCreate<METHOD>(...) and ejbPostCreate<METHOD>(...) methods to indicate an application-level error from the create or initialization operation. Optionally, the Persistence Manager or Bean Provider may mark the transaction for rollback before throwing this exception.

The Persistence Manager or Bean Provider is encouraged to mark the transaction for rollback only if data integrity would be lost if the transaction were committed by the client. Typically, when a CreateException is thrown, it leaves the database in a consistent state, allowing the client to recover. For example, the ejbCreate<METHOD> method may throw the CreateException to indicate that the some of the arguments to the create<METHOD>(...) methods are invalid.

The Container treats the CreateException as any other application exception. See Section 17.3.

9.6.8.2 DuplicateKeyException

The DuplicateKeyException is a subclass of CreateException. It is thrown by the Persistence Manager’s ejbCreate<METHOD>(...) methods to indicate to the client that the entity object cannot be created because an entity object with the same key already exists. The unique key causing the violation may be the primary key, or another key defined in the underlying database.

Normally, the Persistence Manager should not mark the transaction for rollback before throwing the exception.

When the client receives the DuplicateKeyException, the client knows that the entity was not created, and that the client’s transaction has not typically been marked for rollback.

Sun Microsystems Inc

Instance life cycle contract between the bean, the container, and the persistence managerEnterprise JavaBeans 2.0, Public Draft Entity

9.6.8.3 FinderException

From the client’s perspective, a FinderException (or a subclass of FinderException) indicates that an application level error occurred during the find(...) operation. Typically, the client’s transaction has not been marked for rollback because of the FinderException.

The Persistence Manager throws the FinderException (or subclass of FinderException) from the ejbFind<METHOD>(...), ejbSelect<METHOD>(..), or ejbSelect<METHOD>InEntity(...) method to indicate an application-level error in the finder or select method. The Persistence Manager should not, typically, mark the transaction for rollback before throwing the

FinderException.

The Container treats the FinderException as any other application exception. See Section 17.3.

9.6.8.4 ObjectNotFoundException

The ObjectNotFoundException is a subclass of FinderException. The Persistence Manager throws the ObjectNotFoundException from the ejbFind<METHOD>(...), ejbSelect<METHOD>(..), or ejbSelect<METHOD>InEntity(...) method to indicate that the requested entity object does not exist.

Only single-object finder or select methods (see Subsections 9.6.6 and 9.6.7) should throw this exception. Multi-object finders must not throw this exception. Multi-object finders should return an empty collection as an indication that no matching objects were found.

9.6.8.5 RemoveException

From the client’s perspective, a RemoveException (or a subclass of RemoveException) indicates that an application level error occurred during a remove(...) operation. If a client receives this exception, the client does not know, in general, whether the entity object was removed or not. The client also does not know if the transaction has been marked for rollback. (However, the client may determine the transaction status using the UserTransaction interface.)

The Persistence Manager throws the RemoveException (or subclass of RemoveException) from the ejbRemove() method to indicate an application-level error from the entity object removal operation. Optionally, the Persistence Manager may mark the transaction for rollback before throwing this exception.

The Persistence Manager is encouraged to mark the transaction for rollback only if data integrity would be lost if the transaction were committed by the client. Typically, when a RemoteException is thrown, it leaves the database in a consistent state, allowing the client to recover.

The Container treats the RemoveException as any other application exception. See Section 17.3.