We begin this chapter by discussing the common task of reading and writing files that contain text. Examples are files that are created with a simple text editor, such as Windows Notepad, as well as Java source code and HTML files.

The simplest mechanism for reading text is to use the Scanner class. You already know how to use a Scanner for reading console input. To read input from a disk file, the Scanner class relies on another class, File, which describes disk files and directories. (The File class has many methods that we do not discuss in this book; for example, methods that delete or rename a file.) First construct a File object with the name of the input file, then use the File to construct a Scanner object:

File inFile = new File("input.txt");
Scanner in = new Scanner(inFile);

This Scanner object reads text from the file input.txt. You can use the Scanner methods (such as next, nextLine, nextInt, and nextDouble) to read data from the input file.

To write output to a file, you construct a PrintWriter object with the given file name, for example

PrintWriter out = new PrintWriter("output.txt");

If the output file already exists, it is emptied before the new data are written into it. If the file doesn't exist, an empty file is created. You can also construct a PrintWriter object from a File object. This is useful if you use a file chooser (see Special Topic 11.1).

The PrintWriter class is an enhancement of the PrintStream class that you already know—System.out is a PrintStream object. You can use the familiar print, println, and printf methods with any PrintWriter object:

out.print(29.95);
out.println(new Rectangle(5, 10, 15, 25));
out.printf("%10.2f", price);

When you are done writing to a file, be sure to close the PrintWriter:

out.close();

If your program exits without closing the PrintWriter, the disk file may not contain all of the output.

The following program puts these concepts to work. It reads all lines of an input file and sends them to the output file, preceded by line numbers. If the input file is

Mary had a little lamb
Whose fleece was white as snow.
And everywhere that Mary went,
The lamb was sure to go!

then the program produces the output file

/* 1 */ Mary had a little lamb
/* 2 */ Whose fleece was white as snow.
/* 3 */ And everywhere that Mary went,
/* 4 */ The lamb was sure to go!

The line numbers are enclosed in /* */ delimiters so that the program can be used for numbering Java source files.

There is one additional issue that we need to tackle. When the input or output file doesn't exist, a FileNotFoundException can occur. The compiler insists that we tell it what the program should do when that happens. (In this regard, the FileNotFoundException is different from the exceptions that you have already encountered. We will discuss this difference in detail in Section 11.4.) In our sample program, we take the easy way out and acknowledge that the main method should simply be terminated if the exception occurs. We label the main method like this:

public static void main(String[] args) throws FileNotFoundException

You will see in the following sections how to deal with exceptions in a more professional way.

ch11/lines/LineNumberer.java

1 import java.io.File;
2 import java.io.FileNotFoundException;
3 import java.io.PrintWriter;
4 import java.util.Scanner;
5
6 /**
7    This program applies line numbers to a file.
8 */
9 public class LineNumberer
10 {
11   public static void main(String[] args) throws FileNotFoundException
12   {
13      // Prompt for the input and output file names
14
15      Scanner console = new Scanner(System.in);
16      System.out.print("Input file: ");
17      String inputFileName = console.next();
18      System.out.print("Output file: ");
19      String outputFileName = console.next();
20

21      // Construct the Scanner and PrintWriter objects for reading and writing
22
23      File inputFile = new File(inputFileName);
24      Scanner in = new Scanner(inputFile);
25      PrintWriter out = new PrintWriter(outputFileName);
26      int lineNumber = 1;
27
28      //  Read the input and write the output
29
30      while (in.hasNextLine())
31      {
32         String line = in.nextLine();
33         out.println("/* " + lineNumber + " */ " + line);
34         lineNumber++;
35      }
36
37         in.close();
38         out.close();
39      }
40   }

2. What happens when you supply the name of a nonexistent input file to the Line-Numberer program?

inFile = new File("c:\homework\input.dat");

PrintWriter out = new PrintWriter("output.txt");

Scanner in = new Scanner("input.txt"); // ERROR?

Scanner in = new Scanner(new File("input.txt")); // OK

File Dialog Boxes

In a program with a graphical user interface, you will want to use a file dialog box (such as the one shown in the figure below) whenever the users of your program need to pick a file. The JFileChooser class implements a file dialog box for the Swing user interface toolkit.

Note

The JFileChooser dialog box allows users to select a file by navigating through directories.

The JFileChooser class has many options to fine-tune the display of the dialog box, but in its most basic form it is quite simple: Construct a file chooser object; then call the showOpenDialog or showSaveDialog method. Both methods show the same dialog box, but the button for selecting a file is labeled "Open" or "Save", depending on which method you call.

Note

A File object describes a file or directory.

For better placement of the dialog box on the screen, you can specify the user interface component over which to pop up the dialog box. If you don't care where the dialog box pops up, you can simply pass null. The showOpenDialog and showSaveDialog methods return either JFileChooser.APPROVE_OPTION, if the user has chosen a file, or JFileChooser.CANCEL_OPTION, if the user canceled the selection. If a file was chosen, then you call the getSelectedFile method to obtain a File object that describes the file. Here is a complete example:

JFileChooser chooser = new JFileChooser();
Scanner in = null;
if (chooser.showOpenDialog(null) == JFileChooser.APPROVE_OPTION)
{
   File selectedFile = chooser.getSelectedFile();
   in = new Scanner(selectedFile);
   ...
}

A JFileChooser Dialog Box

String address = "http://java.sun.com/index.html";
URL locator = new URL(address);
Scanner in = new Scanner(locator.openStream());

java LineNumberer input.txt numbered.txt

if (args.length >= 1)
   inputFileName = args[0];

java LineNumberer -c HelloWorld.java HelloWorld.txt

for (String arg : args)
{
   if (arg.startsWith("-")) // It's an option
   {
      if (arg.equals("-c")) useCommentDelimiters = true;

}
   else if (inputFileName == null) inputFileName = arg;
   else if (outputFileName == null) outputFileName = arg;
}

In the following sections, you will learn how to process complex text input that you often encounter in real life situations.

while (in.hasNext())
{
   String input = in.next();
   System.out.println(input);
}

Mary
had
a
little
lamb

snow.
1729
C++

Scanner in = new Scanner(...);
in.useDelimiter("[^A-Za-z]+");

Processing Lines

When each line of a file is a data record, it is often best to read entire lines with the nextLine method:

String line = in.nextLine();

The nextLine method consumes the next input line (including the newline character) and returns the line without the newline character. You can then take the line apart for further processing.

Note

The nextLine method reads a line of input and consumes the newline character at the end of the line.

Here is a typical example of processing lines in a file. A file with population data from the CIA Fact Book site (http://www.cia.gov/library/publications/the-world-factbook/) contains lines such as the following:

China 1330044605
India 1147995898
United States 303824646
...

Because some country names have more than one word, it would be tedious to read this file using the next method. For example, after reading United, how would your program know that it still needs to read another word before reading the population count?

Instead, read each input line into a string. Then use the isDigit and isWhitespace methods to find out where the name ends and the number starts.

Locate the first digit:

int i = 0;
while (!Character.isDigit(line.charAt(i))) { i++; }

Then extract the country name and population:

String countryName = line.substring(0, i);
String population = line.substring(i);

However, the country name contains one or more spaces at the end. Use the trim method to remove them:

countryName = countryName.trim();

The trim method returns the string with all white space at the beginning and end removed.

There is another problem. The population is stored in a string, not a number. Use the Integer.parseInt method to convert it:

int populationValue = Integer.parseInt(population);

You need to be careful when calling the Integer.parseInt method. Its parameter value must be a string containing the digits of an integer or a NumberFormatException occurs. The parameter value may not contain any additional characters. Not even spaces are allowed! In our situation, we happen to know that there won't be any spaces at the beginning of the string, but there might be some at the end. Therefore, we use the trim method:

int populationValue = Integer.parseInt(population.trim());

Here you saw how to break a string into parts by looking at individual characters. Another approach is occasionally easier. Construct a new Scanner object to read the characters from a string:

Scanner lineScanner = new Scanner(line);

Then you can use lineScanner like any other Scanner object, reading words and numbers:

String countryName = lineScanner.next();
while (!lineScanner.hasNextInt())
{
   countryName = countryName + " " + lineScanner.next();
}
int populationValue = lineScanner.nextInt();

Reading Numbers

You have used the nextInt and nextDouble methods of the Scanner class many times, but here we will have a look at their behavior in detail. Suppose you call

double value = in.nextDouble();

Note

The nextInt and nextDouble methods consume white space and the next number.

The nextDouble method recognizes floating-point numbers such as 3.14159, −21, or 1E12 (a billion in scientific notation). However, if there is no number in the input, then a NoSuchElementException occurs.

Consider an input containing the characters

White space is consumed and the word 21st is read. However, this word is not a properly formatted number. In this situation, an "input mismatch exception" occurs.

To avoid exceptions, use the hasNextDouble method to screen the input. For example,

if (in.hasNextDouble())
{
   double value = in.nextDouble();
   ...
}

Similarly, you should call the hasNextInt method before calling nextInt.

Note that the nextInt and nextDouble methods do not consume the white space that follows a number. This can be a problem if you alternate between calling nextInt/nextDouble and nextLine. Suppose a file contains student IDs and names in this format:

1729
Harry Morgan
1730
Diana Lin
...

Now suppose you read the file with these instructions:

while (in.hasNextInt())
{
   int studentID = in.nextInt();
   String name = in.nextLine();
   Process the student ID and name
}

Initially, the input contains

After the first call to nextInt, the input contains

The call to nextLine reads an empty string! The remedy is to add a call to nextLine after reading the ID:

int studentID = in.nextInt();
in.nextLine(); // Consume the newline
String name = in.nextLine();

Reading Characters

Sometimes, you want to read a file one character at a time. You achieve this task by calling the useDelimiter method on your Scanner object with an empty string:

Scanner in = new Scanner(...);
in.useDelimiter("");

Note

To read one character at a time, set the delimiter pattern to the empty string.

Now each call to next returns a string consisting of a single character. Here is how you can process the characters:

while (in.hasNext())
{

char ch = in.next().charAt(0);
   Process ch
}

int number = in.nextInt();
String input = in.next();

4. Suppose the input contains the characters 6,995.00 12. What is the value of price and quantity after these statements?

double price = in.nextDouble();
int quantity = in.nextInt();

5. Your input file contains a sequence of numbers, but sometimes a value is not available and marked as N/A. How can you read the numbers and skip over the markers?

Regular Expressions

Regular expressions describe character patterns. For example, numbers have a simple form. They contain one or more digits. The regular expression describing numbers is [0-9]+. The set [0-9] denotes any digit between 0 and 9, and the + means "one or more".

The search commands of professional programming editors understand regular expressions. Moreover, several utility programs use regular expressions to locate matching text. A commonly used program that uses regular expressions is grep (which stands for "global regular expression print"). You can run grep from a command line or from inside some compilation environments. Grep is part of the UNIX operating system, and versions are available for Windows. It needs a regular expression and one or more files to search. When grep runs, it displays a set of lines that match the regular expression.

Suppose you want to look for all magic numbers (see Quality Tip 4.1) in a file. The command

grep [0-9]+ Homework.java

lists all lines in the file Homework.java that contain sequences of digits. That isn't terribly useful; lines with variable names x1 will be listed. OK, you want sequences of digits that do notimmediately follow letters:

grep [^A-Za-z][0-9]+ Homework.java

The set [^A-Za-z] denotes any characters that are not in the ranges A to Z and a to z. This works much better, and it shows only lines that contain actual numbers.

The useDelimiter method of the Scanner class accepts a regular expression to describe delimiters—the blocks of text that separate words. As already mentioned, if you set the delimiter pattern to [^A-Za-z]+, a delimiter is a sequence of one or more characters that are not letters.

For more information on regular expressions, consult one of the many tutorials on the Internet by pointing your search engine to "regular expression tutorial".

Processing Text Files

Processing text files that contain real data can be surprisingly challenging. This How To gives you step-by-step guidance.

As an example, we will consider this task: Read two country data files, worldpop.txt and worldarea.txt (supplied with your book code). Both files contain data for the same countries in the same order. Write a file world_pop_density.txt that contains country names and population densities (people per square km), with the country names aligned left and the numbers aligned right:

Afghanistan                                        50.56
Akrotiri                                          127.64
Albania                                           125.91
Algeria                                            14.18
American Samoa                                    288.92
...

• Step 1 Understand the processing task.

  As always, you need to have a clear understanding of the task before designing a solution. Can you carry out the task by hand (perhaps with smaller input files)? If not, get more information about the problem.

  One important aspect that you need to consider is whether you can process the data as it becomes available, or whether you need to store it first. For example, if you are asked to write out sorted data, you need to first collect all input, perhaps by placing it in an array list. However, it is often possible to process the data "on the go", without storing it.

  In our example, we can read each file a line at a time and compute the density for each line because our input files store the population and area data in the same order.

  While there are more lines to be read
    Read a line from each file.
    Extract the country name.
    population = number following the country name in the line from the first file
    area = number following the country name in the line from the second file
    If area != 0
    density = population / area
    Print country name and density.

• Step 2 Determine which files you need to read and write.

  This should be clear from the problem. In our example, there are two input files, the population data and the area data, and one output file.

• Step 3 Choose a mechanism for obtaining the file names.

  There are four options:

  • Hard-coding the file names (such as "worldpop.txt")

  • Asking the user:

    Scanner in = new Scanner(System.in);
    System.out.print("Enter filename: ");
    String inFile = in.nextLine();

  • Using command line arguments for the file names (see Special Topic 11.3 on page 472)

  • Using a file chooser dialog box (see Special Topic 11.1 on page 471)

  In our example, we use hard-coded file names for simplicity.

• Step 4 Choose between line, word, and character-based input.

  As a rule of thumb, read lines if the input data is grouped by lines. That is the case with tabular data, such as in our example, or when you need to report line numbers.

  When gathering data that can be distributed over several lines, then it makes more sense to read words. Keep in mind that you lose all white space when you read words.

  Reading characters is mostly useful for tasks that require access to individual characters. Examples include analyzing character frequencies, changing tabs to spaces, or encryption.

• Step 5 With line-oriented input, extract the required data.

  It is simple to read a line of input with the nextLine method. Then you need to get the data out of that line. You can extract substrings, as described in Section 11.2.2.

  Typically, you will use methods such as Character.isWhitespace and Character.isDigit to find the boundaries of substrings.

  If you need any of the substrings as numbers, you must convert them, using Integer.parseInt or Double.parseDouble.

• Step 6 Use classes and methods to factor out common tasks.

  Processing input files usually has repetitive tasks, such as skipping over white space or extracting numbers from strings. It really pays off to isolate these tedious operations from the remainder of the code.

  In our example, we have a task that occurs twice: splitting an input line into the country name and the value that follows. We implement a simple CountryValue class for this purpose, using the technique described in Section 11.2.2.

  Here is the complete source code.

  ch11/population/CountryValue.java

  1  /**
  2      Describes a value that is associated with a country.
  3  */
  4  public class CountryValue
  5  {
  6     private String country;
  7     private double value;
  8
  9     /**
  10        Constructs a CountryValue from an input line.
  11        @param line a line containing a country name, followed by a value
  12     */
  13     public CountryValue(String line)
  14     {
  15        int i = 0; //  Locate the start of the first digit
  16        while (!Character.isDigit(line.charAt(i))) { i++; }
  17        int j = i - 1; // Locate the end of the preceding word
  18        while (Character.isWhitespace(line.charAt(j))) { j--; }
  19        country = line.substring(0, j + 1); // Extract the country name
  20        value = Double.parseDouble(line.substring(i).trim()); // Extract the value
  21     }
  22
  23     /**
  24        Gets the country name.
  25        @return the country name
  26     */
  27     public String getCountry() { return country; }
  28

  29      /**
  30         Gets the associated value.
  31         @return the value associated with the country
  32      */
  33      public double getValue() { return value; }
  34   }

  ch11/population/PopulationDensity.java

  1 import java.io.File;
  2 import java.io.FileNotFoundException;
  3 import java.io.PrintWriter;
  4 import java.util.Scanner;
  5
  6 public class PopulationDensity
  7 {
  8    public static void main(String[] args) throws FileNotFoundException
  9    {
  10       // Open input files
  11       Scanner in1 = new Scanner(new File("worldpop.txt"));
  12       Scanner in2 = new Scanner(new File("worldarea.txt"));
  13
  14       // Open output file
  15       PrintWriter out = new PrintWriter("world_pop_density.txt");
  16
  17       // Read lines from each file
  18       while (in1.hasNextLine() && in2.hasNextLine())
  19       {
  20          CountryValue population = new CountryValue(in1.nextLine());
  21          CountryValue area = new CountryValue(in2.nextLine());
  22
  23          // Compute and print the population density
  24          double density = 0;
  25          if (area.getValue() != 0) //  Protect against division by zero
  26          {
  27               density = population.getValue() / area.getValue();
  28          }
  29          out.printf("%-40s%15.2f
  ", population.getCountry(), density);
  30       }
  31
  32       in1.close();
  33       in2.close();
  34       out.close();
  35    }
  36 }

Analyzing Baby Names

In this Worked Example, you will use data from the Social Security Administration to analyze the most popular baby names.

There are two main aspects to exception handling: reporting and recovery. A major challenge of error handling is that the point of reporting is usually far apart from the point of recovery. For example, the get method of the ArrayList class may detect that a nonexistent element is being accessed, but it does not have enough information to decide what to do about this failure. Should the user be asked to try a different operation? Should the program be aborted after saving the user's work? These decisions must be made in a different part of the program.

In Java, exception handling provides a flexible mechanism for passing control from the point of error reporting to a competent recovery handler. In the remainder of this chapter, we will look into the details of this mechanism.

When you detect an error condition, your job is really easy. You just throw an appropriate exception object, and you are done. For example, suppose someone tries to withdraw too much money from a bank account.

public class BankAccount
{
   ...
   public void withdraw(double amount)
   {
      if (amount > balance)
         // Now what?
      ...
   }
}

First look for an appropriate exception class. The Java library provides many classes to signal all sorts of exceptional conditions. Figure 1 on the next page shows the most useful ones.

Look around for an exception type that might describe your situation. How about the IllegalStateException? Is the bank account in an illegal state for the withdraw operation? Not really—some withdraw operations could succeed. Is the parameter value illegal? Indeed it is. It is just too large. Therefore, let's throw an IllegalArgumentException. (The term argument is an alternative term for a parameter value.)

public class BankAccount
{
   public void withdraw(double amount)
   {
      if (amount > balance)
      {
         throw new IllegalArgumentException("Amount exceeds balance");
      }
      balance = balance - amount;
   }
   ...
}

The statement

throw new IllegalArgumentException("Amount exceeds balance");

constructs an object of type IllegalArgumentException and throws that object.

When you throw an exception, execution does not continue with the next statement but with an exception handler. For now, we won't worry about the handling of the exception. That is the topic of Section 11.5.

Figure 11.1. The Hierarchy of Exception Classes

Throwing an Exception

7. Suppose you construct a new bank account object with a zero balance and then call withdraw(10). What is the value of balance afterwards?

Java exceptions fall into two categories, called checked and unchecked exceptions. When you call a method that throws a checked exception, the compiler checks that you don't ignore it. You must tell the compiler what you are going to do about the exception if it is ever thrown. For example, all subclasses of IOException are checked exceptions. On the other hand, the compiler does not require you to keep track of unchecked exceptions. Exceptions such as NumberFormatException, IllegalArgument-Exception, and NullPointerException are unchecked exceptions. More generally, all exceptions that belong to subclasses of RuntimeException are unchecked, and all other subclasses of the class Exception are checked. (In Figure 1, the checked exceptions are shaded in a darker color.) There is a second category of internal errors that are reported by throwing objects of type Error. One example is the OutOfMemoryError, which is thrown when all available memory has been used up. These are fatal errors that happen rarely and are beyond your control. They too are unchecked.

Why have two kinds of exceptions? A checked exception describes a problem that is likely to occur at times, no matter how careful you are. The unchecked exceptions, on the other hand, are your fault. For example, an unexpected end of file can be caused by forces beyond your control, such as a disk error or a broken network connection. But you are to blame for a NullPointerException, because your code was wrong when it tried to use a null reference.

The compiler doesn't check whether you handle a NullPointerException, because you should test your references for null before using them rather than install a handler for that exception. The compiler does insist that your program be able to handle error conditions that you cannot prevent.

Actually, those categories aren't perfect. For example, the Scanner.nextInt method throws an unchecked InputMismatchException if the input does not contain a valid integer. A checked exception would have been more appropriate because the programmer cannot prevent users from entering incorrect input. (The designers of the Scanner class made this choice to make it easy to use for beginning programmers.)

As you can see from Figure 1, the majority of checked exceptions occur when you deal with input and output. That is a fertile ground for external failures beyond your control—a file might have been corrupted or removed, a network connection might be overloaded, a server might have crashed, and so on. Therefore, you will need to deal with checked exceptions principally when programming with files and streams.

You have seen how to use the Scanner class to read data from a file, by passing a File object to the Scanner constructor:

String filename = ...;
File inFile = new File(filename);
Scanner in = new Scanner(inFile);

However, the Scanner constructor can throw a FileNotFoundException. The FileNotFoundException is a checked exception, so you need to tell the compiler what you are going to do about it. You have two choices. You can handle the exception, using the techniques that you will see in Section 11.5. Or you can simply tell the compiler that you are aware of this exception and that you want your method to be terminated when it occurs. The method that reads input does not usually know what to do about an unexpected error, so that is usually the better option.

To declare that a method should be terminated when a checked exception occurs within it, tag the method with a throws clause.

public void read(String filename) throws FileNotFoundException
{
     File inFile = new File(filename);
     Scanner in = new Scanner(inFile);
     ...
}

The throws clause in turn signals the caller of your method that it may encounter a FileNotFoundException. Then the caller needs to make the same decision—handle the exception, or tell its caller that the exception may be thrown.

If your method can throw exceptions of different types, you separate the exception class names by commas:

public void read(String filename)
       throws FileNotFoundException, NoSuchElementException

Always keep in mind that exception classes form an inheritance hierarchy. For example, FileNotFoundException is a subclass of IOException. Thus, if a method can throw both an IOException and a FileNotFoundException, you only tag it as throws IOException.

It sounds somehow irresponsible not to handle an exception when you know that it happened. Actually, though, it is usually best not to catch an exception if you don't know how to remedy the situation. After all, what can you do in a low-level read method? Can you tell the user? How? By sending a message to System.out? You don't know whether this method is called in a graphical program or an embedded system (such as a vending machine), where the user may never see System.out. And even if your users can see your error message, how do you know that they can understand English? Your class may be used to build an application for users in another country. If you can't tell the user, can you patch up the data and keep going? How? If you set a variable to zero, null, or an empty string, that may just cause the program to break later, with much greater mystery.

The throws Clause

Of course, some methods in the program know how to communicate with the user or take other remedial action. By allowing the exception to reach those methods, you make it possible for the exception to be processed by a competent handler.

9. Why is a NullPointerException not a checked exception?

Every exception should be handled somewhere in your program. If an exception has no handler, an error message is printed, and your program terminates. That may be fine for a student program. But you would not want a professionally written program to die just because some method detected an unexpected error. Therefore, you should install exception handlers for all exceptions that your program might throw.

You install an exception handler with the try/catch statement. Each try block contains one or more statements that may cause an exception. Each catch clause contains the handler for an exception type. Here is an example:

try
     {
      String filename = ...;
      File inFile = new File(filename);
      Scanner in = new Scanner(inFile);
      String input = in.next();
      int value = Integer.parseInt(input);
      ...

}
     catch (IOException exception)
     {
      exception.printStackTrace();
     }
     catch (NumberFormatException exception)
     {
      System.out.println("Input was not a number");
     }

Three exceptions may be thrown in this try block: The Scanner constructor can throw a FileNotFoundException, Scanner.next can throw a NoSuchElementException, and Integer.parseInt can throw a NumberFormatException.

If any of these exceptions is actually thrown, then the rest of the instructions in the try block are skipped. Here is what happens for the various exception types:

When the catch (IOException exception) block is executed, then some method in the to the exception object that was thrown. The catch clause can analyze that object to find out more details about the failure. For example, you can get a printout of the chain of method calls that lead to the exception, by calling

exception.printStackTrace()

Catching Exceptions

In these sample catch clauses, we merely inform the user of the source of the problem. A better way of dealing with the exception would be to give the user another chance to provide a correct input—see Section 11.8 for a solution.

It is important to remember that you should place catch clauses only in methods in which you can competently handle the particular exception type.

11. Is there a difference between catching checked and unchecked exceptions?

try
{
   File inFile = new File(filename);
   Scanner in = new Scanner(inFile);
   // Compiler complained about FileNotFoundException
   ...
}
catch (Exception e) {} // So there!

Occasionally, you need to take some action whether or not an exception is thrown. The finally construct is used to handle this situation. Here is a typical situation.

It is important to close a PrintWriter to ensure that all output is written to the file. In the following code segment, we open a stream, call one or more methods, and then close the stream:

PrintWriter out = new PrintWriter(filename);
writeData(out);
out.close(); // May never get here

Now suppose that one of the methods before the last line throws an exception. Then the call to close is never executed! Solve this problem by placing the call to close inside a finally clause:

PrintWriter out = new PrintWriter(filename);
try
{
   writeData(out);
}
finally
{
   out.close();
}

The finally Clause

In a normal case, there will be no problem. When the try block is completed, the finally clause is executed, and the writer is closed. However, if an exception occurs, the finally clause is also executed before the exception is passed to its handler.

Use the finally clause whenever you need to do some clean up, such as closing a file, to ensure that the clean up happens no matter how the method exits.

It is also possible to have a finally clause following one or more catch clauses. Then the code in the finally clause is executed whenever the try block is exited in any of three ways:

However, we recommend that you don't mix catch and finally clauses in the same try block—see Quality Tip 11.3.

13. Suppose the file with the given name does not exist. Trace the flow of execution of the code segment in this section.

try
{
   PrintWriter out = new PrintWriter(filename);
   try
   {
      Write output to out
   }
   finally
   {
      out.close();
   }
}
catch (IOException exception)
{
   Handle exception
}

try (PrintWriter out = new PrintWriter(filename))
{
   Write output to out
}

Sometimes none of the standard exception types describe your particular error condition well enough. In that case, you can design your own exception class. Consider a bank account. Let's report an InsufficientFundsException when an attempt is made to withdraw an amount from a bank account that exceeds the current balance.

if (amount > balance)
{
   throw new InsufficientFundsException(
         "withdrawal of " + amount + " exceeds balance of " + balance);
}

Now you need to provide the InsufficientFundsException class. Should it be a checked or an unchecked exception? Is it the fault of some external event, or is it the fault of the programmer? We take the position that the programmer could have prevented the exceptional condition—after all, it would have been an easy matter to check whether amount <= account.getBalance() before calling the withdraw method. Therefore, the exception should be an unchecked exception and extend the Runtime-Exception class or one of its subclasses.

It is a good idea to extend an appropriate class in the exception hierarchy. For example, we can consider an InsufficientFundsException a special case of an Illegal-ArgumentException. This enables other programmers to catch the exception as an IllegalArgumentException if they are not interested in the exact nature of the problem.

It is customary to provide two constructors for an exception class: a constructor with no parameters and a constructor that accepts a message string describing the reason for the exception. Here is the declaration of the exception class.

public class InsufficientFundsException extends IllegalArgumentException
{
   public InsufficientFundsException() {}

   public InsufficientFundsException(String message)
   {
      super(message);
   }
}

When the exception is caught, its message string can be retrieved using the get-Message method of the Throwable class.

15. Suppose you read bank account data from a file. Contrary to your expectation, the next input value is not of type double. You decide to implement a BadData-Exception. Which exception class should you extend?

This section walks through a complete example of a program with exception handling. The program asks a user for the name of a file. The file is expected to contain data values. The first line of the file contains the total number of values, and the remaining lines contain the data. A typical input file looks like this:

3
1.45
-2.1
0.05

What can go wrong? There are two principal risks.

Who can detect these faults? The Scanner constructor will throw an exception when the file does not exist. The methods that process the input values need to throw an exception when they find an error in the data format.

What exceptions can be thrown? The Scanner constructor throws a FileNotFoundException when the file does not exist, which is appropriate in our situation. Finally, when the file data is in the wrong format, we will throw a BadDataException, a custom checked exception class. We use a checked exception because corruption of a data file is beyond the control of the programmer.

Who can remedy the faults that the exceptions report? Only the main method of the DataAnalyzer program interacts with the user. It catches the exceptions, prints appropriate error messages, and gives the user another chance to enter a correct file.

ch11/data/DataAnalyzer.java

1 import java.io.FileNotFoundException;
2 import java.io.IOException;
3 import java.util.Scanner;
4
5 /**
6    This program reads a file containing numbers and analyzes its contents.
7    If the file doesn't exist or contains strings that are not numbers, an
8    error message is displayed.
9 */
10 public class DataAnalyzer
11 {
12    public static void main(String[] args)
13    {
14       Scanner in = new Scanner(System.in);
15       DataSetReader reader = new DataSetReader();
16
17       boolean done = false;
18       while (!done)
19       {
20          try
21          {
22             System.out.println("Please enter the file name: ");
23             String filename = in.next();
24
25             double[] data = reader.readFile(filename);
26             double sum = 0;
27             for (double d : data) sum = sum + d;
28             System.out.println("The sum is " + sum);
29             done = true;
30          }
31          catch (FileNotFoundException exception)
32          {
33             System.out.println("File not found.");
34          }
35          catch (BadDataException exception)
36          {
37             System.out.println("Bad data: " + exception.getMessage());
38          }
39          catch (IOException exception)
40          {
41              exception.printStackTrace();
42          }
43       }
44    }
45 }

The catch clauses in the main method give a human-readable error report if the file was not found or bad data was encountered.

The following readFile method of the DataSetReader class constructs the Scanner object and calls the readData method. It is completely unconcerned with any exceptions. If there is a problem with the input file, it simply passes the exception to its caller.

public double[] readFile(String filename) throws IOException
{
   File inFile = new File(filename);
   Scanner in = new Scanner(inFile);
   try
   {
      readData(in);
      return data;
   }
   finally
   {
      in.close();
   }
}

The method throws an IOException, the common superclass of FileNotFoundException (thrown by the Scanner constructor) and BadDataException (thrown by the readData method).

Next, here is the readData method of the DataSetReader class. It reads the number of values, constructs an array, and calls readValue for each data value.

private void readData(Scanner in) throws BadDataException
{
   if (!in.hasNextInt())
    throw new BadDataException("Length expected");
    int numberOfValues = in.nextInt();
    data = new double[numberOfValues];

   for (int i = 0; i < numberOfValues; i++)
      readValue(in, i);

   if (in.hasNext())
      throw new BadDataException("End of file expected");
}

This method checks for two potential errors. The file might not start with an integer, or it might have additional data after reading all values.

However, this method makes no attempt to catch any exceptions. Plus, if the readValue method throws an exception—which it will if there aren't enough values in the file—the exception is simply passed on to the caller.

Here is the readValue method:

private void readValue(Scanner in, int i) throws BadDataException
{
   if (!in.hasNextDouble())
      throw new BadDataException("Data value expected");
   data[i] = in.nextDouble();
}

To see the exception handling at work, look at a specific error scenario.

This example shows the separation between error detection (in the DataSetReader. readValue method) and error handling (in the DataAnalyzer.main method). In between the two are the readData and readFile methods, which just pass exceptions along.

ch11/data/DataSetReader.java

1 import java.io.File;
2 import java.io.IOException;
3 import java.util.Scanner;
4
5 /**
6    Reads a data set from a file. The file must have the format
7    numberOfValues
8    value1
9    value2
10    ...
11 */
12 public class DataSetReader
13 {
14    private double[] data;
15
16    /**
17       Reads a data set.
18       @param filename  the name of the file holding the data
19       @return the data in the file
20    */
21    public double[] readFile(String filename) throws IOException
22    {
23       File inFile = new File(filename);
24       Scanner in = new Scanner(inFile);
25
26       try
27       {
28          readData(in);
29          return data;
30       }
31       finally
32       {
33          in.close();
34       }
35    }
36
37    /**
38       Reads all data.
39       @param in the scanner that scans the data
40    */
41    private void readData(Scanner in) throws BadDataException
42    {
43       if (!in.hasNextInt())
44          throw new BadDataException("Length expected");
45       int numberOfValues = in.nextInt();

46         data = new double[numberOfValues];
47
48         for (int i = 0; i < numberOfValues; i++)
49              readValue(in, i);
50
51         if (in.hasNext())
52            throw new BadDataException("End of file expected");
53       }
54
55      /**
56         Reads one data value.
57         @param in  the scanner that scans the data
58         @param i  the position of the value to read
59      */
60      private void readValue(Scanner in, int i) throws BadDataException
61      {
62         if (!in.hasNextDouble())
63            throw new BadDataException("Data value expected");
64         data[i] = in.nextDouble();
65      }
66  }

ch11/data/BadDataException.java

1 import java.io.IOException;
2
3 /**
4    This class reports bad input data.
5 */
6 public class BadDataException extends IOException
7 {
8    public BadDataException() {}
9    public BadDataException(String message)
10    {
11       super(message);
12    }
13 }

17. Suppose the user specifies a file that exists and is empty. Trace the flow of execution.

The Ariane Rocket Incident

The European Space Agency (ESA), Europe's counterpart to NASA, had developed a rocket model called Ariane that it had successfully used several times to launch satellites and scientific experiments into space. However, when a new version, the Ariane 5, was launched on June 4, 1996, from ESA's launch site in Kourou, French Guiana, the rocket veered off course about 40 seconds after liftoff. Flying at an angle of more than 20 degrees, rather than straight up, exerted such an aerodynamic force that the boosters separated, which triggered the automatic self-destruction mechanism. The rocket blew itself up.

The ultimate cause of this accident was an unhandled exception! The rocket contained two identical devices (called inertial reference systems) that processed flight data from measuring devices and turned the data into information about the rocket position. The onboard computer used the position information for controlling the boosters. The same inertial reference systems and computer software had worked fine on the Ariane 4.

The Explosion of the Ariane Rocket

However, due to design changes to the rocket, one of the sensors measured a larger acceleration force than had been encountered in the Ariane 4. That value, expressed as a floating-point value, was stored in a 16-bit integer (like a short variable in Java). Unlike Java, the Ada language, used for the device software, generates an exception if a floating-point number is too large to be converted to an integer. Unfortunately, the programmers of the device had decided that this situation would never happen and didn't provide an exception handler.

When the overflow did happen, the exception was triggered and, because there was no handler, the device shut itself off. The onboard computer sensed the failure and switched over to the backup device. However, that device had shut itself off for exactly the same reason, something that the designers of the rocket had not expected. They figured that the devices might fail for mechanical reasons, and the chances of two devices having the same mechanical failure was considered remote. At that point, the rocket was without reliable position information and went off course.

Perhaps it would have been better if the software hadn't been so thorough? If it had ignored the overflow, the device wouldn't have been shut off. It would have computed bad data. But then the device would have reported wrong position data, which could have been just as fatal. Instead, a correct implementation should have caught overflow exceptions and come up with some strategy to recompute the flight data. Clearly, giving up was not a reasonable option in this context.

The advantage of the exception-handling mechanism is that it makes these issues explicit to programmers—something to think about when you curse the Java compiler for complaining about uncaught exceptions.

java.io.EOFException                       java.lang.RuntimeException
java.io.File                               java.lang.Throwable
java.io.FileNotFoundException                 getMessage
java.io.IOException                           printStackTrace
java.io.PrintWriter                        java.util.NoSuchElementException
   close                                   java.util.Scanner
java.lang.Error                               close
java.lang.IllegalArgumentException         javax.swing.JFileChooser
java.lang.IllegalStateException               getSelectedFile
java.lang.NullPointerException                showOpenDialog
java.lang.NumberFormatException               showSaveDialog

java Woozle -Dname=piglet -Ieeyore -v heff.txt a.txt lump.txt

PrintWriter out = new PrintWriter(filename);
try
{
   Write output
}
catch (IOException exception)
{
   Handle exception
}
finally
{
   out.close();
}

0
1
2
3

java CopyFile report.txt report.sav

java CatFiles chapter1.txt chapter2.txt chapter3.txt book.txt

java Find ring report.txt address.txt Homework.java

report.txt: has broken up an international ring of DVD bootleggers that
address.txt: Kris Kringle, North Pole
address.txt: Homer Simpson, Springfield
Homework.java: String filename;

java Reverse HelloPrinter.java

retnirPolleH ssalc cilbup
{
)sgra ][gnirtS(niam diov citats cilbup
{
wodniw elosnoc eht ni gniteerg a yalpsiD //

;)"!dlroW, olleH"(nltnirp.tuo.metsyS
}
}

java TabExpander filename

java TabExpander -t tabwidth filename

coinName1 coinValue1
coinName2 coinValue2
...

void read(Scanner in) throws FileNotFoundException

static ArrayList<Coin> readFile(String filename)
   throws FileNotFoundException

accountNumber1 balance1
accountNumber2 balance2
...

String address = "http://java.sun.com/index.html";
URL u = new URL(address);
Scanner in = new Scanner(u.openStream());
...

<a href="link">link text</a>