Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.hibernate.exception
Class ExceptionUtils

    java.lang.Object
      org.hibernate.exception.ExceptionUtils

    public final class ExceptionUtils

extends Object

Provides utilities for manipulating and examining `Throwable` objects.

Since:
  1.0
Version:
  $Id: ExceptionUtils.java 4782 2004-11-21 00:11:27Z pgmjsd $
Author:
  Daniel Rall, Dmitri Plotnikov, Stephen Colebourne, Gary Gregory, Pete Gieser

Method Summary
`static Throwable` | `getCause(Throwable throwable)` Introspects the `Throwable` to obtain the cause.
`static Throwable` | `getCause(Throwable throwable, String[] methodNames)` Introspects the `Throwable` to obtain the cause.
`static String` | `getFullStackTrace(Throwable throwable)` A way to get the entire nested stack-trace of an throwable.
`static Throwable` | `getRootCause(Throwable throwable)` Introspects the `Throwable` to obtain the root cause.
`static String[]` | `getRootCauseStackTrace(Throwable throwable)` Creates a compact stack trace for the root cause of the supplied `Throwable`.
`static String[]` | `getStackFrames(Throwable throwable)` Captures the stack trace associated with the specified `Throwable` object, decomposing it into a list of stack frames.
`static String` | `getStackTrace(Throwable throwable)` Gets the stack trace from a Throwable as a String.
`static int` | `getThrowableCount(Throwable throwable)` Counts the number of `Throwable` objects in the exception chain.
`static Throwable[]` | `getThrowables(Throwable throwable)` Returns the list of `Throwable` objects in the exception chain.
`static int` | `indexOfThrowable(Throwable throwable, Class type)` Returns the (zero based) index of the first `Throwable` that matches the specified type in the exception chain.
`static int` | `indexOfThrowable(Throwable throwable, Class type, int fromIndex)` Returns the (zero based) index of the first `Throwable` that matches the specified type in the exception chain from a specified index.
`static boolean` | `isNestedThrowable(Throwable throwable)` Checks whether this `Throwable` class can store a cause.
`static boolean` | `isThrowableNested()` Checks if the Throwable class has a `getCause` method.
`static void` | `printRootCauseStackTrace(Throwable throwable)` Prints a compact stack trace for the root cause of a throwable to `System.err`.
`static void` | `printRootCauseStackTrace(Throwable throwable, PrintStream stream)` Prints a compact stack trace for the root cause of a throwable.
`static void` | `printRootCauseStackTrace(Throwable throwable, PrintWriter writer)` Prints a compact stack trace for the root cause of a throwable.
`static void` | `removeCommonFrames(List causeFrames, List wrapperFrames)` Removes common frames from the cause trace given the two stack traces.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### getCause

    public static Throwable getCause(Throwable throwable)

  Introspects the `Throwable` to obtain the cause.

  The method searches for methods with specific names that return a `Throwable` object. This will pick up most wrapping exceptions, including those from JDK 1.4, and `NestableException`. The method names can be added to using `#addCauseMethodName(String)`.

  The default list searched for are:

  - `getCause()`
  - `getNextException()`
  - `getTargetException()`
  - `getException()`
  - `getSourceException()`
  - `getRootCause()`
  - `getCausedByException()`
  - `getNested()`

  In the absence of any such method, the object is inspected for a `detail` field assignable to a `Throwable`.

  If none of the above is found, returns `null`.

  Parameters:
    `throwable` - the throwable to introspect for a cause, may be null
  Returns:
    the cause of the `Throwable`, `null` if none found or null throwable input

### getCause

    public static Throwable getCause(Throwable throwable,
                                     String[] methodNames)

  Introspects the `Throwable` to obtain the cause.

  1. Try known exception types.
  2. Try the supplied array of method names.
  3. Try the field 'detail'.

  A `null` set of method names means use the default set. A `null` in the set of method names will be ignored.

  Parameters:
    `throwable` - the throwable to introspect for a cause, may be null
    `methodNames` - the method names, null treated as default set
  Returns:
    the cause of the `Throwable`, `null` if none found or null throwable input

### getRootCause

    public static Throwable getRootCause(Throwable throwable)

  Introspects the `Throwable` to obtain the root cause.

  This method walks through the exception chain to the last element, "root" of the tree, using `getCause(Throwable)`, and returns that exception.

  Parameters:
    `throwable` - the throwable to get the root cause for, may be null
  Returns:
    the root cause of the `Throwable`, `null` if none found or null throwable input

### isThrowableNested

    public static boolean isThrowableNested()

  Checks if the Throwable class has a `getCause` method.

  This is true for JDK 1.4 and above.

  Returns:
    true if Throwable is nestable
  Since:
    2.0

### isNestedThrowable

    public static boolean isNestedThrowable(Throwable throwable)

  Checks whether this `Throwable` class can store a cause.

  This method does not check whether it actually does store a cause.

  Parameters:
    `throwable` - the `Throwable` to examine, may be null
  Returns:
    boolean `true` if nested otherwise `false`
  Since:
    2.0

### getThrowableCount

    public static int getThrowableCount(Throwable throwable)

  Counts the number of `Throwable` objects in the exception chain.

  A throwable without cause will return `1`. A throwable with one cause will return `2` and so on. A `null` throwable will return `0`.

  Parameters:
    `throwable` - the throwable to inspect, may be null
  Returns:
    the count of throwables, zero if null input

### getThrowables

    public static Throwable[] getThrowables(Throwable throwable)

  Returns the list of `Throwable` objects in the exception chain.

  A throwable without cause will return an array containing one element - the input throwable. A throwable with one cause will return an array containing two elements. - the input throwable and the cause throwable. A `null` throwable will return an array size zero.

  Parameters:
    `throwable` - the throwable to inspect, may be null
  Returns:
    the array of throwables, never null

### indexOfThrowable

    public static int indexOfThrowable(Throwable throwable,
                                       Class type)

  Returns the (zero based) index of the first `Throwable` that matches the specified type in the exception chain.

  A `null` throwable returns `-1`. A `null` type returns `-1`. No match in the chain returns `-1`.

  Parameters:
    `throwable` - the throwable to inspect, may be null
    `type` - the type to search for
  Returns:
    the index into the throwable chain, -1 if no match or null input

### indexOfThrowable

    public static int indexOfThrowable(Throwable throwable,
                                       Class type,
                                       int fromIndex)

  Returns the (zero based) index of the first `Throwable` that matches the specified type in the exception chain from a specified index.

  A `null` throwable returns `-1`. A `null` type returns `-1`. No match in the chain returns `-1`. A negative start index is treated as zero. A start index greater than the number of throwables returns `-1`.

  Parameters:
    `throwable` - the throwable to inspect, may be null
    `type` - the type to search for
    `fromIndex` - the (zero based) index of the starting position, negative treated as zero, larger than chain size returns -1
  Returns:
    the index into the throwable chain, -1 if no match or null input

### printRootCauseStackTrace

    public static void printRootCauseStackTrace(Throwable throwable)

  Prints a compact stack trace for the root cause of a throwable to `System.err`.

  The compact stack trace starts with the root cause and prints stack frames up to the place where it was caught and wrapped. Then it prints the wrapped exception and continues with stack frames until the wrapper exception is caught and wrapped again, etc.

  The method is equivalent to `printStackTrace` for throwables that don't have nested causes.

  Parameters:
    `throwable` - the throwable to output
  Since:
    2.0

### printRootCauseStackTrace

    public static void printRootCauseStackTrace(Throwable throwable,
                                                PrintStream stream)

  Prints a compact stack trace for the root cause of a throwable.

  The compact stack trace starts with the root cause and prints stack frames up to the place where it was caught and wrapped. Then it prints the wrapped exception and continues with stack frames until the wrapper exception is caught and wrapped again, etc.

  The method is equivalent to `printStackTrace` for throwables that don't have nested causes.

  Parameters:
    `throwable` - the throwable to output, may be null
    `stream` - the stream to output to, may not be null
  Throws:
    `IllegalArgumentException` - if the stream is `null`
  Since:
    2.0

### printRootCauseStackTrace

    public static void printRootCauseStackTrace(Throwable throwable,
                                                PrintWriter writer)

  Prints a compact stack trace for the root cause of a throwable.

  The compact stack trace starts with the root cause and prints stack frames up to the place where it was caught and wrapped. Then it prints the wrapped exception and continues with stack frames until the wrapper exception is caught and wrapped again, etc.

  The method is equivalent to `printStackTrace` for throwables that don't have nested causes.

  Parameters:
    `throwable` - the throwable to output, may be null
    `writer` - the writer to output to, may not be null
  Throws:
    `IllegalArgumentException` - if the writer is `null`
  Since:
    2.0

### getRootCauseStackTrace

    public static String[] getRootCauseStackTrace(Throwable throwable)

  Creates a compact stack trace for the root cause of the supplied `Throwable`.

  Parameters:
    `throwable` - the throwable to examine, may be null
  Returns:
    an array of stack trace frames, never null
  Since:
    2.0

### removeCommonFrames

    public static void removeCommonFrames(List causeFrames,
                                          List wrapperFrames)

  Removes common frames from the cause trace given the two stack traces.

  Parameters:
    `causeFrames` - stack trace of a cause throwable
    `wrapperFrames` - stack trace of a wrapper throwable
  Throws:
    `IllegalArgumentException` - if either argument is null
  Since:
    2.0

### getStackTrace

    public static String getStackTrace(Throwable throwable)

  Gets the stack trace from a Throwable as a String.

  Parameters:
    `throwable` - the `Throwable` to be examined
  Returns:
    the stack trace as generated by the exception's `printStackTrace(PrintWriter)` method

### getFullStackTrace

    public static String getFullStackTrace(Throwable throwable)

  A way to get the entire nested stack-trace of an throwable.

  Parameters:
    `throwable` - the `Throwable` to be examined
  Returns:
    the nested stack trace, with the root cause first
  Since:
    2.0

### getStackFrames

    public static String[] getStackFrames(Throwable throwable)

  Captures the stack trace associated with the specified `Throwable` object, decomposing it into a list of stack frames.

  Parameters:
    `throwable` - the `Throwable` to exaamine, may be null
  Returns:
    an array of strings describing each stack frame, never null

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD