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

Chained Exceptions

Chained exceptions allow you to rethrow an exception, providing additional information without losing the original cause of the exception. The chained exception API was introduced in 1.4 by adding a cause property of type Throwable to exceptions. Two methods and two constructors were added to Throwable, the class from which all exceptions inherit. Since every Throwable can have a cause, each exception can have a cause, which itself can have a cause, and so on.

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

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.

Accessing Stack Trace Information

Now let’s suppose that the higher-level exception handler wants to dump the stack trace in its own format.

Definition:  A stack trace provides information on the execution history of the current thread and lists the names of the classes and methods that were called at the point when the exception occurred. A stack trace is a useful debugging tool that you'll normally take advantage of when an exception has been thrown.
The following code shows how to call the getStackTrace method on the exception object:
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() + "()");
    }
}

Logging API

In the next code snippet, we log where an exception occured from within the catch block. However, rather than manually parsing the stack trace and sending the output to System.err(), we send the output to a file using the logging facility in the java.util.logging (in the API reference documentation) package (added in the 1.4 release of the Java platform).
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());
    }
}

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.