Handling errors - Objects First with Java: A Practical Introduction Using BlueJ - page 432

12.5.1 Checked exceptions: the throws clause

The first requirement of the compiler is that a method throwing a checked exception must declare
that it does so in a throws clause added to the method's header. For instance, a method throwing
a checked IOException from the java.io package might have the following header: 4

Concept:

A checked
exception is a type
of exception whose
use will require
extra checks from
the compiler. In
particular, checked
exceptions in Java
require the use of
throws clauses and
try statements.

public void saveToFile(String destinationFile)
throws IOException

It is permitted to use a throws clause for unchecked exceptions, but the compiler does not
require one. We recommend that a throws clause be used only to list the checked exceptions
thrown by a method.

It is important to distinguish between a throws clause in the header of a method and the
@throws javadoc comment that precedes the method; the latter is completely optional for both
types of exception. Nevertheless, we recommend that javadoc documentation be included for
both checked and unchecked exceptions. In that way, as much information as possible will be
available to someone wishing to use a method that throws an exception.

12.5.2 Anticipating exceptions: the try statement

The second requirement, when using checked exceptions, is that a caller of a method that
throws a checked exception must make provision for dealing with the exception. This usually
means writing an exception handler in the form of a try statement . Most practical try statements
have the general form shown in Code 12.8. This introduces two new Java keywords— try and
catch —which mark a try block and a catch block , respectively.

Code 12.8
The try and catch
blocks of an exception
handler

try {
Protect one or more statements here.

}
catch (Exception e) {
Report and recover from the exception here.

}

Suppose we have a method that saves the contents of an address book to a file. The user is
requested in some way for the name of a file (perhaps via a GUI dialog window), and the
address book's saveToFile method is then called to write out the list to the file. If we did not
have to take exceptions into account, then this would be written as follows:
String filename = request-a-file-from-the-user ;
addressbook.saveToFile(filename);

Concept:

Program code that
protects state-
ments in which
an exception
might be thrown is
called an excep-
tion handler . It
provides reporting
and/or recovery
code should one
arise.

However, because the writing process could fail with an exception, the call to saveToFile
must be placed within a try block to show that this has been taken into account. Code 12.9
illustrates how we would tend to write this, anticipating possible failure.

Any number of statements can be included in a try block, so, in fact, we tend to place there not
just the single statement that could fail, but all of the statements that are related to it in some way.

4

Note that the keyword here is throws and not throw.