Package org.apache.commons.lang.exception

Class ExceptionUtils

  • public class ExceptionUtils
extends java.lang.Object

    Provides utilities for manipulating and examining Throwable objects.

    Since:
    1.0
    Version:
    $Id: ExceptionUtils.java 905837 2010-02-02 23:32:11Z niallp $

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.lang.String[] CAUSE_METHOD_NAMES
      The names of methods commonly used to access a wrapped exception.
      private static java.lang.Object CAUSE_METHOD_NAMES_LOCK  
      private static java.lang.reflect.Method THROWABLE_CAUSE_METHOD
      The Method object for Java 1.4 getCause.
      private static java.lang.reflect.Method THROWABLE_INITCAUSE_METHOD
      The Method object for Java 1.4 initCause.
      (package private) static java.lang.String WRAPPED_MARKER
      Used when printing stack frames to denote the start of a wrapped exception.

    • Constructor Summary

      Constructors 
      Constructor Description
      ExceptionUtils()
      Public constructor allows an instance of ExceptionUtils to be created, although that is not normally necessary.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void addCauseMethodName​(java.lang.String methodName)
      Adds to the list of method names used in the search for Throwable objects.
      static java.lang.Throwable getCause​(java.lang.Throwable throwable)
      Introspects the Throwable to obtain the cause.
      static java.lang.Throwable getCause​(java.lang.Throwable throwable, java.lang.String[] methodNames)
      Introspects the Throwable to obtain the cause.
      private static java.util.ArrayList getCauseMethodNameList()
      Returns CAUSE_METHOD_NAMES as a List.
      private static java.lang.Throwable getCauseUsingFieldName​(java.lang.Throwable throwable, java.lang.String fieldName)
      Finds a Throwable by field name.
      private static java.lang.Throwable getCauseUsingMethodName​(java.lang.Throwable throwable, java.lang.String methodName)
      Finds a Throwable by method name.
      private static java.lang.Throwable getCauseUsingWellKnownTypes​(java.lang.Throwable throwable)
      Finds a Throwable for known types.
      static java.lang.String getFullStackTrace​(java.lang.Throwable throwable)
      A way to get the entire nested stack-trace of an throwable.
      static java.lang.String getMessage​(java.lang.Throwable th)
      Gets a short message summarising the exception.
      static java.lang.Throwable getRootCause​(java.lang.Throwable throwable)
      Introspects the Throwable to obtain the root cause.
      static java.lang.String getRootCauseMessage​(java.lang.Throwable th)
      Gets a short message summarising the root cause exception.
      static java.lang.String[] getRootCauseStackTrace​(java.lang.Throwable throwable)
      Creates a compact stack trace for the root cause of the supplied Throwable.
      (package private) static java.util.List getStackFrameList​(java.lang.Throwable t)
      Produces a List of stack frames - the message is not included.
      (package private) static java.lang.String[] getStackFrames​(java.lang.String stackTrace)
      Returns an array where each element is a line from the argument.
      static java.lang.String[] getStackFrames​(java.lang.Throwable throwable)
      Captures the stack trace associated with the specified Throwable object, decomposing it into a list of stack frames.
      static java.lang.String getStackTrace​(java.lang.Throwable throwable)
      Gets the stack trace from a Throwable as a String.
      static int getThrowableCount​(java.lang.Throwable throwable)
      Counts the number of Throwable objects in the exception chain.
      static java.util.List getThrowableList​(java.lang.Throwable throwable)
      Returns the list of Throwable objects in the exception chain.
      static java.lang.Throwable[] getThrowables​(java.lang.Throwable throwable)
      Returns the list of Throwable objects in the exception chain.
      private static int indexOf​(java.lang.Throwable throwable, java.lang.Class type, int fromIndex, boolean subclass)
      Worker method for the indexOfType methods.
      static int indexOfThrowable​(java.lang.Throwable throwable, java.lang.Class clazz)
      Returns the (zero based) index of the first Throwable that matches the specified class (exactly) in the exception chain.
      static int indexOfThrowable​(java.lang.Throwable throwable, java.lang.Class clazz, 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 int indexOfType​(java.lang.Throwable throwable, java.lang.Class type)
      Returns the (zero based) index of the first Throwable that matches the specified class or subclass in the exception chain.
      static int indexOfType​(java.lang.Throwable throwable, java.lang.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 isCauseMethodName​(java.lang.String methodName)
      Tests if the list of method names used in the search for Throwable objects include the given name.
      static boolean isNestedThrowable​(java.lang.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​(java.lang.Throwable throwable)
      Prints a compact stack trace for the root cause of a throwable to System.err.
      static void printRootCauseStackTrace​(java.lang.Throwable throwable, java.io.PrintStream stream)
      Prints a compact stack trace for the root cause of a throwable.
      static void printRootCauseStackTrace​(java.lang.Throwable throwable, java.io.PrintWriter writer)
      Prints a compact stack trace for the root cause of a throwable.
      static void removeCauseMethodName​(java.lang.String methodName)
      Removes from the list of method names used in the search for Throwable objects.
      static void removeCommonFrames​(java.util.List causeFrames, java.util.List wrapperFrames)
      Removes common frames from the cause trace given the two stack traces.
      static boolean setCause​(java.lang.Throwable target, java.lang.Throwable cause)
      Sets the cause of a Throwable using introspection, allowing source code compatibility between pre-1.4 and post-1.4 Java releases.
      private static java.lang.String[] toArray​(java.util.List list)
      Returns the given list as a String[].

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • WRAPPED_MARKER

        static final java.lang.String WRAPPED_MARKER

        Used when printing stack frames to denote the start of a wrapped exception.

        Package private for accessibility by test suite.

        See Also:
        Constant Field Values

      • CAUSE_METHOD_NAMES_LOCK

        private static final java.lang.Object CAUSE_METHOD_NAMES_LOCK

      • CAUSE_METHOD_NAMES

        private static java.lang.String[] CAUSE_METHOD_NAMES

        The names of methods commonly used to access a wrapped exception.

      • THROWABLE_CAUSE_METHOD

        private static final java.lang.reflect.Method THROWABLE_CAUSE_METHOD

        The Method object for Java 1.4 getCause.

      • THROWABLE_INITCAUSE_METHOD

        private static final java.lang.reflect.Method THROWABLE_INITCAUSE_METHOD

        The Method object for Java 1.4 initCause.

    • Constructor Detail

      • ExceptionUtils

        public ExceptionUtils()

        Public constructor allows an instance of ExceptionUtils to be created, although that is not normally necessary.

    • Method Detail

      • addCauseMethodName

        public static void addCauseMethodName​(java.lang.String methodName)

        Adds to the list of method names used in the search for Throwable objects.

        Parameters:
        methodName - the methodName to add to the list, null and empty strings are ignored
        Since:
        2.0

      • removeCauseMethodName

        public static void removeCauseMethodName​(java.lang.String methodName)

        Removes from the list of method names used in the search for Throwable objects.

        Parameters:
        methodName - the methodName to remove from the list, null and empty strings are ignored
        Since:
        2.1

      • setCause

        public static boolean setCause​(java.lang.Throwable target,
                               java.lang.Throwable cause)

        Sets the cause of a Throwable using introspection, allowing source code compatibility between pre-1.4 and post-1.4 Java releases.

        The typical use of this method is inside a constructor as in the following example:

         import org.apache.commons.lang.exception.ExceptionUtils;
  
 public class MyException extends Exception {
  
    public MyException(String msg) {
       super(msg);
    }

    public MyException(String msg, Throwable cause) {
       super(msg);
       ExceptionUtils.setCause(this, cause);
    }
 }
        Parameters:
        target - the target Throwable
        cause - the Throwable to set in the target
        Returns:
        a true if the target has been modified
        Since:
        2.2

      • toArray

        private static java.lang.String[] toArray​(java.util.List list)
        Returns the given list as a String[].
        Parameters:
        list - a list to transform.
        Returns:
        the given list as a String[].

      • isCauseMethodName

        public static boolean isCauseMethodName​(java.lang.String methodName)

        Tests if the list of method names used in the search for Throwable objects include the given name.

        Parameters:
        methodName - the methodName to search in the list.
        Returns:
        if the list of method names used in the search for Throwable objects include the given name.
        Since:
        2.1

      • getCause

        public static java.lang.Throwable getCause​(java.lang.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
        Since:
        1.0

      • getCause

        public static java.lang.Throwable getCause​(java.lang.Throwable throwable,
                                           java.lang.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
        Since:
        1.0

      • getRootCause

        public static java.lang.Throwable getRootCause​(java.lang.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.

        From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. If the throwable parameter has a cause of itself, then null will be returned. If the throwable parameter cause chain loops, the last element in the chain before the loop is returned.

        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

      • getCauseUsingWellKnownTypes

        private static java.lang.Throwable getCauseUsingWellKnownTypes​(java.lang.Throwable throwable)

        Finds a Throwable for known types.

        Uses instanceof checks to examine the exception, looking for well known types which could contain chained or wrapped exceptions.

        Parameters:
        throwable - the exception to examine
        Returns:
        the wrapped exception, or null if not found

      • getCauseUsingMethodName

        private static java.lang.Throwable getCauseUsingMethodName​(java.lang.Throwable throwable,
                                                           java.lang.String methodName)

        Finds a Throwable by method name.

        Parameters:
        throwable - the exception to examine
        methodName - the name of the method to find and invoke
        Returns:
        the wrapped exception, or null if not found

      • getCauseUsingFieldName

        private static java.lang.Throwable getCauseUsingFieldName​(java.lang.Throwable throwable,
                                                          java.lang.String fieldName)

        Finds a Throwable by field name.

        Parameters:
        throwable - the exception to examine
        fieldName - the name of the attribute to examine
        Returns:
        the wrapped exception, or null if not found

      • 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​(java.lang.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​(java.lang.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.

        From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is processed until the end is reached, or until the next item in the chain is already in the result set.

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

      • getThrowables

        public static java.lang.Throwable[] getThrowables​(java.lang.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 of size zero.

        From version 2.2, this method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is processed until the end is reached, or until the next item in the chain is already in the result set.

        Parameters:
        throwable - the throwable to inspect, may be null
        Returns:
        the array of throwables, never null
        See Also:
        getThrowableList(Throwable)

      • getThrowableList

        public static java.util.List getThrowableList​(java.lang.Throwable throwable)

        Returns the list of Throwable objects in the exception chain.

        A throwable without cause will return a list containing one element - the input throwable. A throwable with one cause will return a list containing two elements. - the input throwable and the cause throwable. A null throwable will return a list of size zero.

        This method handles recursive cause structures that might otherwise cause infinite loops. The cause chain is processed until the end is reached, or until the next item in the chain is already in the result set.

        Parameters:
        throwable - the throwable to inspect, may be null
        Returns:
        the list of throwables, never null
        Since:
        Commons Lang 2.2

      • indexOfThrowable

        public static int indexOfThrowable​(java.lang.Throwable throwable,
                                   java.lang.Class clazz)

        Returns the (zero based) index of the first Throwable that matches the specified class (exactly) in the exception chain. Subclasses of the specified class do not match - see indexOfType(Throwable, Class) for the opposite.

        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
        clazz - the class to search for, subclasses do not match, null returns -1
        Returns:
        the index into the throwable chain, -1 if no match or null input

      • indexOfThrowable

        public static int indexOfThrowable​(java.lang.Throwable throwable,
                                   java.lang.Class clazz,
                                   int fromIndex)

        Returns the (zero based) index of the first Throwable that matches the specified type in the exception chain from a specified index. Subclasses of the specified class do not match - see indexOfType(Throwable, Class, int) for the opposite.

        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
        clazz - the class to search for, subclasses do not match, null returns -1
        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

      • indexOfType

        public static int indexOfType​(java.lang.Throwable throwable,
                              java.lang.Class type)

        Returns the (zero based) index of the first Throwable that matches the specified class or subclass in the exception chain. Subclasses of the specified class do match - see indexOfThrowable(Throwable, Class) for the opposite.

        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, subclasses match, null returns -1
        Returns:
        the index into the throwable chain, -1 if no match or null input
        Since:
        2.1

      • indexOfType

        public static int indexOfType​(java.lang.Throwable throwable,
                              java.lang.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. Subclasses of the specified class do match - see indexOfThrowable(Throwable, Class) for the opposite.

        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, subclasses match, null returns -1
        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
        Since:
        2.1

      • indexOf

        private static int indexOf​(java.lang.Throwable throwable,
                           java.lang.Class type,
                           int fromIndex,
                           boolean subclass)

        Worker method for the indexOfType methods.

        Parameters:
        throwable - the throwable to inspect, may be null
        type - the type to search for, subclasses match, null returns -1
        fromIndex - the (zero based) index of the starting position, negative treated as zero, larger than chain size returns -1
        subclass - if true, compares with Class.isAssignableFrom(Class), otherwise compares using references
        Returns:
        index of the type within throwables nested withing the specified throwable

      • printRootCauseStackTrace

        public static void printRootCauseStackTrace​(java.lang.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 output of this method is consistent across JDK versions. Note that this is the opposite order to the JDK1.4 display.

        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​(java.lang.Throwable throwable,
                                            java.io.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 output of this method is consistent across JDK versions. Note that this is the opposite order to the JDK1.4 display.

        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:
        java.lang.IllegalArgumentException - if the stream is null
        Since:
        2.0

      • printRootCauseStackTrace

        public static void printRootCauseStackTrace​(java.lang.Throwable throwable,
                                            java.io.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 output of this method is consistent across JDK versions. Note that this is the opposite order to the JDK1.4 display.

        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:
        java.lang.IllegalArgumentException - if the writer is null
        Since:
        2.0

      • getRootCauseStackTrace

        public static java.lang.String[] getRootCauseStackTrace​(java.lang.Throwable throwable)

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

        The output of this method is consistent across JDK versions. It consists of the root exception followed by each of its wrapping exceptions separated by '[wrapped]'. Note that this is the opposite order to the JDK1.4 display.

        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​(java.util.List causeFrames,
                                      java.util.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:
        java.lang.IllegalArgumentException - if either argument is null
        Since:
        2.0

      • getFullStackTrace

        public static java.lang.String getFullStackTrace​(java.lang.Throwable throwable)

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

        The result of this method is highly dependent on the JDK version and whether the exceptions override printStackTrace or not.

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

      • getStackTrace

        public static java.lang.String getStackTrace​(java.lang.Throwable throwable)

        Gets the stack trace from a Throwable as a String.

        The result of this method vary by JDK version as this method uses Throwable.printStackTrace(java.io.PrintWriter). On JDK1.3 and earlier, the cause exception will not be shown unless the specified throwable alters printStackTrace.

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

      • getStackFrames

        public static java.lang.String[] getStackFrames​(java.lang.Throwable throwable)

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

        The result of this method vary by JDK version as this method uses Throwable.printStackTrace(java.io.PrintWriter). On JDK1.3 and earlier, the cause exception will not be shown unless the specified throwable alters printStackTrace.

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

      • getStackFrames

        static java.lang.String[] getStackFrames​(java.lang.String stackTrace)

        Returns an array where each element is a line from the argument.

        The end of line is determined by the value of SystemUtils.LINE_SEPARATOR.

        Functionality shared between the getStackFrames(Throwable) methods of this and the NestableDelegate classes.

        Parameters:
        stackTrace - a stack trace String
        Returns:
        an array where each element is a line from the argument

      • getStackFrameList

        static java.util.List getStackFrameList​(java.lang.Throwable t)

        Produces a List of stack frames - the message is not included. Only the trace of the specified exception is returned, any caused by trace is stripped.

        This works in most cases - it will only fail if the exception message contains a line that starts with: "   at".

        Parameters:
        t - is any throwable
        Returns:
        List of stack frames

      • getMessage

        public static java.lang.String getMessage​(java.lang.Throwable th)
        Gets a short message summarising the exception.

        The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}

        Parameters:
        th - the throwable to get a message for, null returns empty string
        Returns:
        the message, non-null
        Since:
        Commons Lang 2.2

      • getRootCauseMessage

        public static java.lang.String getRootCauseMessage​(java.lang.Throwable th)
        Gets a short message summarising the root cause exception.

        The message returned is of the form {ClassNameWithoutPackage}: {ThrowableMessage}

        Parameters:
        th - the throwable to get a message for, null returns empty string
        Returns:
        the message, non-null
        Since:
        Commons Lang 2.2