Package org.apache.commons.lang.exception

## Interface Nestable

- All Known Implementing Classes:
    `CloneFailedException`, `NestableError`, `NestableException`, `NestableRuntimeException`, `NotImplementedException`, `SerializationException`, `UnhandledException`

      public interface Nestable

  An interface to be implemented by `Throwable` extensions which would like to be able to nest root exceptions inside themselves.
  Since:
    1.0
  Version:
    $Id: Nestable.java 512889 2007-02-28 18:18:20Z dlr $

- - ### Method Summary

    All Methods Instance Methods Abstract 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 error message of this and any nested `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​(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.

- - ### Method Detail

    - #### getCause

          Throwable getCause()

      Returns the reference to the exception or error that caused the exception implementing the `Nestable` to be thrown.
      Returns:
        throwable that caused the original exception

    - #### getMessage

          String getMessage()

      Returns the error message of this and any nested `Throwable`.
      Returns:
        the error message

    - #### getMessage

          String getMessage​(int index)

      Returns the error message of the `Throwable` in the chain of `Throwable`s at the specified index, numbered from 0.
      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
      Throws:
        `IndexOutOfBoundsException` - if the `index` argument is negative or not less than the count of `Throwable`s in the chain

    - #### getMessages

          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 `getThrowableCount()` operation.
      Returns:
        the error messages

    - #### getThrowable

          Throwable getThrowable​(int index)

      Returns the `Throwable` in the chain of `Throwable`s at the specified index, numbered from 0.
      Parameters:
        `index` - the index, numbered from 0, of the `Throwable` in the chain of `Throwable`s
      Returns:
        the `Throwable`
      Throws:
        `IndexOutOfBoundsException` - if the `index` argument is negative or not less than the count of `Throwable`s in the chain

    - #### getThrowableCount

          int getThrowableCount()

      Returns the number of nested `Throwable`s represented by this `Nestable`, including this `Nestable`.
      Returns:
        the throwable count

    - #### getThrowables

          Throwable[] getThrowables()

      Returns this `Nestable` and any nested `Throwable`s in an array of `Throwable`s, one element for each `Throwable`.
      Returns:
        the `Throwable`s

    - #### indexOfThrowable

          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).

      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

          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).

      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
      Throws:
        `IndexOutOfBoundsException` - if the `fromIndex` argument is negative or not less than the count of `Throwable`s in the chain

    - #### printStackTrace

          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.
      Parameters:
        `out` - `PrintWriter` to use for output.

    - #### printStackTrace

          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.
      Parameters:
        `out` - `PrintStream` to use for output.

    - #### printPartialStackTrace

          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.
      Parameters:
        `out` - The writer to use.