Custom Exceptions

Built-in exceptions cover many general failures, but real projects also have business-rule failures. “Out of stock” is not a syntax or type error; it means a domain rule was violated.

Defining an exception class

A custom checked exception normally extends Exception. A simple class may initially contain only a constructor that forwards a detailed message to super(), with that message supplied at the throw site. Its name should express the failure clearly, allowing callers to recognize the category without parsing message text.

This lesson uses one class per file, with interfaces in separate files too. Match each filename to its type name. Keep files from the same example in one directory, and use separate directories for different examples to avoid duplicate class names.

OutOfStockException.java

public class OutOfStockException extends Exception {
    OutOfStockException(String message) {
        super(message);
    }
}

Main.java

public class Main {
    public static void main(String[] args) throws OutOfStockException {
        throw new OutOfStockException("Notebook is out of stock.");
    }
}

This Main.java only demonstrates throwing: its throws clause declares the exception it can propagate, so running it reports an uncaught exception. The stock example below shows how to catch it.

Stock example

IllegalArgumentException means the purchase quantity itself is invalid. OutOfStockException means the quantity is sensible but current inventory cannot satisfy it. The types express different levels of failure.

OutOfStockException.java

public class OutOfStockException extends Exception {
    OutOfStockException(String message) {
        super(message);
    }
}

Product.java

public class Product {
    private final String name;
    private int stock;

    Product(String name, int stock) {
        this.name = name;
        this.stock = stock;
    }

    void purchase(int quantity) throws OutOfStockException {
        if (quantity <= 0) {
            throw new IllegalArgumentException("Quantity must be greater than 0.");
        }
        if (quantity > stock) {
            throw new OutOfStockException(name + " is out of stock.");
        }
        stock -= quantity;
    }

    int getStock() {
        return stock;
    }
}

Main.java

public class Main {
    public static void main(String[] args) {
        Product product = new Product("Notebook", 5);
        try {
            product.purchase(3);
            System.out.println("Remaining stock: " + product.getStock());
            product.purchase(4);
        } catch (OutOfStockException exception) {
            System.out.println("Purchase failed: " + exception.getMessage());
        }
    }
}

Remaining stock: 2
Purchase failed: Notebook is out of stock.

Why custom exceptions matter

The value of a custom exception is semantics. After catching OutOfStockException, a UI can offer restocking or another product. After IllegalArgumentException, it should request a different quantity. Caller code can also log, retry, or rethrow these failures separately.