EJB ApplicationException in JBoss EAP 8 / 7 / 6

Environment

• Red Hat JBoss Enterprise Application Platform (EAP)
  • 8
  • 7
  • 6

Issue

• EJB Application Exceptions in JBoss EAP 8
• EJB Application Exceptions in JBoss EAP 7

Resolution

As per the EJB specification, section 9.2.1 Application Exceptions in the EJB 3.2 specification [1], an application exception is a checked exception which is defined on the EJB's business interface for example HelloException is considered an application exception.

public interface MyEJBRemoteInterface {
  public String hello(String name) throws HelloException
}
public class MyEJB implements MyEJBRemoteInterface {
   public String hello(String name) throws HelloException {
      if(name == null) throw new HelloException();
      return "Hello " + name;
   }
}

If the application throws an unchecked exception such as an Error or RuntimeException (or any exception that extends those), then it can be designated as an ApplicationException using the annotation or deployment descriptor xml shown below.

@ApplicationException goes on your application exception class and allows you to control whether the transaction will be rolled back when the application is thrown.

Specifying using annotations

@ApplicationException(rollback=true)
public class MyApplicationException extends Exception {
   ...
}

Specifying using deployment descriptor (ejb-jar.xml)

  <application-exception>  
    <exception-class>com.jboss.examples.MyApplicationException</exception-class>  
    <rollback>true</rollback>  
  </application-exception>

If in your EJB method you are invoking some thing that throws a RuntimeException such as [2], then you would need to have a try / catch in your EJB method to wrap it to your ApplicationException class if you want to prevent rollback.

Notes

• If the EJB method invokes other services / methods / etc which could throw a RuntimeException, the EJB method should wrap the calls in a try / catch to catch the RuntimeException/Error and then throws an ApplicationException if you want to control the rollback or throw a checked exception back to the client.
• If the annotation @ApplicationException is used and the the EJB's interface/transfer objects/exception classes are in a custom module, then using the deployment descriptor is the recommended way to specify the application exceptions as annotations are not parsed by default when the class is not in the application.

Related Solutions

• module defined in jboss-deployment-structure.xml with fails to parse when annotations=true in JBoss EAP 7
• @ApplicationException is ignored for exceptions in other deployments

[1] Content from download.oracle.com is not included.EJB 3.2 specifiction
[2] Content from docs.oracle.com is not included.javax.ejb.ApplicationException
[3] Content from docs.oracle.com is not included.javax.ejb.EJBException

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.