Package org.apache.commons.lang.exception

## Class NestableDelegate

- java.lang.Object
- - org.apache.commons.lang.exception.NestableDelegate

- All Implemented Interfaces:
    `Serializable`

      public class NestableDelegate
      extends Object
      implements Serializable

  A shared implementation of the nestable exception functionality.

  The code is shared between `NestableError`, `NestableException` and `NestableRuntimeException`.

  Since:
    1.0
  Version:
    $Id: NestableDelegate.java 905636 2010-02-02 14:03:32Z niallp $
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static boolean` | `matchSubclasses` | Whether to match subclasses via indexOf.
    `static boolean` | `topDown` | Whether to print the stack trace top-down.
    `static boolean` | `trimStackFrames` | Whether to trim the repeated stack trace.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `NestableDelegate​(Nestable nestable)` | Constructs a new `NestableDelegate` instance to manage the specified `Nestable`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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` | `getMessage​(String baseMsg)` | Returns the full message contained by the `Nestable` and any nested `Throwable`s.
    `String[]` | `getMessages()` | Returns the error message of this and any nested `Throwable`s in an array of Strings, one element for each message.
    `protected String[]` | `getStackFrames​(Throwable t)` | Captures the stack trace associated with the specified `Throwable` object, decomposing it into a list of stack frames.
    `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 `Throwable`s contained in the `Nestable` contained by this delegate.
    `Throwable[]` | `getThrowables()` | Returns this delegate's `Nestable` and any nested `Throwable`s in an array of `Throwable`s, one element for each `Throwable`.
    `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` | `printStackTrace()` | Prints the stack trace of this exception the the standar error stream.
    `void` | `printStackTrace​(PrintStream out)` | Prints the stack trace of this exception to the specified stream.
    `void` | `printStackTrace​(PrintWriter out)` | Prints the stack trace of this exception to the specified writer.
    `protected void` | `trimStackFrames​(List stacks)` | Trims the stack frames.

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

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

- - ### Field Detail

    - #### topDown

          public static boolean topDown

      Whether to print the stack trace top-down. This public flag may be set by calling code, typically in initialisation. This exists for backwards compatability, setting it to false will return the library to v1.0 behaviour (but will affect all users of the library in the classloader).
      Since:
        2.0

    - #### trimStackFrames

          public static boolean trimStackFrames

      Whether to trim the repeated stack trace. This public flag may be set by calling code, typically in initialisation. This exists for backwards compatability, setting it to false will return the library to v1.0 behaviour (but will affect all users of the library in the classloader).
      Since:
        2.0

    - #### matchSubclasses

          public static boolean matchSubclasses

      Whether to match subclasses via indexOf. This public flag may be set by calling code, typically in initialisation. This exists for backwards compatability, setting it to false will return the library to v2.0 behaviour (but will affect all users of the library in the classloader).
      Since:
        2.1

  - ### Constructor Detail

    - #### NestableDelegate

          public NestableDelegate​(Nestable nestable)

      Constructs a new `NestableDelegate` instance to manage the specified `Nestable`.
      Parameters:
        `nestable` - the Nestable implementation (must extend `Throwable`)
      Since:
        2.0

  - ### Method Detail

    - #### 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.
      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
      Since:
        2.0

    - #### getMessage

          public String getMessage​(String baseMsg)

      Returns the full message contained by the `Nestable` and any nested `Throwable`s.
      Parameters:
        `baseMsg` - the base message to use when creating the full message. Should be generally be called via `nestableHelper.getMessage(super.getMessage())`, where `super` is an instance of `Throwable`.
      Returns:
        The concatenated message for this and all nested `Throwable`s
      Since:
        2.0

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

    - #### getThrowable

          public 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
      Since:
        2.0

    - #### getThrowableCount

          public int getThrowableCount()

      Returns the number of `Throwable`s contained in the `Nestable` contained by this delegate.
      Returns:
        the throwable count
      Since:
        2.0

    - #### getThrowables

          public Throwable[] getThrowables()

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

    - #### 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). An alternative is to use the public static flag `matchSubclasses` on `NestableDelegate`, however this is not recommended.

      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
      Since:
        2.0

    - #### printStackTrace

          public void printStackTrace()

      Prints the stack trace of this exception the the standar error stream.

    - #### printStackTrace

          public void printStackTrace​(PrintStream out)

      Prints the stack trace of this exception to the specified stream.
      Parameters:
        `out` - `PrintStream` to use for output.
      See Also:
        `printStackTrace(PrintWriter)`

    - #### printStackTrace

          public void printStackTrace​(PrintWriter out)

      Prints the stack trace of this exception to the specified writer. If the Throwable class has a `getCause` method (i.e. running on jre1.4 or higher), this method just uses Throwable's printStackTrace() method. Otherwise, generates the stack-trace, by taking into account the 'topDown' and 'trimStackFrames' parameters. The topDown and trimStackFrames are set to 'true' by default (produces jre1.4-like stack trace).
      Parameters:
        `out` - `PrintWriter` to use for output.

    - #### getStackFrames

          protected String[] getStackFrames​(Throwable t)

      Captures the stack trace associated with the specified `Throwable` object, decomposing it into a list of stack frames.
      Parameters:
        `t` - The `Throwable`.
      Returns:
        An array of strings describing each stack frame.
      Since:
        2.0

    - #### trimStackFrames

          protected void trimStackFrames​(List stacks)

      Trims the stack frames. The first set is left untouched. The rest of the frames are truncated from the bottom by comparing with one just on top.
      Parameters:
        `stacks` - The list containing String[] elements
      Since:
        2.0