Application Exceptions

The Bean Provider defines application exceptions. Application exceptions that are checked exceptions may be defined as such by being listed in the throws clauses of the methods of the bean's business interface, home interface, component interface, and web service endpoint. An application exception that is an unchecked exception is defined as an application exception by annotating it with the ApplicationException metadata annotation, or denoting it in the deployment descriptor with the application-exception element.

Example of runtime application exception (using annotation):

package by.iba;

import javax.ejb.ApplicationException;
					
@ApplicationException
// NOTE: This is the same as @ApplicationException(rollback=false)
public class InvalidEmployeeException extends RuntimeException {
	
	InvalidEmployeeException() {
	}
	
	InvalidEmployeeException(String s) {
		super(s);
	}	
}
					

NOTE: ApplicationException may be applied to both CHECKED and UNCHECKED exceptions.

Example of runtime application exception (using deployment descriptor):

package by.iba;

public class InvalidEmployeeException extends RuntimeException {
	
	InvalidEmployeeException() {
	}
	
	InvalidEmployeeException(String s) {
		super(s);
	}	
}
					

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar
		xmlns="http://java.sun.com/xml/ns/javaee"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
			http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
		version="3.0">

	<description>Sample of application exception</description>
	<assembly-descriptor>
		<application-exception>
			<exception-class>by.iba.InvalidEmployeeException</exception-class>
		</application-exception>
	</assembly-descriptor>
</ejb-jar>

					
					

The session bean may use the application exception now:

package by.iba.ejb;					
					
@Stateless					
public class PayrollBean implements Payroll {
	
	public int getTaxDeductions(Employee emp) {
		// ...
		throw new InvalidEmployeeException("Employee " + emp + " is invalid !");
	}
}
					

Because application exceptions are intended to be handled by the CLIENT, and not by the System Administrator, they should be used only for reporting business logic exceptions, not for reporting system level problems.

The Bean Provider is responsible for throwing the appropriate application exception from the business method to report a business logic exception to the client.

An application exception DOES NOT automatically result in marking the transaction for rollback unless the ApplicationException annotation is applied to the exception class and is specified with the rollback element value true or the application-exception deployment descriptor element for the exception specifies the rollback element as true. The rollback subelement of the application-exception deployment descriptor element may be explicitly specified to OVERRIDE the rollback value specified or defaulted by the ApplicationException annotation.

Example of runtime application exception which causes transaction ROLLBACK (using annotation):

package by.iba;

import javax.ejb.ApplicationException;
					
@ApplicationException(rollback=true)
public class InvalidEmployeeException extends RuntimeException {
	
	InvalidEmployeeException() {
	}
	
	InvalidEmployeeException(String s) {
		super(s);
	}	
}
					

NOTE: ApplicationException may be applied to both CHECKED and UNCHECKED exceptions.

Example of runtime application exception which causes transaction ROLLBACK (using deployment descriptor):

package by.iba;

public class InvalidEmployeeException extends RuntimeException {
	
	InvalidEmployeeException() {
	}
	
	InvalidEmployeeException(String s) {
		super(s);
	}	
}
					

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar
		xmlns="http://java.sun.com/xml/ns/javaee"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
			http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
		version="3.0">

	<description>Sample of application exception causing ROLLBACK</description>
	<assembly-descriptor>
		<application-exception>
			<exception-class>by.iba.InvalidEmployeeException</exception-class>
			<rollback>true</rollback>
		</application-exception>
	</assembly-descriptor>
</ejb-jar>

					

The Bean Provider MUST do one of the following to ensure data integrity before throwing an application exception from an enterprise bean instance:

The Bean Provider is also responsible for using the standard EJB application exceptions (javax.ejb.CreateException, javax.ejb.RemoveException, javax.ejb.FinderException, and subclasses thereof) for beans written to the EJB 2.1 and earlier client view.

Bean Providers may define subclasses of the standard EJB application exceptions and throw instances of the subclasses in the enterprise bean methods. A subclass will typically provide more information to the client that catches the exception.

System Exceptions

A system exception is an exception that is a java.rmi.RemoteException (or one of its subclasses) or a RuntimeException that is not an application exception.

An enterprise bean business method, message listener method, business method interceptor method, or lifecycle callback interceptor method may encounter various exceptions or errors that prevent the method from successfully completing. Typically, this happens because the exception or error is unexpected, or the exception is expected but the EJB Provider does not know how to recover from it. Examples of such exceptions and errors are: failure to obtain a database connection, JNDI exceptions, unexpected RemoteException from invocation of other enterprise beans, unexpected RuntimeException, JVM errors, and so on.

If the enterprise bean method encounters a system-level exception or error that does not allow the method to successfully complete, the method should throw a suitable non-application exception that is compatible with the method╤Нs throws clause. While the EJB specification does not prescribe the exact usage of the exception, it encourages the Bean Provider to follow these guidelines:

Note that the javax.ejb.EJBException is a subclass of the java.lang.RuntimeException, and therefore it does not have to be listed in the throws clauses of the business methods.

The container catches a non-application exception; logs it (which can result in alerting the System Administrator); and, unless the bean is a message-driven bean, throws the javax.ejb.EJBException or, if the web service client view is used, the java.rmi.RemoteException. If the EJB 2.1 client view is used, the container throws the java.rmi.RemoteException (or subclass thereof) to the client if the client is a REMOTE client, or throws the javax.ejb.EJBException (or subclass thereof) to the client if the client is a LOCAL client. In the case of a message-driven bean, the container logs the exception and then throws a javax.ejb.EJBException that wraps the original exception to the resource adapter.

The Bean Provider can rely on the container to perform the following tasks when catching a non-application exception:

This means that the Bean Provider DOES NOT have to perform any cleanup actions before throwing a non-application exception. It is the container that is responsible for the CLEANUP.

Exceptions Metadata Annotations

The ApplicationException annotation is applied to an exception to denote that it is an application exception and should be reported to the client DIRECTLY (i.e., unwrapped). The ApplicationException annotation may be applied to both checked and unchecked exceptions. The rollback element is used to indicate whether the container must cause the transaction to rollback when the exception is thrown.

@Target(TYPE) @Retention(RUNTIME)
public @interface ApplicationException {
	boolean rollback() default false;
}