The JavaTM Tutorial
Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search
Feedback Form

Trail: Essential Java Classes
Lesson: Handling Errors with Exceptions

How to Throw Exceptions

Before you can catch an exception, some code somewhere must throw one. Any code can throw an exception: your code, code from a package written by someone else (such as the packages that come with the Java platform), or the Java runtime environment. Regardless of what throws the exception, it’s always thrown with the throw statement.

As you have probably noticed, the Java platform provides numerous exception classes. All these classes are descendants of the Throwable (in the API reference documentation) class and all allow programs to differentiate among the various types of exceptions that can occur during the execution of a program.

You also can create your own exception classes to represent problems that can occur within the classes that you write. In fact, if you are a package developer, you might have to create your own set of exception classes so as to allow your users to differentiate an error that can occur in your package from errors that occur in the Java platform or other packages.

You can also create chained exceptions, which were introduced in Java Standard Edition 1.4. For more information, see the Chained Exceptions (in the Essential Java Classes trail) section.

The throw Statement

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() throws EmptyStackException {
    Object obj;

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

    obj = objectAt(SIZE - 1);
    setObjectAt(SIZE - 1, null);
    size--;
    return obj;
}
The pop method checks 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. A later section in this chapter explains how you can 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 (in the API reference documentation) class.

Note that the declaration of the pop method contains a throws clause. EmptyStackException is a checked exception, and the pop method makes no effort to catch it. Hence, the method must use the throws clause to declare that it can throw that type of exception.

Throwable Class and Its Subclasses

The objects that inherit from the Throwable (in the API reference documentation) 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). The figure below illustrates the class hierarchy of the Throwable class and its most significant subclasses. As you can see, Throwable has two direct descendants: Error (in the API reference documentation) and Exception (in the API reference documentation).

The Throwable class and its most significant subclasses.

Error Class

When a dynamic linking failure or other “hard” failure in the Java Virtual Machine occurs, the virtual machine throws an Error (in the API reference documentation). Simple programs typically do not catch or throw Errors.

Exception Class

Most programs throw and catch objects that derive from the Exception (in the API reference documentation) 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 Exception class has many descendants defined in the Java platform. 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 has special meaning: RuntimeException. RuntimeExceptions are exceptions that occur within the Java Virtual Machine during runtime. 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 section Unchecked Exceptions — The Controversy (in the Essential Java Classes trail) discusses why typical programs shouldn’t throw runtime exceptions or subclass RuntimeException.


Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search
Feedback Form

Copyright 1995-2005 Sun Microsystems, Inc. All rights reserved.