Exception Handling

Rather than using a hierarchical design for exceptions, Content Engine exception handling is based on a single exception class (EngineRuntimeException) for all runtime exceptions. The error codes and associated message text for an exception are defined in a separate class (ExceptionCode) and returned as objects in the exception instances. Additional classes implement individual error records (exception causes) and an error stack that is used to store the error records. The ErrorRecord and ErrorStack classes are used for chaining exceptions.

The com.filenet.api.exception package contains the classes that are implemented for exception handling.

Exceptions

The EngineRuntimeException class is used for all unchecked exceptions. Constructors are available for specifying parameter values in use at the time of the exception, and for specifying exceptions to chain. Methods on this class include getExceptionCode and getMessage (or getLocalizedMessage) to return the identifier (code) for the exception and the associated message text.

Exceptions are logged based on the logging level that is specified for the associated exception code. You can get this value for an exception code by using the ExceptionCode.getErrorLoggingLevel method.

For information about logging details, see Trace Logging for logging details.

Server-SideExceptions

As a rule, a server exception results in a rollback of any current transaction. The rollback occurs when the object's save method is called or an UpdatingBatch instance is running. Any attempt to make another server call with this transaction fails. This is relevant within the context of a user transaction because the calling code must catch all exceptions and initiate a rollback. You can use the ExceptionCode.isFatal method to determine whether an exception was unrecoverable (the isFatal flag is used only by object or content retrieval calls; that is, object or content accessor methods that are prefixed by "get_" as opposed to "fetch_").

Note: Non-fatal exceptions that occur in a call to fetch an object (accessor methods prefixed by "fetch_") do not cause a rollback of the current transaction.

Exception Codes

Exception codes are constants that identify the exceptions that are generated by the Content Engine server and the API. There is a one-to-one relationship between an exception code and the associated message. All exception codes are defined in the ExceptionCode class. The exception codes are prefixed by characters that identify the categorical exception group, such as API_, CONTENT_, or TRANSPORT_. Methods on this class include getErrorLoggingLevel. The ErrorLoggingLevel is used to control when an exception is sent to the server's error log file. Normal application errors, such as E_OBJECT_NOT_FOUND, are not sent to the server's error log. However, if necessary, you can capture all exceptions that occur in the server by enabling trace logging (see Enabling Trace Logging for All Subsystems.

Exception Chaining

Exception chaining is used primarily to chain an external exception, such as a Java™ standard exception, to a Content Engine runtime exception. The ErrorStack class stores the exception causes, which are implemented as ErrorRecord instances. When a chained exception is returned, the top record of the ErrorStack instance is converted into an EngineRuntimeException instance that holds the ErrorStack reference. This EngineRuntimeException instance is thrown to the client, allowing navigation through the stack to discover the causes.