org.threadly.util

Class ExceptionUtils

java.lang.Object

org.threadly.util.ExceptionUtils

public class ExceptionUtils
extends java.lang.Object

Utilities for doing basic operations with exceptions.

Since:

1.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ExceptionUtils.TransformedException Exception which is constructed from makeRuntime(Throwable) when the exception was not a runtime exception.
static class	ExceptionUtils.TransformedSuppressedStackException Exception which is constructed from makeRuntime(Throwable, boolean) when the exception was not a runtime exception, and stack is being suppressed.

Constructor Summary

Constructors

Constructor and Description
ExceptionUtils()

Method Summary

Modifier and Type	Method and 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.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.
static void	writeStackTo(java.lang.Throwable t, java.io.Writer w) Formats and writes a throwable's stack trace to a provided Writer.

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