How to define custom exception class in Java, the easiest way?

java

exception-handling

best-practices

custom-exceptions

byAlex Kataev·Aug 30, 2024

To define a custom exception in Java, extend Exception for checked exceptions, or RuntimeException for unchecked exceptions. Always implement two constructors: a no-argument exception and another to include an error message.

Here's a simple example:

public class MyCustomException extends Exception {
    public MyCustomException() { super(); } // Default constructor throws exception with no message
    public MyCustomException(String message) { super(message); } // Overloaded constructor for specific message
}

Simply put, MyCustomException in this case is your custom exception. You can then use these constructors to raise an exception with or without an error message.

Core principles of crafting custom exceptions

When aiming to create the perfect custom exception for your Java application, a few core principles can guide you:

Extend Correctly: First and foremost, your custom exception needs to extend Exception or RuntimeException based on your use case.
Single Responsibility: Keep your exceptions focused. Each custom exception should encapsulate a single type of error.
Create meaningful constructors: Besides the basic constructors, consider adding ones that accept a Throwable cause or both a message and a cause.
Using IDE Templates: The Java compiler might add constructors you don't need. Use IDE templates to control what gets generated.
Superclass Constructor: Recall that you need to explicitly call the superclass' constructor.

Through these principles, you can create custom exceptions that are meaningful, robust, and intuitive to use in your error-handling logic.

Custom exception best practices

Defining constructors for various scenarios

Apart from defining constructors that accept a message, consider adding constructors that accept Throwable causes and combinations of message and cause.

Here's an example:

public class MyCustomException extends Exception {
    // Constructor taking message and cause as arguments
    public MyCustomException(String message, Throwable cause) { //Cause that havoc
        super(message, cause);
    }
    
    // Constructor taking message, cause, suppression enabled, and writable stack trace as arguments
    public MyCustomException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) { //No stack trace is gonna stop us!
        super(message, cause, enableSuppression, writableStackTrace);
    }
}

Adding custom methods for more insights

getMessage() often suffices, but sometimes you may need to provide more context information. You can add additional methods:

public class MyCustomException extends Exception {
    private final String detail;

    public MyCustomException(String message, String detail) { // Give me the details, stat!
        super(message);
        this.detail = detail;
    }

    // Additional method to fetch details about the exception
    public String getDetailMessage() {
        return detail;
    }
}

Optimizing stack trace handling

For performance reasons, you may wish to modify stack trace handling:

public class MyCustomException extends Exception {
    @Override
    public Throwable fillInStackTrace() { // I have my own way of filling this stack trace!
        return this; // return 'this' to skip filling the stack trace
    }
}