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:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected NestableDelegate` | `delegate` | The helper instance which contains much of the code which we delegate to.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `NestableException()` | Constructs a new `NestableException` without specified detail message.
    `NestableException​(String msg)` | Constructs a new `NestableException` with specified detail message.
    `NestableException​(String msg, Throwable cause)` | Constructs a new `NestableException` with specified detail message and nested `Throwable`.
    `NestableException​(Throwable cause)` | Constructs a new `NestableException` with specified nested `Throwable`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Throwable` | `getCause()` | Returns the reference to the exception or error that caused the exception implementing the `Nestable` to be thrown.
    `String` | `getMessage()` | Returns the detail message string of this throwable.
    `String` | `getMessage​(int index)` | Returns the error message of the `Throwable` in the chain of `Throwable`s at the specified index, numbered from 0.
    `String[]` | `getMessages()` | Returns the error message of this and any nested `Throwable`s in an array of Strings, one element for each message.
    `Throwable` | `getThrowable​(int index)` | Returns the `Throwable` in the chain of `Throwable`s at the specified index, numbered from 0.
    `int` | `getThrowableCount()` | Returns the number of nested `Throwable`s represented by this `Nestable`, including this `Nestable`.
    `Throwable[]` | `getThrowables()` | Returns this `Nestable` and any nested `Throwable`s in an array of `Throwable`s, one element for each `Throwable`.
    `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 `Throwable`s.
    `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 `Throwable`s with an index greater than or equal to the specified index.
    `void` | `printPartialStackTrace​(PrintWriter out)` | Prints the stack trace for this exception only--root cause not included--using the provided writer.
    `void` | `printStackTrace()`
    `void` | `printStackTrace​(PrintStream out)` | Prints the stack trace of this exception to the specified print stream.
    `void` | `printStackTrace​(PrintWriter out)` | Prints the stack trace of this exception to the specified print writer.

    - ### Methods inherited from class java.lang.Throwable

      `addSuppressed, fillInStackTrace, getLocalizedMessage, getStackTrace, getSuppressed, initCause, setStackTrace, toString`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### delegate

          protected NestableDelegate delegate

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

  - ### Constructor Detail

    - #### 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 Detail

    - #### 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 `Throwable`s at the specified index, numbered from 0.
      Specified by:
        `getMessage` in interface `Nestable`
      Parameters:
        `index` - the index of the `Throwable` in the chain of `Throwable`s
      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 `Throwable`s 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 `Throwable`s 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 `Throwable`s
      Returns:
        the `Throwable`

    - #### getThrowableCount

          public int getThrowableCount()

      Returns the number of nested `Throwable`s 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 `Throwable`s in an array of `Throwable`s, one element for each `Throwable`.
      Specified by:
        `getThrowables` in interface `Nestable`
      Returns:
        the `Throwable`s

    - #### 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 `Throwable`s. 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 `Throwable`s 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.