How to Create a Custom Java Exception

Java programming language uses special exception classes to handle program errors and exceptional events in the system. Java organizes exceptions into 3 basic types – Exception, Error and RuntimeException.

The Exception and Error classes are root level classes. The Exception class and its derived classes indicates internal application errors. The Error class and its derived classes indicates serious external errors encountered in an application such as a hard disk failure or memory failure.

One special derived class of Exception is the RuntimeException. RuntimeException and its derived classes are used for internal application errors that cannot be recovered from. For example, when an operation is attempted on a null object it throws NullPointerException which is derived from RuntimeException.

Exception classes and its derived classes are known as checked exceptions since programmers must handle them in the code. RuntimeException and its derived classes are known as unchecked exceptions since handling them is optional. Error and its derived classed are also unchecked exceptions.

How to Write Your Own Custom Java Exceptions

If you are building a large Java application, it is important to define your own custom classes for error conditions in your applications. Exceptions in Java are a controversial topic and the following sections are based on my own opinion.

When you build your own Java exceptions start with two root level Exceptions. These high level exceptions will indicate recoverable logical errors and non recoverable system errors. I usually name them as AppLogicalException and AppSystemException. AppLogicalException extends from Exception and hence is a checked exception and AppSystemException extends from RuntimeException and hence is an unchecked exception. All exceptions in your application depending on whether they are recoverable should be derived from one of these classes.

Following are examples for custom Java exceptions. As as example I have added an additional parameter called error code. This is purely optional and is only required if you are going to use the same exception class for closely related errors. In this case error code can be used for identifying a specific sub type.

// AppSystemException.java
// Base exception class for all application non recoverable errors
public class AppSystemException extends RuntimeException {
    
    // special code for use where message is not suitable
    private int errorCode;

    public int getErrorCode() {
        return errorCode;
    }

    public void setErrorCode(int errorCode) {
        this.errorCode = errorCode;
    }
    
    public AppSystemException(int errorCode) {
        this.errorCode = errorCode;
    }
    
    public AppSystemException(int errorCode, Throwable t) {
        super(t);
        this.errorCode = errorCode;
    }
    
    public AppSystemException(int errorCode, String message, Throwable t) {
        super(message, t);
        this.errorCode = errorCode;
    }
}

// AppLogicalException.java
// Base exception class for all application recoverable errors
public class AppLogicalException extends Exception {

    // special code for use where message is not suitable
    private int errorCode;

    public int getErrorCode() {
        return errorCode;
    }

    public void setErrorCode(int errorCode) {
        this.errorCode = errorCode;
    }

    public AppLogicalException(int errorCode) {
        this.errorCode = errorCode;
    }

    public AppLogicalException(int errorCode, Throwable t) {
        super(t);
        this.errorCode = errorCode;
    }

    public AppLogicalException(int errorCode, String message, Throwable t) {
        super(message, t);
        this.errorCode = errorCode;
    }
}

Do you have a programming problem that you are unable to solve? Please send us your problem and we will publish the solution! Please email us.

Leave a Reply