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 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 implemented for exception-handling.
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 specified for the associated exception code. You can get this value for a given exception code by using the ExceptionCode.getErrorLoggingLevel
method.
See Trace Logging Concepts for logging details.
As a general rule, a server exception will result in a rollback of any current transaction. The rollback occurs when the object save
method is called or an UpdatingBatch
instance is executing. Any attempt to make another server call with this transaction will fail. This is particularly 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 fatal (the isFatal
flag is only used by object or content retrieval calls; that is, those object or content accessor methods prefixed by "get_" as opposed to "fetch_").
Note: Non-fatal exceptions occurring in a call to fetch an object (accessor methods prefixed by "fetch_") do not cause a rollback of the current transaction.
Exception codes are constants identifying the exceptions 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 identifying 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 occurring in the server by enabling trace logging (see Enabling Trace Logging for All Subsystems.
Exception-chaining is used primarily to chain an external exception (such as Java™ standard exceptions) to a Content Engine runtime exception. The ErrorStack
class stores the exception causes (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.