Five months ago, I began a mini-series of articles about designing objects. In this
Design Techniques article, I'll continue that series by looking at design principles that concern error reporting and exceptions. I'll assume in this article that you know what exceptions are and how they work. If you would like a refresher on exceptions in general, see the companion article, "
Exceptions in Java".
The benefits of exceptions
Exceptions have several benefits. First, they allow you to separate error handling code from normal code. You can surround the code that you expect to execute 99.9% of the time with a try block, and then place error handling code in catch clauses -- code that you don't expect to get executed often, if ever. This arrangement has the nice benefit of making your "normal" code less cluttered.
If you feel that a method doesn't know how to handle a particular error, you can throw an exception from the method and let someone else deal with it. If you throw a "checked" exception, you enlist the help of the Java compiler to force client programmers to deal with the potential exception, either by catching it or declaring it in the throws clause of their methods. The fact that Java compilers make sure checked exceptions are handled helps make Java programs more robust.
When to throw exceptions
When should you throw an exception? The answer can be summed up in one guideline:
If your method encounters an abnormal condition that it can't handle, it should throw an exception.
Unfortunately, though this guideline may be easy to memorize and may sound impressive when you recite it at parties, it doesn't clear up the picture too much. It actually leads to a different question: What is an "abnormal condition?"
That, it turns out, is the $64,000 question. Deciding whether or not a particular event qualifies as an "abnormal condition" is a subjective judgment. The decision is not always obvious. It's one reason they pay you the big bucks.
A more helpful rule of thumb could be:
Avoid using exceptions to indicate conditions that can reasonably be expected as part of the typical functioning of the method.
An abnormal condition, therefore, would be any condition that wouldn't reasonably be expected as part of the "normal functioning" of a method. To help you get a feel for what I mean by "normal functioning of a method," allow me to give a few examples.
A few examples
As an illustration, consider the
FileInputStream and
DataInputStream classes from the
java.io package. Here is an application that uses
FileInputStream to print the text of a file to the standard output:
// In source packet in file except/ex9/Example9a.java
import java.io.*;
class Example9a {
public static void main(String[] args)
throws IOException {
if (args.length == 0) {
System.out.println("Must give filename as first arg.");
return;
}
FileInputStream in;
try {
in = new FileInputStream(args[0]);
}
catch (FileNotFoundException e) {
System.out.println("Can't find file: " + args[0]);
return;
}
int ch;
while ((ch = in.read()) != -1) {
System.out.print((char) ch);
}
System.out.println();
in.close();
}
}
This example shows that the
read() method of
FileInputStream reports an "end of file has been reached" condition not by throwing an exception, but by returning a special value: -1. In this method, reaching end of file is considered a "normal" part of using the method. It is not considered an "abnormal" condition. The usual way to read bytes is to keep on reading them until you hit the end.
The
DataInputStream class, on the other hand, takes a different approach when reporting end of file:
// In source packet in file except/ex9b/Example9b.java
import java.io.*;
class Example9b {
public static void main(String[] args)
throws IOException {
if (args.length == 0) {
System.out.println("Must give filename as first arg.");
return;
}
FileInputStream fin;
try {
fin = new FileInputStream(args[0]);
}
catch (FileNotFoundException e) {
System.out.println("Can't find file: " + args[0]);
return;
}
DataInputStream din = new DataInputStream(fin);
try {
int i;
for (;;) {
i = din.readInt();
System.out.println(i);
}
}
catch (EOFException e) {
}
fin.close();
}
}
Each time the
readInt() method of
DataInputStream is invoked, it reads four bytes from the stream and interprets them as an
int. When
readInt() encounters end of file, it throws
EOFException.
Throwing an exception is a reasonable approach for this method for two reasons. First,
readInt() can't return a special value to indicate end of file, because all possible return values are valid
ints. (It can't return -1 on end of file, for example, because it may read a -1 from the stream and need to return it as a valid
int value.) Second, if
readInt() encounters end of file after reading only one, two, or three bytes, that probably qualifies as an "abnormal condition." The method is supposed to read four bytes, but only one to three are available. Given that this exception is an integral part of using this class, it is a checked exception (a subclass of
Exception). Client programmers are forced to deal with it.
A third approach to signaling an "end has been reached" condition is illustrated by the
StringTokenizer and
Stack classes in the following example:
// In source packet in file except/ex9b/Example9c.java
// This program prints the white-space separated tokens of an
// ASCII file in reverse order of their appearance in the file.
import java.io.*;
import java.util.*;
class Example9c {
public static void main(String[] args)
throws IOException {
if (args.length == 0) {
System.out.println("Must give filename as first arg.");
return;
}
FileInputStream in = null;
try {
in = new FileInputStream(args[0]);
}
catch (FileNotFoundException e) {
System.out.println("Can't find file: " + args[0]);
return;
}
// Read file into a StringBuffer
StringBuffer buf = new StringBuffer();
try {
int ch;
while ((ch = in.read()) != -1) {
buf.append((char) ch);
}
}
finally {
in.close();
}
// Separate StringBuffer into tokens and
// push each token into a Stack
StringTokenizer tok = new StringTokenizer(buf.toString());
Stack stack = new Stack();
while (tok.hasMoreTokens()) {
stack.push(tok.nextToken());
}
// Print out tokens in reverse order.
while (!stack.empty()) {
System.out.println((String) stack.pop());
}
}
}
This example reads in the bytes of a file, converts them to
chars, and places the
chars into a
StringBuffer. It then uses a
StringTokenizer to extract one white-space separated token (a
String) at a time and push it onto a
Stack. Next it pops all tokens from the
Stack and prints them out one per line. Because
Stack implements a Last In First Out (LIFO) stack, the tokens are printed in reverse order from their appearance in the file.
Both the
StringTokenizer and the
Stack must signal an "end has been reached" condition. The
StringTokenizer constructor takes as a parameter the source
String to tokenize. Each invocation of
nextToken() returns a
String that represents the next token of the source
String. Eventually, all the tokens in the source
String will be consumed, and
StringTokenizer must somehow indicate that the end of tokens has been reached. In this case, there is a special return value,
null, that could have been used to indicate the end of tokens. But the designer of this class took a different approach. A separate method,
hasMoreTokens(), returns a boolean value indicating whether or not the end of tokens has been reached. You must invoke
hasMoreTokens() each time you invoke
nextToken().
This approach shows that the designer did not consider reaching the end of tokens an abnormal condition. It is a normal way to use the class. After the end has been reached, however, if you don't check
hasMoreTokens() and call
nextToken(), you will be rewarded with the
NoSuchElementException. Although this exception is thrown on an end of tokens condition, it is an unchecked exception (a subclass of
RuntimeException). It is thrown more to indicate a software bug -- that you are not using the class correctly -- than to indicate the end of tokens condition.
Similarly, the
Stack class has a method,
empty(), that returns a boolean to indicate that the last object has been popped from the stack. You must invoke
empty() each time you invoke
pop(). If you neglect to invoke
empty()and invoke
pop() on an empty stack, you get an
EmptyStackException. Although this exception is thrown when an "end of objects on the stack" condition is encountered, it is another unchecked runtime exception. It is intended to be more an indication of a software bug in the client code (the improper use of the
Stack class) than the normal way to detect an empty stack.
Exceptions indicate a broken contract
The examples above should give you a feel for when you would want to throw an exception instead of using some other means to communicate an event. One other way to think about exceptions, which may give you more insight into when you should use them, is that exceptions indicate a "broken contract."
One design approach often discussed in the context of object-oriented programming is the Design by Contract approach. This approach to software design says that a method represents a contract between the client (the caller of the method) and the class that declares the method. The contract includes preconditions that the client must fulfill and postconditions that the method itself must fulfill.
Precondition
One example of a method with a precondition is the
charAt(int index) method of class
String. This method requires that the
index parameter passed by the client be between 0 and one less than the value returned by invoking
length() on the
String object. In other words, if the length of a
String is 5, the
index parameter must be between 0 and 4, inclusive.
Postcondition
The postcondition of
String's
charAt(int index) method is that its return value will be the character at position
index and the string itself will remain unchanged.
If the client invokes
charAt() and passes -1 or some value
length() or greater, the client has broken the contract. In this case, the
charAt() method can't do its job correctly, and it signals this to the client by throwing a
StringIndexOutOfBoundsException. This exception indicates that the client has some kind of software bug or has not used the class correctly.
If the
charAt() method finds that it has received good input (the client has kept its part of the bargain), but for some reason is unable to return the character at the requested index (unable to fulfill its end of the contract), it would indicate this condition by throwing an exception. Such an exception would indicate that the method has some kind of bug or difficulty with runtime resources.
So, if an event represents an "abnormal condition" or a "broken contract," the thing to do in Java programs is to throw an exception.
What to throw?
Once you have decided to throw an exception, you need to decide which exception to throw. You can throw an instance of class
Throwable, or any subclass of
Throwable. You can throw an already existing throwable object from the Java API, or define and throw one of your own. How do you decide?
Exceptions versus errors
In general, you should throw an exception and and never throw errors.
Error, a subclass of
Throwable, is intended for drastic problems, such as
OutOfMemoryError, which would be reported by the JVM itself. On occasion an error, such as
java.awt.AWTError, could be thrown by the Java API. In your code, however, you should restrict yourself to throwing exceptions (subclasses of class
Exception). Leave the errors to the big guys.
Checked vs Unchecked exceptions
The big question, then, is whether to throw a "checked" or an "unchecked" exception. A checked exception is some subclass of
Exception (or
Exception itself), excluding class
RuntimeException and its subclasses. Unchecked exceptions are
RuntimeException and any of its subclasses. Class
Error and its subclasses also are unchecked, but as you should be focusing on throwing exceptions only, your decision should be whether to throw a subclass of
RuntimeException (an unchecked exception) or some other subclass of
Exception (a checked exception).
If you throw a checked exception (and don't catch it), you will need to declare the exception in your method's
throws clause. Client programmers who wish to call your method will then need to either catch and handle the exception within the body of their methods, or declare the exception in the throws clause of their methods. Making an exception checked forces client programmers to deal with the possibility that the exception will be thrown.
If you throw an unchecked exception, client programmers can decide whether to catch or disregard the exception, just as with checked exceptions. With an unchecked exception, however, the compiler doesn't force client programmers either to catch the exception or declare it in a throws clause. In fact, client programmers may not even know that the exception could be thrown. Either way, client programmers are less likely to think about what they should do in the event of an unchecked exception than they are in the case of an checked exception.
The simple guideline is:
If you are throwing an exception for an abnormal condition that you feel client programmers should consciously decide how to handle, throw a checked exception.
In general, exceptions that indicate an improper use of a class should be unchecked. The
StringIndexOutOfBoundsException thrown by
String's
charAt() method is an unchecked exception. The designers of the
String class didn't want to force client programmers to deal with the possibility of an invalid
index parameter every time they called
charAt(int index).
The
read() method of class
java.io.FileInputStream, on the other hand, throws
IOException, which is a checked exception. This exception indicates some kind of error occurred while attempting to read from the file. It doesn't indicate that the client has used the
FileInputStream class improperly. It just signals that the method itself is unable to fulfill its contractual responsibility of reading in the next byte from the file. The designers of the
FileInputStream class considered this abnormal condition to be common enough, and important enough, to force client programmers to deal with it.
That is the trick, then, of deciding between a checked and an unchecked exception. If the abnormal condition is a failure of the method to fulfill its contract, and you feel it is common or important enough that client programmers should be forced to deal with the possibility of the exception, throw a checked exception. Otherwise, throw an unchecked exception.
Define a specific exception class
Finally, you must decide which exception class to instantiate and throw. The general rule here is to be specific. Don't just throw
Exception, for example, with a string message indicating the kind of abnormal condition that caused the exception. Define or choose an already existing exception class for each kind of abnormal condition that may cause your method to throw an exception. This way, client programmers can define a separate catch clause for each kind of exception, or can catch some but not others, without having to query the object to determine the kind of abnormal condition that caused the exception.
You may wish to embed some information in the exception object, to give the catch clause more details about the exception. But you don't want to rely solely on embedded information to distinguish one type of exception from another. You don't want clients to have to query the exception object to determine, for example, whether the problem was an I/O error or an illegal argument.
Note that when
String.charAt(int index) receives a bad input, it doesn't throw
RuntimeException or even
IllegalArgumentException. It throws
StringIndexOutOfBoundsException. The type name indicates that the problem was a string index, and the program can query the object to find out what the bad index was.
Conclusion
The most important point to take away from this article is that exceptions are there for
abnormal conditions and shouldn't be used to report conditions that can be reasonably expected as part of the everyday functioning of a method. Although the use of exceptions can help make your code easier to read by separating the "normal" code from the error handling code, their inappropriate use can make your code harder to read.
Here is a collection of the exception guidelines put forth by this article:
- If your method encounters an abnormal condition that it can't handle, it should throw an exception.
- Avoid using exceptions to indicate conditions that can reasonably be expected as part of the normal functioning of the method.
- If your method discovers that the client has breached its contractual obligations (for example, by passing in bad input data), throw an unchecked exception.
- If your method is unable to fulfill its contract, throw either a checked or unchecked exception.
- If you are throwing an exception for an abnormal condition that you feel client programmers should consciously decide how to handle, throw a checked exception.
- Define or choose an already existing exception class for each kind of abnormal condition that may cause your method to throw an exception.
