{"id":11,"date":"2003-09-03T21:36:49","date_gmt":"2003-09-04T02:36:49","guid":{"rendered":"http:\/\/coding.mu\/index.php\/archives\/2003\/09\/03\/ejb-exception-handling\/"},"modified":"2025-11-06T18:51:14","modified_gmt":"2025-11-06T18:51:14","slug":"ejb-exception-handling","status":"publish","type":"post","link":"https:\/\/priscimon.net\/coding\/2003\/09\/03\/ejb-exception-handling\/","title":{"rendered":"EJB Exception Handling"},"content":{"rendered":"\n

If you do a web search for the keywords “EJB” and “exception”, you’ll find the same handful of articles published at IBM DeveloperWorks. Those are, unfortunately, not suitable for beginners. This post is a simpler guide to handling exceptions in EJB.<\/p>\n\n\n\n

Definitions<\/strong><\/h2>\n\n\n\n

A checked exception<\/em> is derived from java.lang.Exception<\/strong> but is not a subclass of java.lang.RuntimeException<\/strong>.<\/p>\n\n\n\n

An unchecked exception<\/em> is derived from java.lang.RuntimeException<\/strong> and is thrown by the Java Virtual Machine (JVM).<\/p>\n\n\n\n

A system exception<\/em> is thrown by the system and is not recoverable. For example, an EJB container losing its connection to a database server causes a system exception; similarly, a failed remote object method call causes a system exception.<\/p>\n\n\n\n

An application exception<\/em> is specific to the application and is thrown to signal a business rule that is not satisfied. For example, an application exception is raised when the balance for a savings account becomes negative.<\/p>\n\n\n\n

System Exception<\/strong><\/h2>\n\n\n\n

A system exception is unchecked and is derived from java.lang.RuntimeException<\/strong>. Because it is unpredictable, it is typically not handled in application code and is handled instead by the EJB container.<\/p>\n\n\n\n

A container automatically wraps an EJBException<\/strong> in a RemoteException<\/strong> and throws it to the client. Although this causes some information to be lost, it is not a problem because a RemoteException<\/strong> is a system error from which the client cannot recover.<\/p>\n\n\n\n

Therefore, for an exception to be caught by the container and sent to the client, a developer must wrap it in an EJBException. <\/strong>The following code extract demonstrates this.<\/p>\n\n\n\n

...\npublic String ejbCreate(String id, String username, String password) \n    throws CreateException {\n\n    try {\n        this.id = id;\n        this.username = username;\n        this.password = password;\n\n        insertRecord();\n    } catch (SQLException e) {\n        throw new EJBException(e); \/\/ swallow the SQLException\n    } catch (Exception e) {\n        throw new EJBException(e);\n    }\n    return id;\n}\n...<\/code><\/pre>\n\n\n\n
Since an EJBException<\/strong> is a system (and unchecked) exception, it does not\u00a0 have to be declared in the throws<\/code> clause.<\/p>\n\n\n\n
create(...)<\/code> is a delegate method of the Home<\/em> object created by the container, and if the method fails due to a system error, the container throws a RemoteException<\/strong>. Therefore, in the Home<\/em> interface of the remote object, the create(...)<\/code> method must throw RemoteException<\/strong>, like this:<\/p>\n\n\n\n
...\npublic UserAccount create(String id, String username, String password) \n    throws RemoteException;\n...<\/code><\/pre>\n\n\n\n
The client code then looks like this:<\/p>\n\n\n\n
...\ntry {\n    UserAccount userAccount = \n        userAccountHome.create(\"1001\", \"user\", \"password\");\n} catch (CreateException e) {\n    System.out.println(\"Object could not be created\");\n} catch (RemoteException e) {\n    System.out.println(\"EJB Error: \" + e.getMessage() );\n} catch (Exception e) {\n    e.printStackTrace();\n}\n...<\/code><\/pre>\n\n\n\n
In this example, the container notifies the client about a system exception by way of the RemoteException<\/strong>.<\/p>\n\n\n\n
Application Exception<\/strong><\/h2>\n\n\n\n
An application exception is checked and, therefore, must be declared in a throws<\/code> clause. It is thrown explicitly by code to indicate an error linked to the business rules. For example, debiting a sum of money that makes a savings account balance go negative triggers a SavingsAccountDebitException<\/strong>. An application exception is needed for a client to be alerted of an error, to determine what caused it, and to notify users. An EJB container does not intercept an application exception because it does not know how to handle it. Consequently, the container does not log an application exception be default.<\/p>\n\n\n\n
A developer does not need to wrap such an application exception in an EJBException<\/strong>. In fact, to prevent the container from hi-jacking<\/em> the exception, a developer must not do this.<\/p>\n\n\n\n
Below is a code extract that shows a typical application exception handling.<\/p>\n\n\n\n
...\npublic void debit(double amount) \n    throws SavingsAccountDebitException {\n\n    if (this.balance == 0) {\n        throw new SavingsAccountDebitException(\n            \"Cannot make a debit\");\n    }\n\n    try {\n        balance -= amount;\n        updateRecord();\n    } catch (SQLException e) {\n        throw new EJBException(e);\n    } catch (Exception e) {\n        throw new EJBException(e);\n    }\n}\n...<\/code><\/pre>\n\n\n\n
Notice that when an EJBException<\/strong> is thrown, it can be left out in the throws<\/code> clause. Also, this code does not demonstrate how transactions are rolled back, a topic which is covered later in this post.<\/p>\n\n\n\n
In the remote interface for the bean containing the above code, a throws clause declaring SavingsAccountDebitException<\/strong> is needed, as in the following.<\/p>\n\n\n\n
...\npublic void debit(double amount) \n    throws SavingsAccountDebitException;\n...<\/code><\/pre>\n\n\n\n
The client code using the remote interface could look like this:<\/p>\n\n\n\n
...\ntry {\n    savingsAccount.debit(1000.00);\n} catch (SavingsAccountDebitException e) {\n    System.out.println(e.getMessage() );\n} catch (Exception e) {\n    e.printStackTrace();\n}\n...<\/code><\/pre>\n\n\n\n
Observe that the application exception is successfully propagated to the client and is ignored by the container. The client uses the information from the exception to notify users; in this example, it displays an error message.<\/p>\n\n\n\n
Exceptions and Transactions<\/strong><\/h2>\n\n\n\n
How transactions are managed is affected by how exceptions are handled.<\/p>\n\n\n\n
A transaction managed by the container is automatically rolled back when a system exception occurs. This happens because the container intercepts system exceptions. However, when an application exception occurs, the container does not intercept it and, therefore, does not roll back a transaction.<\/p>\n\n\n\n
The following code extract illustrates this point.<\/p>\n\n\n\n
...\nEntityContext ctx;\n...\npublic void ejbRemove() \n    throws RemoteException {\n    try {\n        deleteRecord();\n    } catch (SavingsAccountDeleteException e) {\n        ctx.setRollbackOnly()\n        throw new RemoveException(e.getMessage() );\n    } catch (SQLException e) {\n        throw new EJBException(e);\n    } catch (Exception e) {\n        throw new EJBException(e);\n    }\n}\n...<\/code><\/pre>\n\n\n\n
Conclusion<\/strong><\/p>\n\n\n\n
This post applies to remote<\/em> EJB; when local<\/em> EJB is used, RemoteException<\/strong> is never thrown.<\/p>\n\n\n\n
As shown, handling exceptions in EJB is different to how it is done in standalone Java applications. In fact, the guidelines for dealing with each situation can be contradictory in some cases. For a comparison, please refer to the post Exception Handling Best Practice<\/a>.<\/p>\n\n\n\n
These are the four rules to follow for proper handling of exceptions in EJB:<\/p>\n\n\n\n