🎓 A1Learner
🔍
0 of 40 lessons completed

Java Custom Exceptions

A custom exception is an exception class the program writes for its own failures. It carries a message that names the exact problem.

An exception class with a message

The class below extends Exception and stores the message through super. The method throws it when the box is empty.

public class Main {
  static String take(String box) throws EmptyBoxException {
    if (box.isEmpty()) {
      throw new EmptyBoxException("the box is empty");
    }
    return box;
  }

  public static void main(String[] args) {
    try {
      System.out.println(take(""));
    } catch (EmptyBoxException e) {
      System.out.println(e.getMessage());
    }
  }
}

class EmptyBoxException extends Exception {
  EmptyBoxException(String message) {
    super(message);
  }
}

Leaving a checked call unhandled

The same call without a catch or a throws declaration does not compile. The compiler message names the missing handling.

public class Main {
  static String take(String box) throws EmptyBoxException {
    if (box.isEmpty()) {
      throw new EmptyBoxException("the box is empty");
    }
    return box;
  }

  public static void main(String[] args) {
    System.out.println(take(""));
  }
}

class EmptyBoxException extends Exception {
  EmptyBoxException(String message) {
    super(message);
  }
}

The check passes good input through

A full box returns its content untouched. An empty box takes the catch path instead.

public class Main {
  static String take(String box) throws EmptyBoxException {
    if (box.isEmpty()) {
      throw new EmptyBoxException("the box is empty");
    }
    return box;
  }

  public static void main(String[] args) {
    try {
      System.out.println(take("apples"));
    } catch (EmptyBoxException e) {
      System.out.println(e.getMessage());
    }
    try {
      System.out.println(take(""));
    } catch (EmptyBoxException e) {
      System.out.println(e.getMessage());
    }
  }
}

class EmptyBoxException extends Exception {
  EmptyBoxException(String message) {
    super(message);
  }
}

Example

public class Main {
  static int takeFromShelf(int stock, int wanted) throws OutOfStockException {
    if (wanted > stock) {
      throw new OutOfStockException("not enough stock on the shelf");
    }
    return stock - wanted;
  }

  public static void main(String[] args) {
    try {
      System.out.println(takeFromShelf(10, 4));
      System.out.println(takeFromShelf(2, 5));
    } catch (OutOfStockException e) {
      System.out.println(e.getMessage());
    }
  }
}

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

Key points

  • A custom exception class extends Exception and passes its message to super.
  • Extending Exception makes the new exception checked.
  • A checked exception must be caught or declared with throws before the code compiles.
  • A method header with throws warns every caller about the failure it can throw.
  • A checked exception fits a condition the caller must face, like an empty box.
  • An unchecked exception fits a programming mistake, and IllegalArgumentException is one example.

In this example, the method returns the remaining stock for a valid order, and the custom exception reports the order the shelf cannot fill.

Try it Yourself

Edit the code, then press Run.

Running is simulated

Exercise

A class extends Exception directly. What does that make its objects?