Package org.apache.flink.util

Class ExceptionUtils

  • @Internal
public final class ExceptionUtils
extends Object
    A collection of utility functions for dealing with exceptions and exception workflows.

    • 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
                                       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

      • 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,
                                                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

      • 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

      • 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​(org.apache.flink.util.function.RunnableWithException action)