EJB.12.3 Container Provider Responsibilities

This section describes the responsibilities of the container provider for handling exceptions. The EJB architecture specifies the container's behavior for the following exceptions:

Exceptions from enterprise bean's business methods
Exceptions from container-invoked callbacks on the enterprise bean
Exceptions from management of container-managed transaction demarcation

EJB.12.3.1 Exceptions from an Enterprise Bean's Business Methods

Business methods are considered to be the methods defined in the enterprise bean's remote and home interface (including all their superinterfaces) and the following methods: ejbCreate(...) , ejbPostCreate(...) , ejbRemove() , and the ejbFind<METHOD> methods.

Table EJB.12-1 specifies how the container must handle the exceptions thrown by the business methods for beans with container-managed transaction demarcation. The table specifies the container's action as a function of the condition under which the business method executes and the exception thrown by the business method. The table also illustrates the exception that the client will receive and how the client can recover from the exception. (Section EJB.12.4 describes the client's view of exceptions in detail.)

Table EJB.12-2 specifies how the container must handle the exceptions thrown by the business methods for beans with bean-managed transaction demarcation. ^[3] The table specifies the container's action as a function of the condition under which the business method executes and the exception thrown by the business method. The table also illustrates the exception that the client will receive and how the client can recover from the exception. (Section EJB.12.4 describes the client's view of exceptions in detail.)

^[3] Note that the EJB specification allows only session beans to use bean-managed transaction demarcation.

Table EJB.12-1. Handling of Exceptions Thrown by a Business Method of a Bean with Container-Managed Transaction Demarcation

Method Condition	Method Exception	Container's Action	Client's View
Bean method runs in the context of the caller's transaction. ^[a] This case may happen with `Required` , `Mandatory` , and `Supports` attributes.	`AppException`	Re-throw `AppException`	Receives `AppException` . Can attempt to continue computation in the transaction, and eventually commit the transaction (the commit would fail if the instance called `setRollbackOnly())` .
	All other exceptions and errors	Log the exception or error. ^[b] Mark the transaction for rollback. Discard instance. ^[c] Throw `TransactionRolledBackException` to the client.	Receives `TransactionRolled BackException.` Continuing transaction is fruitless.
Bean method runs in the context of a transaction that the container started immediately before dispatching the business method. This case may happen with `Required` and `RequiresNew` attributes.	`AppException`	If the instance called `setRollbackOnly()` , then rollback the transaction, and re-throw `AppException` . Otherwise, attempt to commit the transaction, and then re-throw `AppException` .	Receives `AppException` . If the client executes in a transaction, the client's transaction is not marked for rollback, and client can continue its work.
	All other exceptions	Log the exception or error. Rollback the container-started transaction. Discard instance. Throw `RemoteException` .	Receives `RemoteException` . If the client executes in a transaction, the client's transaction is not marked for rollback, and client can continue its work.
Bean method runs with an unspecified transaction context. This case may happen with the `NotSupported` , `Never` , and `Supports` attributes.	`AppException`	Re-throw `AppException` .	Receives AppException. If the client executes in a transaction, the client's transaction is not marked for rollback, and client can continue its work.
	All other exceptions	Log the exception or error. Discard instance. Throw `RemoteException` .	Receives `RemoteException` . If the client executes in a transaction, the client's transaction is not marked for rollback, and client can continue its work.

^[a] The caller can be another enterprise bean or an arbitrary client program.

^[b] Log the exception or error means that the container logs the exception or error so that the system administrator is alerted of the problem.

^[c] Discard instance means that the container must not invoke any business methods or container callbacks on the instance.

Table EJB.12-2. Handling of Exceptions Thrown by a Business Method of a Session with Bean-Managed Transaction Demarcation

Bean Method Condition

Bean Method Exception

Container Action

Client Receives

Bean is stateful or stateless session.

AppException

Re-throw AppException

Receives AppException .

All other exceptions

Log the exception or error.

Mark for rollback a transaction that has been started, but not yet completed, by the instance.

Discard instance.

Throw RemoteException .

Receives RemoteException .

EJB.12.3.2 Exceptions from Container-Invoked Callbacks

This subsection specifies the container's handling of exceptions thrown from the container-invoked callbacks on the enterprise bean. It applies to the following callback methods:

The ejbActivate() , ejbLoad() , ejbPassivate() , ejbStore() , setEntityContext(EntityContext) , and unsetEntityContext() methods of the EntityBean interface.
The ejbActivate() , ejbPassivate() , and setSessionContext(SessionContext) methods of the SessionBean interface.
The afterBegin(), beforeCompletion() and afterCompletion(boolean) methods of the SessionSynchronization interface.

The container must handle all exceptions or errors from these methods as follows :

Log the exception or error to bring the problem to the attention of the system administrator.
If the instance is in a transaction, mark the transaction for rollback.
Discard the instance (i.e., the container must not invoke any business methods or container callbacks on the instance).
If the exception or error happened during the processing of a client invoked method, throw the java.rmi.RemoteException to the client. If the instance executed in the client's transaction, the container should throw the javax.transaction.TransactionRolledBackException because it provides more information to the client. (The client knows that it is fruitless to continue the transaction.)

EJB.12.3.3 `javax.ejb.NoSuchEntityException`

The NoSuchEntityException is a subclass of EJBException . If it is thrown by a method of an entity bean class, the container must handle the exception using the rules for EJBException described in Sections EJB.12.3.1 and EJB.12.3.2.

To give the client a better indication of the cause of the error, the container should throw the java.rmi.NoSuchObjectException to the client (which is a subclass of java.rmi.RemoteException ).

EJB.12.3.4 Non-Existing Session Object

If a client makes a call to a session object that has been removed, the container should throw the java.rmi.NoSuchObjectException to the client (which is a subclass of java.rmi.RemoteException ).

EJB.12.3.5 Exceptions from the Management of Container-Managed Transactions

The container is responsible for starting and committing the container-managed transactions, as described in Section EJB.11.6.2. This subsection specifies how the container must deal with the exceptions that may be thrown by the transaction start and commit operations.

If the container fails to start or commit a container-managed transaction, the container must throw the java.rmi.RemoteException to the client.

However, the container should not throw the java.rmi.RemoteException if the container performs a transaction roll back because the instance has invoked the setRollbackOnly() method on its EJBContext object. In this case, the container must roll back the transaction and pass the business method result or the application exception thrown by the business method to the client.

Note that some implementations of the container may retry a failed transaction transparently to the client and enterprise bean code. Such a container would throw the java.rmi.RemoteException after a number of unsuccessful tries .

EJB.12.3.6 Release of Resources

When the container discards an instance because of a system exception, the container should release all the resources held by the instance that were acquired through the resource factories declared in the enterprise bean environment (See Section EJB.14.4).

Note

While the container should release the connections to the resource managers that the instance acquired through the resource factories declared in the enterprise bean environment, the container cannot, in general, release "unmanaged" resources that the instance may have acquired through the JDK APIs. For example, if the instance has opened a TCP/IP connection, most container implementations will not be able to release the connection. The connection will be eventually released by the JVM garbage collector mechanism.

EJB.12.3.7 Support for Deprecated Use of `java.rmi.RemoteException`

The EJB 1.0 specification allowed the business methods, ejbCreate , ejbPostCreate , ejbFind<METHOD> , ejbRemove , and the container-invoked callbacks (i.e., the methods defined in the EntityBean , SessionBean , and SessionSynchronization inter-faces) implemented in the enterprise bean class to use the java.rmi.RemoteException to report non-application exceptions to the container.

This use of the java.rmi.RemoteException is deprecated in EJB 1.1 ”enterprise beans written for the EJB 1.1 specification should use the javax.ejb.EJBException instead.

The EJB 1.1 specification requires that a container support the deprecated use of the java.rmi.RemoteException . The container should treat the java.rmi.RemoteException thrown by an enterprise bean method in the same way as it is specified for the javax.ejb.EJBException .