11.2.1. Introduction¶

Mistakes happen. Making mistakes is the norm rather than the exception. This is not to say that we make mistakes more often than we get it right. It is to say that (almost) nothing we do or build is ever perfectly correct, least of all computer software. No matter how well-designed a program is,

there is always the chance that some kind of error will arise during its execution.

An exception is an erroneous or anomalous condition that arises while a program is running. Examples of such conditions that we have discussed in this text include attempting to divide by 0 (arithmetic exception), reading a decimal value when an integer is expected (number format exception), attempting to write to a file that doesn’t exist (I/O exception), or referring to a nonexistent character in a string (index out of bounds exception). The list of potential errors and anomalies is endless.

A well-designed program should include code to guard against errors and other exceptional conditions when they arise. This code should be incorporated into the program from the very first stages of its development. That way it can help identify problems during development. In Java, the preferred way of handling such conditions is to use exception handling, a divide-and-conquer approach that separates a program’s normal code from its error-handling code.

This section describes Java’s exception handling features. We begin by contrasting the traditional way of handling errors within a program with Java’s default exception-handling mechanism. We show how exceptions are raised (thrown) and handled (caught) within a program and identify the rules that apply to different kinds of exceptions. We then focus on some of the key design issues that govern when, where, and how to use exceptions in your programs.

11.2.2. Handling Exceptional Conditions¶

/**
* Precondition:  N > 0
* Postcondition: avgFirstN() = (1+2+...+N)/N
*/
public double avgFirstN(int N) {
    int sum = 0;
    for (int k = 1; k <= N; k++)
        sum += k;
    return sum/N;         // What if N is 0?
}

/**
  * Precondition:  N > 0
  * Postcondition: avgFirstN() equals (1+2+...+N) divided by N
  */
public double avgFirstN(int N) {
    int sum = 0;
    if (N <= 0) {
      System.out.println(
           "ERROR avgFirstN: N <= 0. Program terminating.");
      System.exit(0);
    }
    for (int k = 1; k <= N; k++)
        sum += k;
    return sum/N;         // What if N is 0?
  }

ERROR avgFirstN: N <= 0. Program terminating.

Exception in thread "main"
   java.lang.ArithmeticException:  / by zero
        at CalcAverage.avgFirstN(Compiled Code)
        at CalcAvgTest.main(CalcAvgTest.java:5)

11.2.3. Java’s Exception Hierarchy¶

11.2.3.1. Java Predefined Exceptions¶

The Java class library contains a number of predefined exceptions, some of which are shown below. The most general type of exception, java.lang.Exception, is located in the java.lang package, but most of its subclasses are contained in other packages. Some of the various IOException classes are contained in the java.io package, while others are contained in the java.net package. In general, exception classes are placed in the package that contains the methods that throw those exceptions.

Note

This section goes into a lot of detail about the exception hierarchy. The main thing to take away from this section is that there are many predefined exception classes, and that IOException and its subclasses are checked exceptions, so they must be declared in a throws clause or caught and handled within the method.

Unchecked exceptions do not have to be declared in a throws clause, and they do not have to be caught and handled within the method.

Each of the classes in the figure identifies a particular type of exception, and each is a subclass of the Exception class. Obviously a subclass defines a more specific exception than its superclass. Thus, both ArrayIndexOutOfBoundsException and StringIndexOutOfBoundsException are more specific than IndexOutOfBoundsException.

Class	Description
ArithmeticException	Division by zero or some other kind of arithmetic problem
ArrayIndexOutOfBoundsException	An array index is less than zero or greater than or equal to the array’s length
FileNotFoundException	Reference to a file that cannot be found
IllegalArgumentException	Calling a method with an improper argument
IndexOutOfBoundsException	An array or string index is out of bounds
NullPointerException	Reference to an object that has not been instantiated
NumberFormatException	Use of an illegal number format, such as when calling a method
StringIndexOutOfBoundsException	A String index is less than zero or greater than or equal to the String’s length

The table above gives a brief summary of some of the most important exceptions. You’ve probably encountered some of these exceptions already in the course!

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;

public class Example {
    BufferedReader input = new BufferedReader
            (new InputStreamReader(System.in));
    public void doRead() throws IOException {
        // May throw IOException
        String inputString = input.readLine();
    }
    public static void main(String argv[])
                        throws IOException {
        Example ex = new Example();
        ex.doRead();
    }
  }

11.2.3.5. The Exception Class¶

The java.lang.Exception class itself is quite simple, consisting of just two constructor methods (see the figure below). The Throwable class, from which Exception is derived, is the root class of Java’s exception and error hierarchy. It contains definitions for the getMessage() and printStackTrace() methods, which are two methods that we will use frequently in our error-handling routines.

11.2.4. Trying, Throwing, and Catching an Exception¶

This section will describe how to handle exceptions within the program rather than leaving them to be handled by the JVM. In Java, errors and other abnormal conditions are handled by throwing and catching exceptions. When an error or an exceptional condition is detected, you can throw an exception as a way of signaling the abnormal condition. This is like pulling the fire alarm. When an exception is thrown, an exception handler will catch the exception and deal with it (see the figure below).

If we go back to our avgFirstN() example, the typical way of handling this error in Java would be to throw an exception in the avgFirstN() method and catch it in the calling method. Of course, the calling method could be in the same object or it could belong to some other object. In the latter case, the detection of the error is separated from its handling. This division of labor opens up a wide range of possibilities. For example, a program could dedicate a single object to serve as the handler for all its exceptions. The object would be sort of like the program’s fire department.

To illustrate Java’s try/throw/catch mechanism, let’s revisit the CalcAvgTest program. The version shown below mimics the way Java’s default exception handler works. If the avgFirstN() method is called with an argument that is zero or negative, an IllegalArgumentException is thrown. The exception is caught by the catch clause in the CalcAvgTest.main() method.

try {
  CalcAverage ca = new CalcAverage();
  System.out.println( "AVG + " + ca.avgFirstN(0));
}
catch (IllegalArgumentException e) { // Exception Handler
  System.out.println(e.getMessage());
  e.printStackTrace();
  System.exit(0);
}

class CalcAverage {
    /**
    * Precondition:  N > 0
    * Postcondition: avgFirstN() equals the average of (1+2+...+N)
    */
    public double avgFirstN(int N) {
        int sum = 0;
        if (N <= 0) {
            throw new IllegalArgumentException("ERROR: Can't average 0 elements");
        }
        for (int k = 1; k <= N; k++) {
            sum += k;
        }
        return sum/N;         // What if N is 0?
    }
}

public class CalcAvgTest {
    public static void main(String args[]) {
        try {
            CalcAverage ca = new CalcAverage();
            System.out.println("AVG + " + ca.avgFirstN(0));
        }
        catch (IllegalArgumentException e) { // Exception Handler
            System.out.println(e.getMessage());
            e.printStackTrace();
            System.exit(0);
        }
    }
}

In this version of the calcAvgTest program, an IllegalArgumentException thrown in CalcAverage.avgFirstN(), would be handled by the catch clause in CalcAvgTest.main().

Let’s go through this example step by step. The first thing to notice is that if the CalcAverage.avgFirstN() method has a zero or negative argument, it will throw an exception:

if (N <= 0)
   throw new IllegalArgumentException("ERROR: Illegal argument");

Note the syntax of the throw statement. It creates a new IllegalArgumentException object and passes it a message that describes the error. This message becomes part of the exception object. It can be retrieved using the getMessage() method, which is inherited from the Throwable class (Figure 2).

When a throw statement is executed, the JVM interrupts the normal execution of the program and searches for an exception handler. We will describe the details of this search shortly. In this case, the exception handler is the catch clause contained in the CalcAvgTest.main() method:

catch (IllegalArgumentException e) {  // Exception Handler
   System.out.println(e.getMessage());
   e.printStackTrace();
   System.exit(0);
}

When an IllegalArgumentException is thrown, the statements within this catch clause are executed. The first statement uses the getMessage() method to print a copy of the error message. The second statement uses the printStackTrace() method, which is defined in Throwable and inherited by all ``Exception``s, to print a trace of the method calls leading up to the exception. The last statement causes the program to terminate.

When we run this program, the following output will be generated as a result of the illegal argument error:

ERROR: Can't average 0 elements
java.lang.IllegalArgumentException: ERROR: Can't average 0 elements
        at CalcAverage.avgFirstN(CalcAverage.java:9)
        at CalcAvgTest.main(CalcAvgTest.java:6)

Thus, as in the previous example of Java’s default exception handler, our exception handler also prints out a description of the error and a trace of the method calls that led up to the error. However, in this example, we are directly handling the exception rather than leaving it up to Java’s default exception handler. Of course, this example is intended mainly for illustrative purposes. It would make little sense to write our own exception handler if it does nothing more than mimic Java’s default handler.

Finally, note that the catch clause is associated with a try block. The handling of exceptions in Java takes place in two parts: First, we try to execute some statements, which may or may not lead to an exception. These are the statements contained within the try clause:

try {
    CalcAverage ca = new CalcAverage();
    System.out.println( "AVG + " + ca.avgFirstN(0));
  }

Second, we provide one or more catch clauses to handle particular types of exceptions. In this case, we are only handling ``IllegalArgumentException``s.

As we said earlier, throwing an exception is like pulling a fire alarm. The throw occurs somewhere within the scope of the try block. The “fire department” in this case is the code contained in the catch clause that immediately follows the try block. This is the exception handler for this particular exception. There’s something like a game of catch going on here: Some method within the try block throws an Exception object, which is caught and handled by the catch block located in some other object (Figure 2).

Playing catch: in this design, the IllegalArgumentException is thrown by the CalcAverage.avgFirstN() method and caught by the catch clause within CalcAvgTest.main() method.

11.2.5. Syntax and Semantics of Try/Throw/Catch¶

A try block begins with the keyword try followed by a block of code enclosed within curly braces. A catch clause or catch block consists of the keyword catch, followed by a parameter declaration that identifies the type of Exception being caught, followed by a collection of statements enclosed within curly braces. These are the statements that handle the exception by taking appropriate action.

Once an exception is thrown, control is transferred out of the try block to an appropriate catch block. Control does not return to the try block.

The complete syntax of the try/catch statement is summarized below.

try {
      // Block of statements
      // At least one of which may throw an exception
      if ( /* Some condition obtains */ )
          throw new ExceptionName();
 } catch (ExceptionName ParameterName) {
     // Block of statements to be executed
     // If the ExceptionName exception is thrown in try
 }  catch (ExceptionName2 ParameterName) {
     // Block of statements to be executed
     // If the ExceptionName2 exception is thrown in try
...  // Possibly other catch clauses
} finally {
     // Optional block of statements that is executed
     // Whether an exception is thrown or not
 }

The try block is meant to include a statement or statements that might throw an exception. The catch blocks—there can be one or more—are meant to handle exceptions that are thrown in the try block. A catch block will handle any exception that matches its parameter class, including subclasses of that class. The finally block clause is an optional clause that is always executed, whether an exception is thrown or not.

The statements in the try block are part of the program’s normal flow of execution. By encapsulating a group of statements within a try block, you thereby indicate that one or more exceptions may be thrown by those statements, and that you intend to catch them. In effect, you are trying a block of code with the possibility that something might go wrong.

If an exception is thrown within a try block, Java exits the block and transfers control to the first catch block that matches the particular kind of exception that was thrown. Exceptions are thrown by using the throw statement, which takes the following general form:

throw new ExceptionClassName(OptionalMessageString);

The keyword throw is followed by the instantiation of an object of the ExceptionClassName class. This is done the same way we instantiate any object in Java: by using the new operator and invoking one of the exception’s constructor methods. Some of the constructors take an OptionalMessageString, which is the message that gets returned by the exception’s getMessage() method.

A catch block has the following general form:

catch (ExceptionClassName ParameterName) {
    // Exception handling statements
  }

A catch block is very much like a method definition. It contains a parameter, which specifies the class of exception that is handled by that block. The ParameterName can be any valid identifier, but it is customary to use e as the catch block parameter. The parameter’s scope is limited to the catch block, and it is used to refer to the caught exception.

The ExceptionClassName must be one of the classes in Java’s exception hierarchy (see Figure 2). A thrown exception will match any parameter of its own class or any of its superclasses. Thus, if an ArithmeticException is thrown, it will match both an ArithmeticException parameter and an Exception parameter, because ArithmeticException is a subclass of Exception.

Note that there can be multiple catch clauses associated with a given try block, and the order with which they are arranged is important. A thrown exception will be caught by the first catch clause it matches. Therefore, catch clauses should be arranged in order from most specific to most general (See the exception hierarchy in Figure 2). If a more general catch clause precedes a more specific one, it will prevent the more specific one from executing. In effect, the more specific clause will be hidden by the more general one. You might as well just not have the more specific clause at all.

To illustrate how to arrange catch clauses, suppose an ArithmeticException is thrown in the following try/catch statement:

try {
     // Suppose an ArithmeticException is thrown here
} catch (ArithmeticException e) {
     System.out.println("ERROR: " + e.getMessage() );
     e.printStackTrace();
     System.exit(1);
} catch (Exception e) {
     System.out.println("ERROR: " + e.getMessage() );
    }

In this case, the exception would be handled by the more specific ArithmeticException block. On the other hand, if some other kind of exception is raised, it will be caught by the second catch clause. The Exception class will match any exception that is thrown. Therefore, it should always occur last in a sequence of catch clauses. Catch clauses should be arranged from most specific to most general. The Exception clause should always be the last in the sequence.

11.2.6. Exception Propagation: Searching for a Catch Block¶

When an exception is thrown, Java searches for a catch clause to handle it. This search process involves looking through the program’s structure and method calls to find an appropriate exception handler.

Java uses a method call stack to keep track of the program’s execution. A method call stack is a data structure that behaves like a stack of dishes in a cafeteria. For each method call, a method call block is placed on top of the stack (like a dish), and when a particular method call returns, its block is removed from the top of the stack. In the figure below, the method call stack for the Propagate program is shown. The curved arrows give a trace of the method calls leading to the program’s present state.

An important feature of the method call stack is that the current executing method is always represented by the top block on the method call stack. If an exception occurs during that method call, Java can trace backward through the method calls to find an exception handler for that exception. In this figure, you can visualize this back trace as a matter of reversing the direction of the curved arrows.

To find a matching catch block for an exception, Java performs a method stack trace. The basic idea is that Java traces backward through the program until it finds an appropriate catch clause. The search begins within the block that threw the exception. If the exception is not caught by the block in which it is thrown, Java searches the enclosing block. If it is not caught within the enclosing block, Java searches the next higher enclosing block, and so on.

If the exception is not caught at all within the method in which it was thrown, Java uses the method call stack to search backward through the method calls that were made leading up to the exception. In the case of our CalcAvgTest() example, Java would search backward to the CalcAvgTest.main() method, which is where avgFirstN() was called, and it would find the catch clause there for handling ``IllegalArgumentException``s. It would, therefore, execute that catch clause.