Throwing and declaring

Written Explanation

The throw statement

To raise an exception, create an object and throw it:

throw new IllegalArgumentException("age must be between 0 and 150, was " + age);

throw takes one thing: an object of a type that descends from Throwable. The Oracle tutorial states that only such objects can be thrown, and that exceptions are always thrown with this keyword, whether they come from your code, a library, or the runtime. As soon as throw executes, the method stops. Nothing after it in that method runs, and Java starts searching for a catch, as in lesson 1.

A common pattern is the guard clause: check the bad case at the top, throw, and let the rest of the method assume everything is fine.

void setAge(int age) {
    if (age < 0 || age > 150) {
        throw new IllegalArgumentException("age must be between 0 and 150, was " + age);
    }
    this.age = age;
}

This is the same idea as the invariants in the encapsulation module. Failing at the point where the bad value arrives, rather than later, makes the cause easy to find.

Messages that help

The message is the first thing a person sees. A useful message says what was wrong and which value caused it, and ideally what was expected.

A good message costs one string concatenation.

Which exception to throw

Use an existing exception when its name describes your problem:

• IllegalArgumentException: the argument is wrong, whatever the object's state. Example: a negative deposit.
• IllegalStateException: the argument is fine, but the state of the object does not allow the call now. Example: withdrawing more than the balance (until lesson 5 gives us a better type).
• Lesson 2's checked exceptions, such as IOException, for problems with the outside world.

One note: the Oracle tutorial says that most applications should not throw runtime exceptions or subclass RuntimeException, and treats them as for incorrect use of an API. Standard Java libraries themselves throw IllegalArgumentException for bad arguments, and the earlier encapsulation module used it the same way. Treat the advice as part of the long-running debate over checked versus unchecked: follow what your team and framework do, and be consistent.

The throws clause

If a method can throw a checked exception and does not catch it, the method must declare it. The throws keyword goes after the parameter list:

static String load(String name) throws IOException {
    if (!name.endsWith(".cfg")) {
        throw new IOException("Unsupported file type (expected .cfg): " + name);
    }
    return "settings from " + name;
}

The declaration is part of the method's contract: it tells every caller "this can fail with an IOException". The Oracle tutorial notes that declaring unchecked exceptions is optional. Either form compiles. Some teams list important unchecked exceptions in throws or in documentation as a hint to readers, but the compiler never forces it.

What callers must do

When you call a method that declares a checked exception, the Catch or Specify Requirement (lesson 2) applies to your code. You have exactly two choices:

1. Catch it with try/catch, and handle it here.
2. Declare it in your own throws clause, passing the decision up to your caller.

If you do neither, the compiler stops you:

NoPlan.java:9: error: unreported exception IOException; must be caught or declared to be thrown
        System.out.println(load("a.cfg"));
                               ^

Which choice is right? Handle it where you can do something sensible about it. A method deep in the code usually cannot decide what the user should see, so it declares the exception. A method near the top (often main) can show a message or retry, so it catches. Declaring everything with throws Exception is a poor habit: it announces "anything may go wrong" and stops the compiler helping you.

Exceptions are not for normal flow

An exception is for something unexpected that stops the normal path. Do not use one to end a loop or to return a normal answer:

// Poor: using an exception as the loop exit
try {
    for (int i = 0; ; i++) {
        System.out.println(values[i]);
    }
} catch (ArrayIndexOutOfBoundsException e) {
    // reached the end
}

// Better
for (int i = 0; i < values.length; i++) {
    System.out.println(values[i]);
}

The first version hides the real end condition and would swallow a bug if an index were wrong for another reason. Rule: if a plain if or loop condition can express it, use that.