Overview

As the Java language provides full support for exceptions, they are the recommended mechanism for handling errors in an IBM Cúram Social Program Management application. The advantage of using exceptions to handle errors is that it saves the developer from having to check the status of each operation attempted. A single try..catch construct can enclose many statements, each of which could raise an exception.

In a Cúram application, exceptions can originate from various parts of generated code. For example the Database Access Layer (DAL) throws exceptions in the event of a database error, application developers can throw pre-defined exceptions or customized exceptions. There are two basic forms of exceptions used; checked and unchecked.

Checked exceptions are subclasses of curam.util.exception.AppException and curam.util.exception.InformationalException. These exceptions must be explicitly caught or listed in the throws clause of the method.

Unchecked exceptions are subclasses of curam.util.exception.AppRuntimeException. These exceptions do not have to be explicitly handled as they inherit from the Java Exception and RuntimeException classes respectively. Typically, database problems (such as a RecordLockedException) are thrown as unchecked exceptions. This means that there is no need for code to tediously check for a RecordLockedException each time the database is accessed.

In a Cúram application, checked exceptions can arrive at the Remote Interface Layer (RIL), despite being checked, a throws clause can unwind all the way to the RIL. Once here they are converted to a different form of exception which is thrown to the client, and may write information from the exception to the log file. To avoid this a developer can write code to catch exceptions and handle them and/or re-throw them before the exception reaches the RIL.

The following happens when the RIL catches a checked exception:

• The text for the exception is loaded from a message catalog file.
• If the exception is loggable, then the text will be formatted, with arguments inserted and written to the log file in the default server language.
• If the exception is loggable and includes a stack trace this will be written to the log file.
• An exception is created and thrown to the client. This contains the name of the message catalog, the ID of the message, and the exception arguments if any.
• The client receives the exception and uses the catalog name and message ID to look-up a localized version of the message. It then inserts and formats the arguments into a message and displays the message.

The RIL also catches unchecked exceptions to perform default actions.

• The text for the exception is loaded from a message catalog file.
• The text is formatted with arguments inserted and written to the log file in the default server language.
• A stack trace is written to the log file.
• A new exception is created and thrown to the client. This exception states that the original exception was Unhandled. The original exception is mapped because the descriptive text is at too low a level to make sense to a user.

  The newly created exception contains a nested exception which has the details of the original exception - namely the name of the message catalog, the ID of the message, and the exception arguments if any.

  This mapping happens for all but four unchecked exceptions. These exceptions are left untouched because the descriptive text produced is readable to a user. These are RecordChangedException. RecordDeletedException, RecordLockedException and ReadmultiMaxException.

• When the client receives the exception and uses the catalog name and message ID to look-up a localized version of the message. It then inserts and formats the arguments into the message and displays the message.