The first kind of exception is the checked exception. These are exceptional conditions that a well-written application should anticipate and recover from. For example, suppose an application prompts a user for an input file name, then opens the file by passing the name to the constructor for java.io.FileReader. Normally, the user provides the name of an existing, readable file, so the construction of the FileReader object succeeds, and the execution of the application proceeds normally. But sometimes the user supplies the name of a nonexistent file, and the constructor throws java.io.FileNotFoundException. A well-written program will catch this exception and notify the user of the mistake, possibly prompting for a corrected file name.

Checked exceptions are subject to the Catch or Specify Requirement. All exceptions are checked exceptions, except for those indicated by Error, RuntimeException, and their subclasses.

The second kind of exception is the error. These are exceptional conditions that are external to the application and that the application usually cannot anticipate or recover from. For example, suppose that an application successfully opens a file for input, but is unable to read the file because of a hardware or system malfunction. The unsuccessful read will throw java.io.IOError. An application might choose to catch this exception, in order to notify the user of the problem—but it also might make sense for the program to print a stack trace and exit.

Errors are not subject to the Catch or Specify Requirement. Errors are those exceptions indicated by Error and its subclasses.

The third kind of exception is the runtime exception. These are exceptional conditions that are internal to the application and that the application usually cannot anticipate or recover from. These usually indicate programming bugs, such as logic errors or improper use of an API. For example, consider the application described previously that passes a file name to the constructor for FileReader. If a logic error causes a null to be passed to the constructor, the constructor will throw NullPointerException. The application can catch this exception, but it probably makes more sense to eliminate the bug that caused the exception to occur.

Runtime exceptions are not subject to the Catch or Specify Requirement. Runtime exceptions are those indicated by RuntimeException and its subclasses.

Errors and runtime exceptions are collectively known as unchecked exceptions.

Some programmers consider the Catch or Specify Requirement a serious flaw in the exception mechanism and bypass it by using unchecked exceptions in place of checked exceptions. In general, this is not recommended. The Unchecked Exceptions—The Controversy section (page 252) talks about when it is appropriate to use unchecked exceptions.

The first step in constructing an exception handler is to enclose the code that might throw an exception within a try block. In general, a try block looks like the following:

try {
  code
}
catch and finally blocks . . .

The segment in the example labeled code contains one or more legal lines of code that could throw an exception. (The catch and finally blocks are explained in the next two sections.)

To construct an exception handler for the writeList method from the ListOfNumbers class, enclose the exception-throwing statements of the writeList method within a try block. There is more than one way to do this. You can put each line of code that might throw an exception within its own try block and provide separate exception handlers for each. Or, you can put all the writeList code within a single try block and associate multiple handlers with it. The following listing uses one try block for the entire method because the code in question is very short:

private Vector vector;
private static final int SIZE = 10;

PrintWriter out = null;

try {
  System.out.println("Entered try statement");
  out = new PrintWriter(new FileWriter("OutFile.txt"));
  for (int i = 0; i < SIZE; i++) {
    out.println("Value at: " + i + " = " +
                                  vector.elementAt(i));
  }
}
catch and finally statements . . .

If an exception occurs within the try block, that exception is handled by an exception handler associated with it. To associate an exception handler with a try block, you must put a catch block after it; the next section shows you how.

You associate exception handlers with a try block by providing one or more catch blocks directly after the try block. No code can be between the end of the try block and the beginning of the first catch block:

try {

} catch (ExceptionType name) {

} catch (ExceptionType name) {

}

Each catch block is an exception handler and handles the type of exception indicated by its argument. The argument type, ExceptionType, declares the type of exception that the handler can handle and must be the name of a class that inherits from the Throwable class. The handler can refer to the exception with name.

The catch block contains code that is executed if and when the exception handler is invoked. The runtime system invokes the exception handler when the handler is the first one in the call stack whose ExceptionType matches the type of the exception thrown. The system considers it a match if the thrown object can legally be assigned to the exception handler’s argument.

The following are two exception handlers for the writeList method—one for two types of checked exceptions that can be thrown within the try statement:

try {

} catch (FileNotFoundException e) {
    System.err.println("FileNotFoundException: " +
                                       e.getMessage());
    throw new SampleException(e);

} catch (IOException e) {
    System.err.println("Caught IOException: " +
                                       e.getMessage());
}

Both handlers print an error message. The second handler does nothing else. By catching any IOException that’s not caught by the first handler, it allows the program to continue executing.

The first handler, in addition to printing a message, throws a user-defined exception. (Throwing exceptions is covered in detail later in this chapter in the How to Throw Exceptions section, page 246.) In this example, when the FileNotFoundException is caught it causes a user-defined exception called SampleException to be thrown. You might want to do this if you want your program to handle an exception in this situation in a specific way.

Exception handlers can do more than just print error messages or halt the program. They can do error recovery, prompt the user to make a decision, or propagate the error up to a higher-level handler using chained exceptions, as described in the Chained Exceptions section (page 249).

The finally block always executes when the try block exits. This ensures that the finally block is executed even if an unexpected exception occurs. But finally is useful for more than just exception handling—it allows the programmer to avoid having cleanup code accidentally bypassed by a return, continue, or break. Putting cleanup code in a finally block is always a good practice, even when no exceptions are anticipated.

The try block of the writeList method that you’ve been working with here opens a PrintWriter. The program should close that stream before exiting the writeList method. This poses a somewhat complicated problem because writeList’s try block can exit in one of three ways.

The runtime system always executes the statements within the finally block regardless of what happens within the try block. So it’s the perfect place to perform cleanup.

The following finally block for the writeList method cleans up and then closes the PrintWriter:

finally {
  if (out != null) {
      System.out.println("Closing PrintWriter");
      out.close();
  } else {
      System.out.println("PrintWriter not open");
  }
}

In the writeList example, you could provide for cleanup without the intervention of a finally block. For example, you could put the code to close the PrintWriter at the end of the try block and again within the exception handler for ArrayIndexOutOfBoundsException, as follows:

try {

    out.close();      // Don't do this; it duplicates code.

} catch (FileNotFoundException e) {
    out.close();      // Don't do this; it duplicates code.

    System.err.println("Caught: FileNotFoundException: " +
                                              e.getMessage());
    throw new RuntimeException(e);

} catch (IOException e) {
    System.err.println("Caught IOException: " +
                                   e.getMessage());
}

However, this duplicates code, thus making the code difficult to read and error-prone should you modify it later. For example, if you add code that can throw a new type of exception to the try block, you have to remember to close the PrintWriter within the new exception handler.

The previous sections described how to construct the try, catch, and finally code blocks for the writeList method in the ListOfNumbers class.

Now, let’s walk through the code and investigate what can happen.

When all the components are put together, the writeList method looks like the following:

public void writeList() {
  PrintWriter out = null;

  try {
    System.out.println("Entering try statement");
    out = new PrintWriter(
                new FileWriter("OutFile.txt"));
      for (int i = 0; i < SIZE; i++)
        out.println("Value at: " + i + " = " +
                                vector.elementAt(i));

  } catch (ArrayIndexOutOfBoundsException e) {
      System.err.println("Caught " +
                         "ArrayIndexOutOfBoundsException: " +
                                               e.getMessage());
  } catch (IOException e) {
      System.err.println("Caught IOException: " +
                                     e.getMessage());
  } finally {
      if (out != null) {
        System.out.println("Closing PrintWriter");
        out.close();
      }
      else {
        System.out.println("PrintWriter not open");
      }
  }
}

As mentioned previously, this method’s try block has three different exit possibilities; here are two of them:

Let’s look at what happens in the writeList method during these two exit possibilities.

Entering try statement
Caught IOException: OutFile.txt
PrintWriter not open

public void writeList() {
  PrintWriter out = null;

  try {
    System.out.println("Entering try statement");
    out = new PrintWriter(
               new FileWriter("OutFile.txt"));
    for (int i = 0; i < SIZE; i++)
      out.println("Value at: " + i + " = " +
                                          vector.elementAt(i));

  } catch (ArrayIndexOutOfBoundsException e) {
      System.err.println("Caught " +
                         "ArrayIndexOutOfBoundsException: " +
                                               e.getMessage());
  } catch (IOException e) {
      System.err.println("Caught IOException: " +
                                   e.getMessage());
  } finally {
      if (out != null) {
         System.out.println("Closing PrintWriter");
         out.close();
      }
      else {
        System.out.println("PrintWriter not open");
      }
  }
}

Entering try statement
Closing PrintWriter

public void writeList() {
  PrintWriter out = null;
  try {
    System.out.println("Entering try statement");
    out = new PrintWriter(
              new FileWriter("OutFile.txt"));
    for (int i = 0; i < SIZE; i++)
      out.println("Value at: " + i + " = " +
                              vector.elementAt(i));

  } catch (ArrayIndexOutOfBoundsException e) {
      System.err.println("Caught " +
                         "ArrayIndexOutOfBoundsException: " +
                                               e.getMessage());

  } catch (IOException e) {
      System.err.println("Caught IOException: " +
                                     e.getMessage());
  } finally {
      if (out != null) {
        System.out.println("Closing PrintWriter");
        out.close();
      }
      else {
        System.out.println("PrintWriter not open");
      }
  }
}

All methods use the throw statement to throw an exception. The throw statement requires a single argument: a throwable object. Throwable objects are instances of any subclass of the Throwable class. Here’s an example of a throw statement:

throw someThrowableObject;

Let’s look at the throw statement in context. The following pop method is taken from a class that implements a common stack object. The method removes the top element from the stack and returns the object:

public Object pop() {
  Object obj;

  if (size == 0) {
    throw new EmptyStackException();
  }

  obj = objectAt(size - 1);
  setObjectAt(size - 1, null);
  size--;
  return obj;
}

The pop method checks to see whether any elements are on the stack. If the stack is empty (its size is equal to 0), pop instantiates a new EmptyStackException object (a member of java.util) and throws it. The Creating Exception Classes section (page 250) explains how to create your own exception classes. For now, all you need to remember is that you can throw only objects that inherit from the java.lang.Throwable class.

Note that the declaration of the pop method does not contain a throws clause. EmptyStackException is a not a checked exception, so pop is not required to state that it might occur.

The objects that inherit from the Throwable class include direct descendants (objects that inherit directly from the Throwable class) and indirect descendants (objects that inherit from children or grandchildren of the Throwable class). Figure 9.3 illustrates the class hierarchy of the Throwable class and its most significant subclasses. As you can see, Throwable has two direct descendants: Error^[3] and Exception.^[4]

Figure 9.3. The Throwable class.

When a dynamic linking failure or other hard failure in the Java virtual machine occurs, the virtual machine throws an Error. Simple programs typically do not catch or throw Errors.

Most programs throw and catch objects that derive from the Exception class. An Exception indicates that a problem occurred, but it is not a serious system problem. Most programs you write will throw and catch Exceptions as opposed to Errors.

The Java platform defines the many descendants of the Exception class. These descendants indicate various types of exceptions that can occur. For example, IllegalAccessException signals that a particular method could not be found, and NegativeArraySizeException indicates that a program attempted to create an array with a negative size.

One Exception subclass, RuntimeException, is reserved for exceptions that indicate incorrect use of an API. An example of a runtime exception is NullPointerException, which occurs when a method tries to access a member of an object through a null reference. The Unchecked Exceptions—The Controversy section (page 252) discusses why most applications shouldn’t throw runtime exceptions or subclass RuntimeException.

An application often responds to an exception by throwing another exception. In effect, the first exception causes the second exception. It can be very helpful to know when one exception causes another. Chained exceptions help the programmer do this.

The following are the methods and constructors in Throwable that support chained exceptions:

Throwable getCause()
Throwable initCause(Throwable)
Throwable(String, Throwable)
Throwable(Throwable)

The Throwable argument to initCause and the Throwable constructors is the exception that caused the current exception. getCause returns the exception that caused the current exception, and initCause returns the current exception.

The following example shows how to use a chained exception:

try {

} catch (IOException e) {
    throw new SampleException("Other IOException", e);
}

In this example, when an IOException is caught, a new SampleException exception is created with the original cause attached and the chain of exceptions is thrown up to the next higher-level exception handler.

catch (Exception cause) {
  StackTraceElement elements[] = cause.getStackTrace();
  for (int i = 0, n = elements.length; i < n; i++) {
    System.err.println(elements[i].getFileName() + ":" +
                       elements[i].getLineNumber() +
                       ">> " +
                       elements[i].getMethodName() + "()");
  }
}

try {
    Handler handler = new FileHandler("OutFile.log");
    Logger.getLogger("").addHandler(handler);

} catch (IOException e) {
    Logger logger = Logger.getLogger("package.name");
    StackTraceElement elements[] = e.getStackTrace();
    for (int i = 0; n = elements.length; i < n; i++) {
      logger.log(Level.WARNING, elements[i].getMethodName());
    }
}

When faced with choosing the type of exception to throw, you can either use one written by someone else—the Java platform provides a lot of exception classes you can use—or you can write one of your own. You should write your own exception classes if you answer yes to any of the following questions; otherwise, you can probably use someone else’s:

An Example

Suppose you are writing a linked list class. The class supports the following methods, among others:

• objectAt(int n). Returns the object in the nth position in the list. Throws an exception if the argument is less than 0 or more than the number of objects currently in the list.

• firstObject(). Returns the first object in the list. Throws an exception if the list contains no objects.

• indexOf(Object o). Searches the list for the specified Object and returns its position in the list. Throws an exception if the object passed into the method is not in the list.

The linked list class can throw multiple exceptions, and it would be convenient to be able to catch all exceptions thrown by the linked list with one exception handler. Also, if you plan to distribute your linked list in a package, all related code should be packaged together. Thus, the linked list should provide its own set of exception classes.

Figure 9.4 illustrates one possible class hierarchy for the exceptions thrown by the linked list.

Figure 9.4. Example exception class hierarchy.

Exceptions provide the means to separate the details of what to do when something out of the ordinary happens from the main logic of a program. In traditional programming, error detection, reporting, and handling often lead to confusing spaghetti code. For example, consider the pseudocode method here that reads an entire file into memory:

readFile {
  open the file;
  determine its size;
  allocate that much memory;
  read the file into memory;
  close the file;
}

At first glance, this function seems simple enough, but it ignores all the following potential errors:

To handle such cases, the readFile function must have more code to do error detection, reporting, and handling. Here is an example of what the function might look like:

errorCodeType readFile {
  initialize errorCode = 0;

  open the file;
  if (theFileIsOpen) {
      determine the length of the file;
      if (gotTheFileLength) {
          allocate that much memory;
          if (gotEnoughMemory) {
              read the file into memory;
              if (readFailed) {
                  errorCode = -1;
              }
          } else {
              errorCode = -2;
          }
      } else {
          errorCode = -3;
      }
      close the file;
      if (theFileDidntClose && errorCode == 0) {
          errorCode = -4;
      } else {
          errorCode = errorCode and -4;
      }
  } else {
      errorCode = -5;
  }
  return errorCode;
}

There’s so much error detection, reporting, and returning here that the original seven lines of code are lost in the clutter. Worse yet, the logical flow of the code has also been lost, thus making it difficult to tell whether the code is doing the right thing: Is the file really being closed if the function fails to allocate enough memory? It’s even more difficult to ensure that the code continues to do the right thing when you modify the method three months after writing it. Many programmers solve this problem by simply ignoring it—errors are reported when their programs crash.

Exceptions enable you to write the main flow of your code and to deal with the exceptional cases elsewhere. If the readFile function used exceptions instead of traditional error-management techniques, it would look more like the following:

readFile {
  try {
      open the file;
      determine its size;
      allocate that much memory;
      read the file into memory;
      close the file;
  } catch (fileOpenFailed) {
      doSomething;
  } catch (sizeDeterminationFailed) {
      doSomething;
  } catch (memoryAllocationFailed) {
      doSomething;
  } catch (readFailed) {
      doSomething;
  } catch (fileCloseFailed) {
      doSomething;
  }
}

Note that exceptions don’t spare you the effort of doing the work of detecting, reporting, and handling errors, but they do help you organize the work more effectively.

A second advantage of exceptions is the ability to propagate error reporting up the call stack of methods. Suppose that the readFile method is the fourth method in a series of nested method calls made by the main program: method1 calls method2, which calls method3, which finally calls readFile:

method1 {
  call method2;
}

method2 {
  call method3;
}

method3 {
  call readFile;
}

Suppose also that method1 is the only method interested in the errors that might occur within readFile. Traditional error-notification techniques force method2 and method3 to propagate the error codes returned by readFile up the call stack until the error codes finally reach method1—the only method that is interested in them:

method1 {
  errorCodeType error;
  error = call method2;
  if (error)
    doErrorProcessing;
  else
    proceed;
}

errorCodeType method2 {
  errorCodeType error;
  error = call method3;
  if (error)
    return error;
  else
    proceed;
}

errorCodeType method3 {
  errorCodeType error;
  error = call readFile;
  if (error)
    return error;
  else
    proceed;
}

Recall that the Java runtime environment searches backward through the call stack to find any methods that are interested in handling a particular exception. A method can duck any exceptions thrown within it, thereby allowing a method farther up the call stack to catch it. Hence, only the methods that care about errors have to worry about detecting errors:

method1 {
  try {
      call method2;
  } catch (exception e) {
      doErrorProcessing;
  }
}

method2 throws exception {
  call method3;
}

method3 throws exception {
  call readFile;
}

However, as the pseudocode shows, ducking an exception requires some effort on the part of the middleman methods. Any checked exceptions that can be thrown within a method must be specified in its throws clause.

Because all exceptions thrown within a program are objects, the grouping or categorizing of exceptions is a natural outcome of the class hierarchy. An example of a group of related exception classes in the Java platform are those defined in java.io—IOException and its descendants. IOException is the most general and represents any type of error that can occur when performing I/O. Its descendants represent more specific errors. For example, FileNotFoundException means that a file could not be located on disk.

A method can write specific handlers that can handle a very specific exception. The FileNotFoundException class has no descendants, so the following handler can handle only one type of exception:

catch (FileNotFoundException e) {
  ...
}

A method can catch an exception based on its group or general type by specifying any of the exception’s superclasses in the catch statement. For example, to catch all I/O exceptions, regardless of their specific type, an exception handler specifies an IOException argument:

catch (IOException e) {
  ...
}

This handler will be able to catch all I/O exceptions, including FileNotFoundException, EOFException, and so on. You can find details about what occurred by querying the argument passed to the exception handler. For example, use the following to print the stack trace:

catch (IOException e) {
  e.printStackTrace();           // Output goes to System.err.
  e.printStackTrace(System.out); // Send trace to stdout.
}

You could even set up an exception handler that handles any Exception with the handler here:

catch (Exception e) {    // A (too) general exception handler
  ...
}

The Exception class is close to the top of the Throwable class hierarchy. Therefore, this handler will catch many other exceptions in addition to those that the handler is intended to catch. You may want to handle exceptions this way if all you want your program to do, for example, is print out an error message for the user and then exit.

In most situations, however, you want exception handlers to be as specific as possible. The reason is that the first thing a handler must do is determine what type of exception occurred before it can decide on the best recovery strategy. In effect, by not catching specific errors, the handler must accommodate any possibility. Exception handlers that are too general can make code more error-prone by catching and handling exceptions that weren’t anticipated by the programmer and for which the handler was not intended.

As noted, you can create groups of exceptions and handle exceptions in a general fashion, or you can use the specific exception type to differentiate exceptions and handle exceptions in an exact fashion.

You can find answers to these Questions and Exercises at:

tutorial/essential/exceptions/QandE/answers.html