ExceptionUtils (Flink : 1.16-SNAPSHOT API)

java.lang.Object
- org.apache.flink.util.ExceptionUtils

```
@Internal
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.

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

Method Summary

All Methods Static Methods Concrete Methods
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`	`assertThrowable(T throwable, java.util.function.Predicate<Throwable> predicate)` The same as `findThrowable(Throwable, Predicate)`, 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>`	`findSerializedThrowable(Throwable throwable, Class<T> searchType, ClassLoader classLoader)` Checks whether a throwable chain contains a specific type of exception and returns it.
`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 <T extends Throwable> Optional<T>`	`findThrowableSerializedAware(Throwable throwable, Class<T> searchType, ClassLoader classLoader)` Checks whether a throwable chain contains a specific type of exception 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`	`logExceptionIfExcepted(Throwable e, org.slf4j.Logger log)` Log the given exception in debug level if it is a `FlinkExpectedException`.
`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 Throwable`	`returnExceptionIfUnexpected(Throwable e)` Return the given exception if it is not a `FlinkExpectedException`.
`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`	`suppressExceptions(RunnableWithException action)`
`static void`	`tryDeserializeAndThrow(Throwable throwable, ClassLoader classLoader)` Tries to find a `SerializedThrowable` as the cause of the given throwable and throws its deserialized value.
`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
  - findSerializedThrowable
```
public static <T extends Throwable> Optional<T> findSerializedThrowable(Throwable throwable,
                                                                        Class<T> searchType,
                                                                        ClassLoader classLoader)
```
    Checks whether a throwable chain contains a specific type of exception and returns it. It deserializes any SerializedThrowable that are found using the provided ClassLoader.
    
    Parameters:
    
    throwable - the throwable chain to check.
    
    searchType - the type of exception to search for in the chain.
    
    classLoader - to use for deserialization.
    
    Returns:
    
    Optional throwable of the requested type if available, otherwise empty
  - 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
  - findThrowableSerializedAware
```
public static <T extends Throwable> Optional<T> findThrowableSerializedAware(Throwable throwable,
                                                                             Class<T> searchType,
                                                                             ClassLoader classLoader)
```
    Checks whether a throwable chain contains a specific type of exception and returns it. This method handles SerializedThrowables in the chain and deserializes them with the given ClassLoader.
    SerializedThrowables are often used when exceptions might come from dynamically loaded code and be transported over RPC / HTTP for better error reporting. The receiving processes or threads might not have the dynamically loaded code available.
    
    Parameters:
    
    throwable - the throwable chain to check.
    
    searchType - the type of exception to search for in the chain.
    
    classLoader - the ClassLoader to use when encountering a SerializedThrowable.
    
    Returns:
    
    Optional throwable of the requested type if available, otherwise empty
  - 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
  - assertThrowable
```
public static <T extends Throwable> void assertThrowable(T throwable,
                                                         java.util.function.Predicate<Throwable> predicate)
                                                  throws T extends Throwable
```
    The same as findThrowable(Throwable, Predicate), but rethrows original exception if the expected exception was not found.
    
    Throws:
    
    T extends Throwable
  - 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
  - tryDeserializeAndThrow
```
public static void tryDeserializeAndThrow(Throwable throwable,
                                          ClassLoader classLoader)
                                   throws Throwable
```
    Tries to find a SerializedThrowable as the cause of the given throwable and throws its deserialized value. If there is no such throwable, then the original throwable is thrown.
    
    Parameters:
    
    throwable - to check for a SerializedThrowable
    
    classLoader - to be used for the deserialization of the SerializedThrowable
    
    Throws:
    
    Throwable - either the deserialized throwable or the given throwable
  - 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
  - returnExceptionIfUnexpected
```
public static Throwable returnExceptionIfUnexpected(Throwable e)
```
    Return the given exception if it is not a FlinkExpectedException.
    
    Parameters:
    
    e - the given exception
    
    Returns:
    
    the given exception if it is not a FlinkExpectedException
  - logExceptionIfExcepted
```
public static void logExceptionIfExcepted(Throwable e,
                                          org.slf4j.Logger log)
```
    Log the given exception in debug level if it is a FlinkExpectedException.
    
    Parameters:
    
    e - the given exception
    
    log - logger
  - suppressExceptions
```
public static void suppressExceptions(RunnableWithException action)
```

Back to Flink Website

Class ExceptionUtils

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

STRINGIFIED_NULL_EXCEPTION

Method Detail

stringifyException

isJvmFatalError

isJvmFatalOrOutOfMemoryError

tryEnrichOutOfMemoryError

updateDetailMessage

isMetaspaceOutOfMemoryError

isDirectOutOfMemoryError

isHeapSpaceOutOfMemoryError

rethrowIfFatalError

rethrowIfFatalErrorOrOOM

firstOrSuppressed

rethrow

rethrow

rethrowException

rethrowException

tryRethrowException

tryRethrowIOException

rethrowIOException

findSerializedThrowable

findThrowable

assertThrowable

findThrowableSerializedAware

findThrowable

assertThrowable

findThrowableWithMessage

assertThrowableWithMessage

stripExecutionException

stripCompletionException

stripException

tryDeserializeAndThrow

checkInterrupted

returnExceptionIfUnexpected

logExceptionIfExcepted

suppressExceptions

Back to Flink Website