Package org.threadly.util

Class ExceptionUtils

  • public class ExceptionUtils
extends java.lang.Object
    Utilities for doing basic operations with exceptions.
    Since:
    1.0.0

    • Constructor Summary

      Constructors 
      Constructor Description
      ExceptionUtils()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void changeStackOverflowCheckFrequency​(int frequencyMillis)
      Update how often the check for StackOverflowErrors being produced in handleException(Throwable).
      static <T extends java.lang.Throwable>
      T      		 getCauseOfType​(java.lang.Throwable rootError, java.lang.Class<? extends T> type)
      Checks to see if the provided error, or any causes in the provided error matching the provided type.
      static java.lang.Throwable getCauseOfTypes​(java.lang.Throwable rootError, java.lang.Iterable<? extends java.lang.Class<? extends java.lang.Throwable>> types)
      Checks to see if the provided error, or any causes in the provided error matching the provided type.
      static ExceptionHandler getExceptionHandler()
      Gets the set ExceptionHandler if one is set, or null if none is set.
      static java.lang.Throwable getRootCause​(java.lang.Throwable throwable)
      Gets the root cause of a provided Throwable.
      static ExceptionHandler getThreadLocalExceptionHandler()
      Gets the thread local ExceptionHandler if one is set, or null if none is set.
      static void handleException​(java.lang.Throwable t)
      This call handles an uncaught throwable.
      static boolean hasCauseOfType​(java.lang.Throwable rootError, java.lang.Class<? extends java.lang.Throwable> type)
      Checks to see if the provided error, or any causes in the provided error match the provided type.
      static boolean hasCauseOfTypes​(java.lang.Throwable rootError, java.lang.Iterable<? extends java.lang.Class<? extends java.lang.Throwable>> types)
      Checks to see if the provided error, or any causes in the provided error match the provided type.
      static java.lang.RuntimeException makeRuntime​(java.lang.Throwable t)
      Makes a rRuntimeException if necessary.
      static java.lang.RuntimeException makeRuntime​(java.lang.Throwable t, boolean suppressWrappedStack)
      Makes a rRuntimeException if necessary.
      static void setDefaultExceptionHandler​(ExceptionHandler exceptionHandler)
      Sets the default ExceptionHandler to be used by all threads.
      static void setInheritableExceptionHandler​(ExceptionHandler exceptionHandler)
      Sets the ExceptionHandler for this thread, and any threads that spawn off of this thread.
      static void setThreadExceptionHandler​(ExceptionHandler exceptionHandler)
      Sets the ExceptionHandler for this thread.
      static java.lang.String stackToString​(java.lang.StackTraceElement[] stack)
      Writes the stack trace array out to a string.
      static java.lang.String stackToString​(java.lang.Throwable t)
      Convert throwable's stack and message into a simple string.
      static void writeStackTo​(java.lang.StackTraceElement[] stack, java.lang.StringBuilder stringBuilder)
      Writes the stack to the provided StringBuilder.
      static void writeStackTo​(java.lang.Throwable t, java.io.Writer w)
      Formats and writes a throwable's stack trace to a provided Writer.
      static void writeStackTo​(java.lang.Throwable t, java.lang.StringBuffer sb)
      Formats and writes a throwable's stack trace to a provided StringBuffer.
      static void writeStackTo​(java.lang.Throwable t, java.lang.StringBuilder sb)
      Formats and writes a throwable's stack trace to a provided StringBuilder.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • ExceptionUtils

        public ExceptionUtils()

    • Method Detail

      • changeStackOverflowCheckFrequency

        public static void changeStackOverflowCheckFrequency​(int frequencyMillis)
        Update how often the check for StackOverflowErrors being produced in handleException(Throwable). It is important that handleException(Throwable) never throws an exception, however due to the nature of StackOverflowError there may be issues in properly reporting the issue. Instead they will be stored internally with a best effort reporting to indicate that they have been occurring (but only one instance per frequency will be reported). By default they are checked every 10 seconds to see if any were thrown. If there was any StackOverflowError they will be provided back to handleException(Throwable) on an async thread (as to provide a fresh / shortened stack).
        Parameters:
        frequencyMillis - Milliseconds between checks for overflow, or negative to disable checks

      • setThreadExceptionHandler

        public static void setThreadExceptionHandler​(ExceptionHandler exceptionHandler)
        Sets the ExceptionHandler for this thread. This exception handler will be called if this thread calls to handleException(Throwable).
        Parameters:
        exceptionHandler - Exception handler instance, or null to remove any handler

      • setInheritableExceptionHandler

        public static void setInheritableExceptionHandler​(ExceptionHandler exceptionHandler)
        Sets the ExceptionHandler for this thread, and any threads that spawn off of this thread. If this thread, or any children threads (that do not override their ExceptionHandler), calls handleException(Throwable), the provided interface will be called.
        Parameters:
        exceptionHandler - Exception handler instance, or null to remove any handler

      • setDefaultExceptionHandler

        public static void setDefaultExceptionHandler​(ExceptionHandler exceptionHandler)
        Sets the default ExceptionHandler to be used by all threads. Assuming a threads local, or inheritable ExceptionHandler has not been set, this default instance will be relied on.
        Parameters:
        exceptionHandler - Exception handler instance, or null to remove any handler

      • getThreadLocalExceptionHandler

        public static ExceptionHandler getThreadLocalExceptionHandler()
        Gets the thread local ExceptionHandler if one is set, or null if none is set. Since getExceptionHandler() prioritizes to the thread local handler, this can be used to get a reference to the current handler before changing the thread local handler to ensure that getExceptionHandler() (and down stream use like handleException(Throwable)) invoke a handler of your choosing. Once done you can then choose to reset the original handler with the one returned from this invocation.
        Returns:
        Thread local ExceptionHandler, or null if none is set

      • getExceptionHandler

        public static ExceptionHandler getExceptionHandler()
        Gets the set ExceptionHandler if one is set, or null if none is set. This prioritizes to the threads locally set handler, with the second priority being an inherited handler, with the final option being the default handler. If none of those are set, a null is returned.
        Returns:
        Handling instance for this thread, or null if none are available

      • handleException

        public static void handleException​(java.lang.Throwable t)
        This call handles an uncaught throwable. If a default uncaught exception handler is set, then that will be called to handle the uncaught exception. If none is set, then the exception will be printed out to standard error.
        Parameters:
        t - throwable to handle

      • makeRuntime

        public static java.lang.RuntimeException makeRuntime​(java.lang.Throwable t)
        Makes a rRuntimeException if necessary. If provided exception is already a RuntimeException then it is just directly returned. If it has to produce a new exception the stack is updated to omit this call.

        If the point of wrapping the stack is not useful in debugging consider providing a true into. makeRuntime(Throwable, boolean).

        Parameters:
        t - Throwable which may or may not be a runtimeException
        Returns:
        a RuntimeException based on provided Throwable

      • makeRuntime

        public static java.lang.RuntimeException makeRuntime​(java.lang.Throwable t,
                                                     boolean suppressWrappedStack)
        Makes a rRuntimeException if necessary. If provided exception is already a RuntimeException then it is just directly returned. If it has to produce a new exception, you can control if a stack is generated by providing a true to suppress the generation (which in java can be fairly expensive). If stack generation is not suppressed (ie false is specified), then the stack will be modified to omit this call.
        Parameters:
        t - Throwable which may or may not be a runtimeException
        suppressWrappedStack - true to avoid generating a stack trace
        Returns:
        A RuntimeException based on provided Throwable

      • getRootCause

        public static java.lang.Throwable getRootCause​(java.lang.Throwable throwable)
        Gets the root cause of a provided Throwable. If there is no cause for the Throwable provided into this function, the original Throwable is returned.

        If a cyclic exception chain is detected this function will return the cause where the cycle end, and thus the returned Throwable will have a cause associated to it (specifically a cause which is one that was seen earlier in the chain). If no cycle exists this will return a Throwable which contains no cause.

        Parameters:
        throwable - starting Throwable
        Returns:
        root cause Throwable

      • getCauseOfTypes

        public static java.lang.Throwable getCauseOfTypes​(java.lang.Throwable rootError,
                                                  java.lang.Iterable<? extends java.lang.Class<? extends java.lang.Throwable>> types)
        Checks to see if the provided error, or any causes in the provided error matching the provided type. This can be useful when trying to truncate an exception chain to only the relevant information. If the goal is only to determine if it exists or not consider using hasCauseOfTypes(Throwable, Iterable). If you are only comparing against one exception type getCauseOfType(Throwable, Class) is a better option (and will return without the need to cast, type thanks to generics).
        Parameters:
        rootError - Throwable to start search from
        types - Types of throwable classes looking to match against
        Returns:
        Throwable that matches one of the provided types, or null if none was found

      • hasCauseOfTypes

        public static boolean hasCauseOfTypes​(java.lang.Throwable rootError,
                                      java.lang.Iterable<? extends java.lang.Class<? extends java.lang.Throwable>> types)
        Checks to see if the provided error, or any causes in the provided error match the provided type. This can be useful when trying to detect conditions where the actual condition may not be the head cause, nor the root cause (but buried somewhere in the chain). If the actual exception is needed consider using getCauseOfTypes(Throwable, Iterable). If you are only comparing against one exception type hasCauseOfType(Throwable, Class) is a better option.
        Parameters:
        rootError - Throwable to start search from
        types - Types of throwable classes looking to match against
        Returns:
        true if a match was found, false if no exception cause matches any provided types

      • getCauseOfType

        public static <T extends java.lang.Throwable> T getCauseOfType​(java.lang.Throwable rootError,
                                                               java.lang.Class<? extends T> type)
        Checks to see if the provided error, or any causes in the provided error matching the provided type. This can be useful when trying to truncate an exception chain to only the relevant information. If the goal is only to determine if it exists or not consider using hasCauseOfType(Throwable, Class).
        Type Parameters:
        T - Type of throwable to return (must equal or be super type of generic class provided)
        Parameters:
        rootError - Throwable to start search from
        type - Type of throwable classes looking to match against
        Returns:
        Throwable that matches one of the provided types, or null if none was found

      • hasCauseOfType

        public static boolean hasCauseOfType​(java.lang.Throwable rootError,
                                     java.lang.Class<? extends java.lang.Throwable> type)
        Checks to see if the provided error, or any causes in the provided error match the provided type. This can be useful when trying to detect conditions where the actual condition may not be the head cause, nor the root cause (but buried somewhere in the chain). If the actual exception is needed consider using getCauseOfType(Throwable, Class).
        Parameters:
        rootError - Throwable to start search from
        type - Type of throwable classes looking to match against
        Returns:
        true if a match was found, false if no exception cause matches any provided types

      • stackToString

        public static java.lang.String stackToString​(java.lang.Throwable t)
        Convert throwable's stack and message into a simple string.
        Parameters:
        t - throwable which contains stack
        Returns:
        string which contains the throwable stack trace

      • writeStackTo

        public static void writeStackTo​(java.lang.Throwable t,
                                java.lang.StringBuilder sb)
        Formats and writes a throwable's stack trace to a provided StringBuilder.
        Parameters:
        t - Throwable which contains stack
        sb - StringBuilder to write output to

      • writeStackTo

        public static void writeStackTo​(java.lang.Throwable t,
                                java.lang.StringBuffer sb)
        Formats and writes a throwable's stack trace to a provided StringBuffer.
        Parameters:
        t - Throwable which contains stack
        sb - StringBuffer to write output to

      • writeStackTo

        public static void writeStackTo​(java.lang.Throwable t,
                                java.io.Writer w)
        Formats and writes a throwable's stack trace to a provided Writer.
        Parameters:
        t - Throwable which contains stack
        w - Writer to write output to

      • stackToString

        public static java.lang.String stackToString​(java.lang.StackTraceElement[] stack)
        Writes the stack trace array out to a string. This produces a stack trace string in a very similar way as the stackToString(Throwable) from a throwable would.
        Parameters:
        stack - Array of stack elements to build the string off of
        Returns:
        String which is the stack in a human readable format

      • writeStackTo

        public static void writeStackTo​(java.lang.StackTraceElement[] stack,
                                java.lang.StringBuilder stringBuilder)
        Writes the stack to the provided StringBuilder. This produces a stack trace string in a very similar way as the writeStackTo(Throwable, StringBuilder) would.
        Parameters:
        stack - Array of stack elements to build the string off of
        stringBuilder - StringBuilder to write the stack out to