An Exception Class Template
Jakob Jenkov |
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.
Tweet | |
Jakob Jenkov |