org.apache.paimon.utils

Class ExceptionUtils

java.lang.Object

org.apache.paimon.utils.ExceptionUtils

public final class ExceptionUtils
extends Object

A collection of utility functions for dealing with exceptions and exception workflows.

Field Summary

Fields

Modifier and Type	Field and Description
static String	STRINGIFIED_NULL_EXCEPTION The stringified representation of a null exception reference.

Method Summary

Modifier and Type	Method and Description
static <T extends Throwable> void	assertThrowable(Throwable throwable, Class<T> searchType) The same as findThrowable(Throwable, Class), but rethrows original exception if the expected exception was not found.
static <T extends Throwable> void	assertThrowableWithMessage(Throwable throwable, String searchMessage) The same as findThrowableWithMessage(Throwable, String), but rethrows original exception if the expected exception was not found.
static void	checkInterrupted(Throwable e) Checks whether the given exception is a InterruptedException and sets the interrupted flag accordingly.
static <T extends Throwable> Optional<T>	findThrowable(Throwable throwable, Class<T> searchType) Checks whether a throwable chain contains a specific type of exception and returns it.
static Optional<Throwable>	findThrowable(Throwable throwable, java.util.function.Predicate<Throwable> predicate) Checks whether a throwable chain contains an exception matching a predicate and returns it.
static Optional<Throwable>	findThrowableWithMessage(Throwable throwable, String searchMessage) Checks whether a throwable chain contains a specific error message and returns the corresponding throwable.
static <T extends Throwable> T	firstOrSuppressed(T newException, T previous) Adds a new exception as a suppressed exception to a prior exception, or returns the new exception, if no prior exception exists.
static boolean	isDirectOutOfMemoryError(Throwable t) Checks whether the given exception indicates a JVM direct out-of-memory error.
static boolean	isHeapSpaceOutOfMemoryError(Throwable t)
static boolean	isJvmFatalError(Throwable t) Checks whether the given exception indicates a situation that may leave the JVM in a corrupted state, meaning a state where continued normal operation can only be guaranteed via clean process restart.
static boolean	isJvmFatalOrOutOfMemoryError(Throwable t) Checks whether the given exception indicates a situation that may leave the JVM in a corrupted state, or an out-of-memory error.
static boolean	isMetaspaceOutOfMemoryError(Throwable t) Checks whether the given exception indicates a JVM metaspace out-of-memory error.
static void	rethrow(Throwable t) Throws the given Throwable in scenarios where the signatures do not allow you to throw an arbitrary Throwable.
static void	rethrow(Throwable t, String parentMessage) Throws the given Throwable in scenarios where the signatures do not allow you to throw an arbitrary Throwable.
static void	rethrowException(Throwable t) Throws the given Throwable in scenarios where the signatures do allow to throw a Exception.
static void	rethrowException(Throwable t, String parentMessage) Throws the given Throwable in scenarios where the signatures do allow to throw a Exception.
static void	rethrowIfFatalError(Throwable t) Rethrows the given Throwable, if it represents an error that is fatal to the JVM.
static void	rethrowIfFatalErrorOrOOM(Throwable t) Rethrows the given Throwable, if it represents an error that is fatal to the JVM or an out-of-memory error.
static void	rethrowIOException(Throwable t) Re-throws the given Throwable in scenarios where the signatures allows only IOExceptions (and RuntimeException and Error).
static String	stringifyException(Throwable e) Makes a string representation of the exception's stack trace, or "(null)", if the exception is null.
static Throwable	stripCompletionException(Throwable throwable) Unpacks an CompletionException and returns its cause.
static Throwable	stripException(Throwable throwableToStrip, Class<? extends Throwable> typeToStrip) Unpacks an specified exception and returns its cause.
static Throwable	stripExecutionException(Throwable throwable) Unpacks an ExecutionException and returns its cause.
static void	throwMultiException(List<Exception> exceptions)
static void	tryEnrichOutOfMemoryError(Throwable root, String jvmMetaspaceOomNewErrorMessage, String jvmDirectOomNewErrorMessage, String jvmHeapSpaceOomNewErrorMessage) Tries to enrich OutOfMemoryErrors being part of the passed root Throwable's cause tree.
static void	tryRethrowException(Exception e) Tries to throw the given exception if not null.
static void	tryRethrowIOException(Throwable t) Tries to throw the given Throwable in scenarios where the signatures allows only IOExceptions (and RuntimeException and Error).
static void	updateDetailMessage(Throwable root, java.util.function.Function<Throwable,String> throwableToMessage) Updates error messages of Throwables appearing in the cause tree of the passed root Throwable.

Methods inherited from class java.lang.Object

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

Field Detail

STRINGIFIED_NULL_EXCEPTION

public static final String STRINGIFIED_NULL_EXCEPTION

The stringified representation of a null exception reference.

See Also:

Constant Field Values

Method Detail

stringifyException

public static String stringifyException(Throwable e)

Makes a string representation of the exception's stack trace, or "(null)", if the exception is null.

This method makes a best effort and never fails.

Parameters:

e - The exception to stringify.

Returns:

A string with exception name and call stack.

isJvmFatalError

public static boolean isJvmFatalError(Throwable t)

Checks whether the given exception indicates a situation that may leave the JVM in a corrupted state, meaning a state where continued normal operation can only be guaranteed via clean process restart.

Currently considered fatal exceptions are Virtual Machine errors indicating that the JVM is corrupted, like InternalError, UnknownError, and ZipError (a special case of InternalError). The ThreadDeath exception is also treated as a fatal error, because when a thread is forcefully stopped, there is a high chance that parts of the system are in an inconsistent state.

Parameters:

t - The exception to check.

Returns:

True, if the exception is considered fatal to the JVM, false otherwise.

isJvmFatalOrOutOfMemoryError

public static boolean isJvmFatalOrOutOfMemoryError(Throwable t)

Checks whether the given exception indicates a situation that may leave the JVM in a corrupted state, or an out-of-memory error.

See isJvmFatalError(Throwable) for a list of fatal JVM errors. This method additionally classifies the OutOfMemoryError as fatal, because it may occur in any thread (not the one that allocated the majority of the memory) and thus is often not recoverable by destroying the particular thread that threw the exception.

Parameters:

t - The exception to check.

Returns:

True, if the exception is fatal to the JVM or and OutOfMemoryError, false otherwise.

tryEnrichOutOfMemoryError

public static void tryEnrichOutOfMemoryError(@Nullable
                                             Throwable root,
                                             @Nullable
                                             String jvmMetaspaceOomNewErrorMessage,
                                             @Nullable
                                             String jvmDirectOomNewErrorMessage,
                                             @Nullable
                                             String jvmHeapSpaceOomNewErrorMessage)

Tries to enrich OutOfMemoryErrors being part of the passed root Throwable's cause tree.

This method improves error messages for direct and metaspace OutOfMemoryError. It adds description about the possible causes and ways of resolution.

Parameters:

root - The Throwable of which the cause tree shall be traversed.

jvmMetaspaceOomNewErrorMessage - The message being used for JVM metaspace-related OutOfMemoryErrors. Passing null will disable handling this class of error.

jvmDirectOomNewErrorMessage - The message being used for direct memory-related OutOfMemoryErrors. Passing null will disable handling this class of error.

jvmHeapSpaceOomNewErrorMessage - The message being used for Heap space-related OutOfMemoryErrors. Passing null will disable handling this class of error.

updateDetailMessage

public static void updateDetailMessage(@Nullable
                                       Throwable root,
                                       @Nullable
                                       java.util.function.Function<Throwable,String> throwableToMessage)

Updates error messages of Throwables appearing in the cause tree of the passed root Throwable. The passed Function is applied on each Throwable of the cause tree. Returning a String will cause the detailMessage of the corresponding Throwable to be updated. Returning null, instead, won't trigger any detailMessage update on that Throwable.

Parameters:

root - The Throwable whose cause tree shall be traversed.

throwableToMessage - The Function based on which the new messages are generated. The function implementation should return the new message. Returning null, in contrast, will result in not updating the message for the corresponding Throwable.

isMetaspaceOutOfMemoryError

public static boolean isMetaspaceOutOfMemoryError(@Nullable
                                                  Throwable t)

Checks whether the given exception indicates a JVM metaspace out-of-memory error.

Parameters:

t - The exception to check.

Returns:

True, if the exception is the metaspace OutOfMemoryError, false otherwise.

isDirectOutOfMemoryError

public static boolean isDirectOutOfMemoryError(@Nullable
                                               Throwable t)

Checks whether the given exception indicates a JVM direct out-of-memory error.

Parameters:

t - The exception to check.

Returns:

True, if the exception is the direct OutOfMemoryError, false otherwise.

isHeapSpaceOutOfMemoryError

public static boolean isHeapSpaceOutOfMemoryError(@Nullable
                                                  Throwable t)

rethrowIfFatalError

public static void rethrowIfFatalError(Throwable t)

Rethrows the given Throwable, if it represents an error that is fatal to the JVM. See isJvmFatalError(Throwable) for a definition of fatal errors.

Parameters:

t - The Throwable to check and rethrow.

rethrowIfFatalErrorOrOOM

public static void rethrowIfFatalErrorOrOOM(Throwable t)

Rethrows the given Throwable, if it represents an error that is fatal to the JVM or an out-of-memory error. See isJvmFatalError(Throwable) for a definition of fatal errors.

Parameters:

t - The Throwable to check and rethrow.

firstOrSuppressed

public static <T extends Throwable> T firstOrSuppressed(T newException,
                                                        @Nullable
                                                        T previous)

Adds a new exception as a suppressed exception to a prior exception, or returns the new exception, if no prior exception exists.

 public void closeAllThings() throws Exception {
     Exception ex = null;
     try {
         component.shutdown();
     } catch (Exception e) {
         ex = firstOrSuppressed(e, ex);
     }
     try {
         anotherComponent.stop();
     } catch (Exception e) {
         ex = firstOrSuppressed(e, ex);
     }
     try {
         lastComponent.shutdown();
     } catch (Exception e) {
         ex = firstOrSuppressed(e, ex);
     }

     if (ex != null) {
         throw ex;
     }
 }
 

Parameters:

newException - The newly occurred exception

previous - The previously occurred exception, possibly null.

Returns:

The new exception, if no previous exception exists, or the previous exception with the new exception in the list of suppressed exceptions.

rethrow

public static void rethrow(Throwable t)

Throws the given Throwable in scenarios where the signatures do not allow you to throw an arbitrary Throwable. Errors and RuntimeExceptions are thrown directly, other exceptions are packed into runtime exceptions

Parameters:

t - The throwable to be thrown.

rethrow

public static void rethrow(Throwable t,
                           String parentMessage)

Throws the given Throwable in scenarios where the signatures do not allow you to throw an arbitrary Throwable. Errors and RuntimeExceptions are thrown directly, other exceptions are packed into a parent RuntimeException.

Parameters:

t - The throwable to be thrown.

parentMessage - The message for the parent RuntimeException, if one is needed.

rethrowException

public static void rethrowException(Throwable t,
                                    String parentMessage)
                             throws Exception

Throws the given Throwable in scenarios where the signatures do allow to throw a Exception. Errors and Exceptions are thrown directly, other "exotic" subclasses of Throwable are wrapped in an Exception.

Parameters:

t - The throwable to be thrown.

parentMessage - The message for the parent Exception, if one is needed.

Throws:

Exception

rethrowException

public static void rethrowException(Throwable t)
                             throws Exception

Throws the given Throwable in scenarios where the signatures do allow to throw a Exception. Errors and Exceptions are thrown directly, other "exotic" subclasses of Throwable are wrapped in an Exception.

Parameters:

t - The throwable to be thrown.

Throws:

Exception

tryRethrowException

public static void tryRethrowException(@Nullable
                                       Exception e)
                                throws Exception

Tries to throw the given exception if not null.

Parameters:

e - exception to throw if not null.

Throws:

Exception

tryRethrowIOException

public static void tryRethrowIOException(Throwable t)
                                  throws IOException

Tries to throw the given Throwable in scenarios where the signatures allows only IOExceptions (and RuntimeException and Error). Throws this exception directly, if it is an IOException, a RuntimeException, or an Error. Otherwise does nothing.

Parameters:

t - The Throwable to be thrown.

Throws:

IOException

rethrowIOException

public static void rethrowIOException(Throwable t)
                               throws IOException

Re-throws the given Throwable in scenarios where the signatures allows only IOExceptions (and RuntimeException and Error).

Throws this exception directly, if it is an IOException, a RuntimeException, or an Error. Otherwise it wraps it in an IOException and throws it.

Parameters:

t - The Throwable to be thrown.

Throws:

IOException

findThrowable

public static <T extends Throwable> Optional<T> findThrowable(Throwable throwable,
                                                              Class<T> searchType)

Checks whether a throwable chain contains a specific type of exception and returns it.

Parameters:

throwable - the throwable chain to check.

searchType - the type of exception to search for in the chain.

Returns:

Optional throwable of the requested type if available, otherwise empty

assertThrowable

public static <T extends Throwable> void assertThrowable(Throwable throwable,
                                                         Class<T> searchType)
                                                  throws T extends Throwable

The same as findThrowable(Throwable, Class), but rethrows original exception if the expected exception was not found.

Throws:

T extends Throwable

findThrowable

public static Optional<Throwable> findThrowable(Throwable throwable,
                                                java.util.function.Predicate<Throwable> predicate)

Checks whether a throwable chain contains an exception matching a predicate and returns it.

Parameters:

throwable - the throwable chain to check.

predicate - the predicate of the exception to search for in the chain.

Returns:

Optional throwable of the requested type if available, otherwise empty

findThrowableWithMessage

public static Optional<Throwable> findThrowableWithMessage(Throwable throwable,
                                                           String searchMessage)

Checks whether a throwable chain contains a specific error message and returns the corresponding throwable.

Parameters:

throwable - the throwable chain to check.

searchMessage - the error message to search for in the chain.

Returns:

Optional throwable containing the search message if available, otherwise empty

assertThrowableWithMessage

public static <T extends Throwable> void assertThrowableWithMessage(Throwable throwable,
                                                                    String searchMessage)
                                                             throws T extends Throwable

The same as findThrowableWithMessage(Throwable, String), but rethrows original exception if the expected exception was not found.

Throws:

T extends Throwable

stripExecutionException

public static Throwable stripExecutionException(Throwable throwable)

Unpacks an ExecutionException and returns its cause. Otherwise the given Throwable is returned.

Parameters:

throwable - to unpack if it is an ExecutionException

Returns:

Cause of ExecutionException or given Throwable

stripCompletionException

public static Throwable stripCompletionException(Throwable throwable)

Unpacks an CompletionException and returns its cause. Otherwise the given Throwable is returned.

Parameters:

throwable - to unpack if it is an CompletionException

Returns:

Cause of CompletionException or given Throwable

stripException

public static Throwable stripException(Throwable throwableToStrip,
                                       Class<? extends Throwable> typeToStrip)

Unpacks an specified exception and returns its cause. Otherwise the given Throwable is returned.

Parameters:

throwableToStrip - to strip

typeToStrip - type to strip

Returns:

Unpacked cause or given Throwable if not packed

checkInterrupted

public static void checkInterrupted(Throwable e)

Checks whether the given exception is a InterruptedException and sets the interrupted flag accordingly.

Parameters:

e - to check whether it is an InterruptedException

throwMultiException

public static void throwMultiException(List<Exception> exceptions)
                                throws Exception

Throws:

Exception