org.apache.commons.lang.exception
Class NestableException

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--org.apache.commons.lang.exception.NestableException

All Implemented Interfaces:

Nestable, java.io.Serializable

public class NestableException

extends java.lang.Exception

implements Nestable

The base class of all exceptions which can contain other exceptions. It is intended to ease the debugging by carrying on the information about the exception which was caught and provoked throwing the current exception. Catching and rethrowing may occur multiple times, and provided that all exceptions except the first one are descendands of NestedException, when the exception is finally printed out using any of the printStackTrace() methods, the stacktrace will contain the information about all exceptions thrown and caught on the way.

Running the following program

  1 import org.apache.commons.NestedException;
  2
  3 public class Test {
  4     public static void main( String[] args ) {
  5         try {
  6             a();
  7         } catch(Exception e) {
  8             e.printStackTrace();
  9         }
 10      }
 11
 12      public static void a() throws Exception {
 13          try {
 14              b();
 15          } catch(Exception e) {
 16              throw new NestedException("foo", e);
 17          }
 18      }
 19
 20      public static void b() throws Exception {
 21          try {
 22              c();
 23          } catch(Exception e) {
 24              throw new NestedException("bar", e);
 25          }
 26      }
 27
 28      public static void c() throws Exception {
 29          throw new Exception("baz");
 30      }
 31 }
 

Yields the following stacktrace:

 java.lang.Exception: baz: bar: foo
    at Test.c(Test.java:29)
    at Test.b(Test.java:22)
 rethrown as NestedException: bar
    at Test.b(Test.java:24)
    at Test.a(Test.java:14)
 rethrown as NestedException: foo
    at Test.a(Test.java:16)
    at Test.main(Test.java:6)
 

Version:

$Id: NestableException.java,v 1.5 2002/09/29 08:20:52 bayard Exp $

Author:

Rafal Krzewski, Daniel Rall, Kasper Nielsen, Steven Caswell

See Also:

Serialized Form

Field Summary

private java.lang.Throwable	cause Holds the reference to the exception or error that caused this exception to be thrown.
protected NestableDelegate	delegate The helper instance which contains much of the code which we delegate to.

Fields inherited from class java.lang.Throwable

backtrace, detailMessage, serialVersionUID

Constructor Summary

NestableException()
Constructs a new NestableException without specified detail message.

NestableException(java.lang.String msg)
Constructs a new NestableException with specified detail message.

NestableException(java.lang.String msg, java.lang.Throwable cause)
Constructs a new NestableException with specified detail message and nested Throwable.

NestableException(java.lang.Throwable cause)
Constructs a new NestableException with specified nested Throwable.

Method Summary

java.lang.Throwable	getCause() Returns the reference to the exception or error that caused the exception implementing the Nestable to be thrown.
java.lang.String	getMessage() Returns the error message of this and any nested Throwable.
java.lang.String	getMessage(int index) Returns the error message of the Throwable in the chain of Throwables at the specified index, numbererd from 0.
java.lang.String[]	getMessages() Returns the error message of this and any nested Throwables in an array of Strings, one element for each message.
java.lang.Throwable	getThrowable(int index) Returns the Throwable in the chain of Throwables at the specified index, numbererd from 0.
int	getThrowableCount() Returns the number of nested Throwables represented by this Nestable, including this Nestable.
java.lang.Throwable[]	getThrowables() Returns this Nestable and any nested Throwables in an array of Throwables, one element for each Throwable.
int	indexOfThrowable(java.lang.Class type) Returns the index, numbered from 0, of the first occurrence of the specified type in the chain of Throwables, or -1 if the specified type is not found in the chain.
int	indexOfThrowable(java.lang.Class type, int fromIndex) Returns the index, numbered from 0, of the first Throwable that matches the specified type in the chain of Throwables with an index greater than or equal to the specified index, or -1 if the type is not found.
void	printPartialStackTrace(java.io.PrintWriter out) Prints the stack trace for this exception only--root cause not included--using the provided writer.
void	printStackTrace()
void	printStackTrace(java.io.PrintStream out) Prints the stack trace of this exception to the specified print stream.
void	printStackTrace(java.io.PrintWriter out) Prints the stack trace of this exception to the specified print writer.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, printStackTrace0, toString

Methods inherited from class java.lang.Object

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

Field Detail

delegate

protected NestableDelegate delegate

The helper instance which contains much of the code which we delegate to.

cause

private java.lang.Throwable cause

Holds the reference to the exception or error that caused this exception to be thrown.

Constructor Detail

NestableException

public NestableException()

Constructs a new NestableException without specified detail message.

NestableException

public NestableException(java.lang.String msg)

Constructs a new NestableException with specified detail message.

Parameters:

msg - The error message.

NestableException

public NestableException(java.lang.Throwable cause)

Constructs a new NestableException with specified nested Throwable.

Parameters:

cause - the exception or error that caused this exception to be thrown

NestableException

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

Constructs a new NestableException with specified detail message and nested Throwable.

Parameters:

msg - the error message

cause - the exception or error that caused this exception to be thrown

Method Detail

getCause

public java.lang.Throwable getCause()

Description copied from interface: Nestable

Returns the reference to the exception or error that caused the exception implementing the Nestable to be thrown.

Specified by:

getCause in interface Nestable

getMessage

public java.lang.String getMessage()

Description copied from interface: Nestable

Returns the error message of this and any nested Throwable.

Specified by:

getMessage in interface Nestable

Overrides:

getMessage in class java.lang.Throwable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Returns:

the error message

getMessage

public java.lang.String getMessage(int index)

Description copied from interface: Nestable

Returns the error message of the Throwable in the chain of Throwables at the specified index, numbererd from 0.

Specified by:

getMessage in interface Nestable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Parameters:

index - the index of the Throwable in the chain of Throwables

Returns:

the error message, or null if the Throwable at the specified index in the chain does not contain a message

Throws:

IndexOutOfBoundsException - if the index argument is negative or not less than the count of Throwables in the chain

getMessages

public java.lang.String[] getMessages()

Description copied from interface: Nestable

Returns the error message of this and any nested Throwables in an array of Strings, one element for each message. Any Throwable not containing a message is represented in the array by a null. This has the effect of cause the length of the returned array to be equal to the result of the Nestable.getThrowableCount() operation.

Specified by:

getMessages in interface Nestable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Returns:

the error messages

getThrowable

public java.lang.Throwable getThrowable(int index)

Description copied from interface: Nestable

Returns the Throwable in the chain of Throwables at the specified index, numbererd from 0.

Specified by:

getThrowable in interface Nestable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Parameters:

index - the index, numbered from 0, of the Throwable in the chain of Throwables

Returns:

the Throwable

Throws:

IndexOutOfBoundsException - if the index argument is negative or not less than the count of Throwables in the chain

getThrowableCount

public int getThrowableCount()

Description copied from interface: Nestable

Returns the number of nested Throwables represented by this Nestable, including this Nestable.

Specified by:

getThrowableCount in interface Nestable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Returns:

the throwable count

getThrowables

public java.lang.Throwable[] getThrowables()

Description copied from interface: Nestable

Returns this Nestable and any nested Throwables in an array of Throwables, one element for each Throwable.

Specified by:

getThrowables in interface Nestable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Returns:

the Throwables

indexOfThrowable

public int indexOfThrowable(java.lang.Class type)

Description copied from interface: Nestable

Returns the index, numbered from 0, of the first occurrence of the specified type in the chain of Throwables, or -1 if the specified type is not found in the chain.

Specified by:

indexOfThrowable in interface Nestable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Parameters:

type - Class to be found

Returns:

index of the first occurrence of the type in the chain, or -1 if the type is not found

indexOfThrowable

public int indexOfThrowable(java.lang.Class type,
                            int fromIndex)

Description copied from interface: Nestable

Returns the index, numbered from 0, of the first Throwable that matches the specified type in the chain of Throwables with an index greater than or equal to the specified index, or -1 if the type is not found.

Specified by:

indexOfThrowable in interface Nestable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Parameters:

type - Class to be found

fromIndex - the index, numbered from 0, of the starting position in the chain to be searched

Returns:

index of the first occurrence of the type in the chain, or -1 if the type is not found

Throws:

IndexOutOfBoundsException - if the fromIndex argument is negative or not less than the count of Throwables in the chain

printStackTrace

public void printStackTrace()

Overrides:

printStackTrace in class java.lang.Throwable

printStackTrace

public void printStackTrace(java.io.PrintStream out)

Description copied from interface: Nestable

Prints the stack trace of this exception to the specified print stream. Includes inforamation from the exception--if any--which caused this exception.

Specified by:

printStackTrace in interface Nestable

Overrides:

printStackTrace in class java.lang.Throwable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Parameters:

out - PrintStream to use for output.

printStackTrace

public void printStackTrace(java.io.PrintWriter out)

Description copied from interface: Nestable

Prints the stack trace of this exception to the specified print writer. Includes inforamation from the exception--if any--which caused this exception.

Specified by:

printStackTrace in interface Nestable

Overrides:

printStackTrace in class java.lang.Throwable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Parameters:

out - PrintWriter to use for output.

printPartialStackTrace

public final void printPartialStackTrace(java.io.PrintWriter out)

Description copied from interface: Nestable

Prints the stack trace for this exception only--root cause not included--using the provided writer. Used by NestableDelegate to write individual stack traces to a buffer. The implementation of this method should call super.printStackTrace(out); in most cases.

Specified by:

printPartialStackTrace in interface Nestable

Following copied from interface: org.apache.commons.lang.exception.Nestable

Parameters:

out - The writer to use.