An Exception Class Template

AppException
ErrorInfo

Jakob Jenkov
Last update: 2014-05-26

The first place to start is to design an exception class which can contain all the necessary information.

As mentioned in earlier texts, the error information may be extended or changed as the exception is propagated up the call stack. Therefore, the exception cannot just have this information hardcoded.

Instead, it will keep error information in a separate ErrorInfo object. As the exception is propagated up the call stack, the upper layers of the code can add additional ErrorInfo objects to the error. Thus, rather than having a single ErrorInfo object internally, the exception has an internal list of ErrorInfo objects.

AppException

Here is an example AppException class with the ErrorInfo list:

public class AppException extends Exception {

  protected List<ErrorInfo> errorInfoList = new ArrayList<ErrorInfo>();


  public AppException() {
  }

  public ErrorInfo addInfo(ErrorInfo info){
    this.errorInfoList.add(info);
    return info;
  }

  public ErrorInfo addInfo(){
    ErrorInfo info = new ErrorInfo();
    this.errorInfoList.add(info);
    return info;
  }

  public List<ErrorInfo> getErrorInfoList() {
    return errorInfoList;
  }
}

It's a very simple exception class. No information can be contained in it, except ErrorInfo instances. Even the root cause (Throwable) cannot be contained in this exception. This too, is kept in the ErrorInfo instances.

ErrorInfo

Now that you have seen the AppException class, let's look at the ErrorInfo class, which contains the error information. Here is an example ErrorInfo class:

public class ErrorInfo {

    protected Throwable cause                = null;
    protected String    errorId              = null;
    protected String    contextId            = null;

    protected int       errorType            = -1;
    protected int       severity             = -1;

    protected String    userErrorDescription = null;
    protected String    errorDescription     = null;
    protected String    errorCorrection      = null;

    protected Map<String, Object> parameters =
            new HashMap<String, Object>();
}

I have left out the getter and setter methods to make the example shorter.

The following table describes the fields in the ErrorInfo class.

Field	Description
cause	The error cause, if an alien exception is caught and wrapped.
errorId	A unique id that identifies this error. The errorId tells what went wrong, like `FILE_LOAD_ERROR`. The id only has to be unique within the same context, meaning the combination of contextId and errorId should be unique througout your application.
contextId	A unique id that identifies the context where the error occurred. The contextId tells where the error occurred (in what class, component, layer etc.). The contextId and errorId combination used at any specific exception handling point should be unique throughout the application.
errorType	The errorType field tells whether the error was caused by errornous input to the application, an external service that failed, or an internal error. The idea is to use this field to indicate to the exception catching code what to do with this error. Should only the user be notified, or should the application operators and developers be notified too?
severity	Contains the severity of the error. E.g. WARNING, ERROR, FATAL etc. It is up to you to define the severity levels for your application.
userErrorDescription	Contains the error description to show to the user. Note: In an internationalized application this field may just contain a key used to lookup an error message in a text bundle, so the user can get the error description in his or her own language. Also keep in mind that many errors will be reported to the user with the same standard text, like "An error occurred internall. It has been logged, and the application operators has been notified". Thus, you may want to use the same user error description or error key for many different errors.
errorDescription	Contains a description of the error with all the necessary details needed for the application operators, and possibly the application developers, to understand what error occurred.
errorCorrection	Contains a description of how the error can be corrected, if you know how. For instance, if loading a configuration file fails, this text may say that the operator should check that the configuration file that failed to load is located in the correct directory.
parameters	A Map of any additional parameters needed to construct a meaningful error description, either for the users or the application operators and developers. For instance, if a file fails to load, the file name could be kept in this map. Or, if an operation fails which require 3 parameters to succeed, the names and values of each parameter could be kept in this Map.

In the following texts I will show you how to use the AppException and ErrorInfo classes to throw exceptions, wrap exceptions, propagate exceptions, catch exceptions etc.

Next: Throwing the AppException

Tweet
	Jakob Jenkov