web server - Borland Technical Publications

Handling of EJB exceptions
Application-level exceptions
An EJB throws an application-level exception to indicate application-specific error
conditions, that is, business logic errors and not system problems. These applicationlevel
exceptions are exceptions other than java.ejb.EJBException. Application-level
exceptions are checked exceptions, which means you must check for them when you
call a method that potentially can throw this exception.
The EJB's business methods use application exceptions to report abnormal application
conditions, such as unacceptable input values or amounts beyond acceptable limits.
For example, a bean method that debits an account balance can throw an application
exception to report that the account balance is not sufficient to permit a particular debit
operation. A client can often recover from these application-level errors without having
to rollback the entire transaction.
The application or calling program gets back the same exception that was thrown and
this allows the calling program to know the precise nature of the problem. When an
application-level exception occurs, the EJB instance does not automatically rollback
the client's transaction. The client now has the knowledge and the opportunity to
evaluate the error message, take the necessary steps to correct the situation, and
recover the transaction. Otherwise, the client can abort the transaction.
Handling application exceptions
Because application-level exceptions report business logic errors, the client is
expected to handle these exceptions. While these exceptions can require transaction
rollback, they do not automatically mark the transaction for rollback. You often have the
option to retry the transaction, though there are times when you must abort and
rollback the transaction.
The bean Provider is responsible for ensuring that the state of the bean is such that, if
the client continues with the transaction, there is no loss of data integrity. If the Provider
cannot ensure this degree of integrity, then the bean marks the transaction for rollback.
Transaction rollback
When your client program gets an application exception, you must first check if the
current transaction has been marked for “rollback only”. For example, a client can
receive a javax.transaction.TransactionRolledbackException. This exception indicates
that the helper enterprise bean failed and the transaction has been aborted or marked
“rollback only”. In general, the client does not know the transaction context within which
the called enterprise bean operated. The called bean may have operated in its own
transaction context separate from the calling program's transaction context, or it may
have operated in the calling program's context.
If the EJB operated in the same transaction context as the calling program, then the
bean itself (or its container) may have already marked the transaction for rollback.
When the EJB container has marked a transaction for rollback, the client should stop
all work on the transaction. Normally, a client using declarative transactions will get an
appropriate exception, such as javax.transaction.TransactionRolledbackException.
Note that declarative transactions are those transactions where the container manages
the transaction details.
A client that is itself an EJB calls the javax.ejb.EJBContext.getRollbackOnly method to
determine if its own transaction has been marked for rollback or not.
For bean-managed transactions--those transactions managed explicitly by the client--
the client should rollback the transaction by calling the rollback method from the
java.transaction.UserTransaction interface.
180 BES Developer’s Guide