Sun Microsystems Inc.

9.1.9 Standard application exceptions for Entities

The EJB specification defines the following standard application exceptions:

•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 bean-managed persistence. The use of the exceptions by entity beans with container-managed persistence is the same, with one additional element: The responsibilities for throwing the exceptions apply to the data access methods generated by the Container Provider’s tools.

9.1.9.1 CreateException

From the client’s perspective, a CreateException (or a subclass of CreateException) indicates that an application level error occurred during the create(...) 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.)

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

The 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, ejbCreate may throw the CreateException to indicate that the some of the arguments to the create(...) methods are invalid.

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

9.1.9.2 DuplicateKeyException

The DuplicateKeyException is a subclass of CreateException. It is thrown by the ejbCreate(...) 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.

Sun Microsystem Inc

Normally, the Bean Provider 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.

9.1.9.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 Bean Provider throws the FinderException (or subclass of FinderException) from the ejbFind<METHOD>(...) methods to indicate an application-level error in the finder method. The Bean Provider should not, typically, mark the transaction for rollback before throwing the FinderException.

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

9.1.9.4 ObjectNotFoundException

The ObjectNotFoundException is a subclass of FinderException. It is thrown by the ejbFind<METHOD>(...) methods to indicate that the requested entity object does not exist.

Only single-object finders (see Subsection 9.1.8) 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.1.9.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 Bean Provider 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 Bean Provider may mark the transaction for rollback before throwing this exception.

The 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 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 12.3.