Package 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:
Serializable, Nestable
public class NestableException extends 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 descendants of NestedException, when the exception is finally printed out using any of the printStackTrace() methods, the stack trace will contain the information about all exceptions thrown and caught on the way.

Running the following program 

  1 import org.apache.commons.lang.exception.NestableException;
  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 NestableException("foo", e);
 17          }
 18      }
 19
 20      public static void b() throws Exception {
 21          try {
 22              c();
 23          } catch(Exception e) {
 24              throw new NestableException("bar", e);
 25          }
 26      }
 27
 28      public static void c() throws Exception {
 29          throw new Exception("baz");
 30      }
 31 }

Yields the following stack trace: 

 org.apache.commons.lang.exception.NestableException: foo
         at Test.a(Test.java:16)
         at Test.main(Test.java:6)
 Caused by: org.apache.commons.lang.exception.NestableException: bar
         at Test.b(Test.java:24)
         at Test.a(Test.java:14)
         ... 1 more
 Caused by: java.lang.Exception: baz
         at Test.c(Test.java:29)
         at Test.b(Test.java:22)
         ... 2 more

Since:
1.0
Version:
$Id: NestableException.java 512889 2007-02-28 18:18:20Z dlr $
See Also:

  • Field Details

    • delegate

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

  • Constructor Details

    • NestableException

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

    • NestableException

      public NestableException(String msg)
      Constructs a new NestableException with specified detail message.
      Parameters:
      msg - The error message.

    • NestableException

      public NestableException(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(String msg, 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 Details

    • getCause

      public Throwable getCause()
      Returns the reference to the exception or error that caused the exception implementing the Nestable to be thrown.
      Specified by:
      getCause in interface Nestable
      Overrides:
      getCause in class Throwable
      Returns:
      throwable that caused the original exception

    • getMessage

      public String getMessage()
      Returns the detail message string of this throwable. If it was created with a null message, returns the following: (cause==null ? null : cause.toString()).
      Specified by:
      getMessage in interface Nestable
      Overrides:
      getMessage in class Throwable
      Returns:
      String message string of the throwable

    • getMessage

      public String getMessage(int index)
      Returns the error message of the Throwable in the chain of Throwables at the specified index, numbered from 0.
      Specified by:
      getMessage in interface 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

    • getMessages

      public String[] getMessages()
      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
      Returns:
      the error messages

    • getThrowable

      public Throwable getThrowable(int index)
      Returns the Throwable in the chain of Throwables at the specified index, numbered from 0.
      Specified by:
      getThrowable in interface Nestable
      Parameters:
      index - the index, numbered from 0, of the Throwable in the chain of Throwables
      Returns:
      the Throwable

    • getThrowableCount

      public int getThrowableCount()
      Returns the number of nested Throwables represented by this Nestable, including this Nestable.
      Specified by:
      getThrowableCount in interface Nestable
      Returns:
      the throwable count

    • getThrowables

      public Throwable[] getThrowables()
      Returns this Nestable and any nested Throwables in an array of Throwables, one element for each Throwable.
      Specified by:
      getThrowables in interface Nestable
      Returns:
      the Throwables

    • indexOfThrowable

      public int indexOfThrowable(Class type)
      Returns the index, numbered from 0, of the first occurrence of the specified type, or a subclass, in the chain of Throwables. The method returns -1 if the specified type is not found in the chain.

      NOTE: From v2.1, we have clarified the Nestable interface such that this method matches subclasses. If you want to NOT match subclasses, please use ExceptionUtils.indexOfThrowable(Throwable, Class) (which is avaiable in all versions of lang).

      Specified by:
      indexOfThrowable in interface Nestable
      Parameters:
      type - the type to find, subclasses match, null returns -1
      Returns:
      index of the first occurrence of the type in the chain, or -1 if the type is not found

    • indexOfThrowable

      public int indexOfThrowable(Class type, int fromIndex)
      Returns the index, numbered from 0, of the first Throwable that matches the specified type, or a subclass, in the chain of Throwables with an index greater than or equal to the specified index. The method returns -1 if the specified type is not found in the chain.

      NOTE: From v2.1, we have clarified the Nestable interface such that this method matches subclasses. If you want to NOT match subclasses, please use ExceptionUtils.indexOfThrowable(Throwable, Class, int) (which is avaiable in all versions of lang).

      Specified by:
      indexOfThrowable in interface Nestable
      Parameters:
      type - the type to find, subclasses match, null returns -1
      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

    • printStackTrace

      public void printStackTrace()
      Overrides:
      printStackTrace in class Throwable

    • printStackTrace

      public void printStackTrace(PrintStream out)
      Prints the stack trace of this exception to the specified print stream. Includes information from the exception, if any, which caused this exception.
      Specified by:
      printStackTrace in interface Nestable
      Overrides:
      printStackTrace in class Throwable
      Parameters:
      out - PrintStream to use for output.

    • printStackTrace

      public void printStackTrace(PrintWriter out)
      Prints the stack trace of this exception to the specified print writer. Includes information from the exception, if any, which caused this exception.
      Specified by:
      printStackTrace in interface Nestable
      Overrides:
      printStackTrace in class Throwable
      Parameters:
      out - PrintWriter to use for output.

    • printPartialStackTrace

      public final void printPartialStackTrace(PrintWriter out)
      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
      Parameters:
      out - The writer to use.