com.svincent.util
Class NestableException

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--com.svincent.util.NestableException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

PrologException, ReflectException, SmallJavaBuildingException, SmallJavaValidationException

public class NestableException

extends java.lang.Exception

A NestableException is an exception which can contain a nested exception.

This is generally useful in a very common code idiom, in which some code catches an exception, then re-throws a differently typed exception.

For example,

try {
foo ();
} catch (SomeRandomException ex) {
throw new NestableException ("Could not foo()", ex);
}

It will be common to wish to subclass NestableException for all your friends and neighbors, as so:

public class WilsonException extends NestableException {
public WilsonException () { super (); }
public WilsonException (String msg) { super (msg); }
public WilsonException (String msg, Throwable ex) { super (msg, ex); }
}

When a stack trace for a NestableException is printed, the stack trace of the nested exception is also printed, seperated by the string "--- Nested Exception ---". In this way, a stack of stack traces are printed, for every exception to the root cause of the error. The stack trace dump is terminated by the string "--- No Nested Exception ---"

An example stack trace follows:

 com.engulfco.StartupException: Could not start the system!
         at com.engulfco.Starter.startup(Starter.java:129)
         at com.engulfco.Starter.main(Starter.java:116)
 --- Nested Exception ---
 com.engulfco.ProtocolFailure: Could not read initialization file!
         at com.engulfco.Protocol.initialize(Protocol.java:136)
         at com.engulfco.Starter.startup(Starter.java:126)
         at com.engulfco.Starter.main(NestableException.java:116)
 --- No Nested Exception ---
 

In this simple stack trace, you can see that the Starter class was unable to run due to a StartupException. However, we also discover that the StartupException was caused by a ProtocolFailure! In other exception handling schemes, the choice must be made whether to throw a new exception (which hides the original), or to let the underlying exception through (which mostly gives super-specific information which is also unneccesary). NestableException gives the best of both worlds.

Author:

Shawn Vincent

See Also:

NestableRuntimeException, Serialized Form

Constructor Summary

NestableException()

NestableException(java.lang.String msg)

NestableException(java.lang.String msg, java.lang.Throwable ex)

Method Summary

java.lang.Throwable	getNestedException()
java.lang.String	getStackTrace() A convenience method: returns the stack trace of this exception as a string.
static void	main(java.lang.String[] args) Test code
void	printStackTrace(java.io.PrintStream out) Print the stack trace of this exception to the given PrintStream.
void	printStackTrace(java.io.PrintWriter out) Print the stack trace of this exception to the given writer.
protected static void	testBar() Test code
protected static void	testFoo() Test code

Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NestableException

public NestableException()

NestableException

public NestableException(java.lang.String msg)

NestableException

public NestableException(java.lang.String msg,
                         java.lang.Throwable ex)

Method Detail

getNestedException

public java.lang.Throwable getNestedException()

getStackTrace

public java.lang.String getStackTrace()

A convenience method: returns the stack trace of this exception as a string.

printStackTrace

public void printStackTrace(java.io.PrintWriter out)

Print the stack trace of this exception to the given writer.

Overrides:

printStackTrace in class java.lang.Throwable

printStackTrace

public void printStackTrace(java.io.PrintStream out)

Print the stack trace of this exception to the given PrintStream.

Overrides:

printStackTrace in class java.lang.Throwable

main

public static void main(java.lang.String[] args)

Test code

testFoo

protected static void testFoo()
                       throws NestableException

Test code

testBar

protected static void testBar()
                       throws NestableException

Test code