Class ExceptionUtil

java.lang.Object
cloud.opencode.base.core.exception.ExceptionUtil
public final class ExceptionUtil extends Object
Exception Utility - Exception chain analysis and handling utilities 异常工具类 - 异常链分析和处理工具

Provides exception chain analysis, stack trace handling and safe execution wrappers.

提供异常链分析、堆栈跟踪处理和安全执行包装器等功能。

Features | 主要功能:

  • Root cause extraction (getRootCause) - 根本原因提取
  • Stack trace to string (getStackTrace) - 堆栈跟踪转字符串
  • Exception chain traversal (getCausalChain) - 异常链遍历
  • Checked exception wrapping (wrapAndThrow) - 受检异常包装
  • Sneaky throw (bypass compilation check) - 静默抛出

Usage Examples | 使用示例:

Throwable root = ExceptionUtil.getRootCause(exception);
String stackTrace = ExceptionUtil.getStackTrace(exception);
List<Throwable> chain = ExceptionUtil.getCausalChain(exception);
ExceptionUtil.sneakyThrow(new IOException("test"));

Security | 安全性:

  • Thread-safe: Yes (stateless) - 线程安全: 是 (无状态)
  • Null-safe: Yes - 空值安全: 是
Since:
JDK 25, opencode-base-core V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • getRootCause

      public static Throwable getRootCause(Throwable throwable)
      Gets the root cause of the exception chain. 获取异常的根本原因。

      Traverses the cause chain and returns the deepest exception (one with no cause).

      遍历异常链，返回最底层的异常（没有 cause 的异常）。

      Parameters:
      throwable - the exception to analyze | 待分析的异常
      Returns:
      the root cause, or null if the input is null | 根本原因，如果输入为 null 则返回 null

    • getStackTrace

      public static String getStackTrace(Throwable throwable)
      Gets the full stack trace as a string. 获取异常的堆栈跟踪字符串。
      Parameters:
      throwable - the exception to convert | 待转换的异常
      Returns:
      the stack trace string, or empty string if input is null | 堆栈跟踪字符串，如果输入为 null 则返回空字符串

    • getCausalChain

      public static List<Throwable> getCausalChain(Throwable throwable)
      Gets the complete causal chain as a list. 获取异常的因果链。

      Returns all exceptions from the given throwable to the root cause.

      返回从当前异常到根本原因的所有异常列表。

      Parameters:
      throwable - the exception to traverse | 待遍历的异常
      Returns:
      unmodifiable list of the causal chain, or empty list if input is null | 异常链的不可修改列表（从当前异常到根本原因），如果输入为 null 则返回空列表

    • unwrap

      public static Throwable unwrap(Throwable throwable)
      Unwraps a nested exception by returning its cause. 解包嵌套异常，返回其原因。

      If the exception wraps another (e.g., RuntimeException wrapping IOException), returns the wrapped exception. If there is no cause, returns the original.

      如果异常是包装类型（如 RuntimeException 包装了 IOException）， 则返回被包装的异常。如果没有 cause，返回原异常。

      Parameters:
      throwable - the exception to unwrap | 待解包的异常
      Returns:
      the cause, or the original exception if no cause exists | 原因异常，如果没有 cause 则返回原异常

    • unwrap

      public static <T extends Throwable> T unwrap(Throwable throwable, Class<T> exceptionType)
      Unwraps an exception of a specific type from the causal chain. 从异常链中解包特定类型的异常。

      Traverses the causal chain and returns the first exception matching the given type.

      遍历异常链，找到并返回指定类型的异常。

      Type Parameters:
      T - the exception type | 异常类型
      Parameters:
      throwable - the exception to search from | 起始异常
      exceptionType - the target exception type to find | 目标异常类型
      Returns:
      the found exception, or null if not found | 找到的异常，如果未找到则返回 null

    • wrapAndThrow

      public static void wrapAndThrow(ExceptionUtil.CheckedRunnable runnable)
      Wraps a checked exception as a runtime exception and throws it. 包装受检异常为运行时异常并抛出。

      Executes the given runnable. If a checked exception is thrown, it is wrapped in an OpenException. RuntimeExceptions pass through unwrapped.

      执行可能抛出受检异常的代码，如果发生受检异常则包装为 OpenException。 RuntimeException 直接抛出不包装。

      Parameters:
      runnable - the code block that may throw checked exceptions | 可能抛出受检异常的代码块
      Throws:
      OpenException - if a checked exception occurs | 如果发生受检异常

    • wrapAndReturn

      public static <T> T wrapAndReturn(ExceptionUtil.CheckedSupplier<T> supplier)
      Wraps a checked exception as a runtime exception and returns the result. 包装受检异常为运行时异常并返回结果。

      Executes the given supplier. If a checked exception is thrown, it is wrapped in an OpenException. RuntimeExceptions pass through unwrapped.

      执行可能抛出受检异常的代码块并返回结果。如果发生受检异常则包装为 OpenException。

      Type Parameters:
      T - the return type | 返回值类型
      Parameters:
      supplier - the code block that may throw checked exceptions | 可能抛出受检异常的代码块
      Returns:
      the execution result | 执行结果
      Throws:
      OpenException - if a checked exception occurs | 如果发生受检异常

    • sneakyThrow

      public static <T extends Throwable> RuntimeException sneakyThrow(Throwable throwable) throws T
      Silently throws a checked exception 静默抛出受检异常

      利用泛型擦除机制，将受检异常作为运行时异常抛出， 而不需要在方法签名中声明。

      警告

      谨慎使用此方法，因为它绕过了编译器的异常检查。 仅在确实需要抛出原始受检异常时使用。
      Type Parameters:
      T - the disguised exception type | 伪装的异常类型
      Parameters:
      throwable - the exception to throw | 要抛出的异常
      Returns:
      never returns, declared only to satisfy return type requirements | 永不返回，仅用于满足返回类型要求
      Throws:
      T - always thrown | 实际抛出的异常

    • contains

      public static boolean contains(Throwable throwable, Class<? extends Throwable> exceptionType)
      Checks if the causal chain contains an exception of the given type. 判断异常链中是否包含指定类型的异常。
      Parameters:
      throwable - the exception to check | 待检查的异常
      exceptionType - the target exception type | 目标异常类型
      Returns:
      true if the chain contains the type | 如果异常链包含该类型则返回 true

    • findCause

      public static <T extends Throwable> Optional<T> findCause(Throwable throwable, Class<T> exceptionType)
      Finds the first exception of the given type in the causal chain. 在异常链中查找第一个指定类型的异常。
      Type Parameters:
      T - the exception type | 异常类型
      Parameters:
      throwable - the exception to search from | 起始异常
      exceptionType - the type to find | 目标异常类型
      Returns:
      Optional containing the found exception, or empty if not found | 包含找到的异常的 Optional，未找到则为空

    • isOrCausedBy

      public static boolean isOrCausedBy(Throwable throwable, Class<? extends Throwable> exceptionType)
      Checks if the throwable itself or any of its causes is of the given type. 检查异常本身或其原因链中是否存在指定类型的异常。

      Semantically equivalent to contains(Throwable, Class) with a more descriptive name.

      语义上等同于 contains(Throwable, Class)，但名称更具描述性。

      Parameters:
      throwable - the exception to check | 待检查的异常
      exceptionType - the type to look for | 目标异常类型
      Returns:
      true if the throwable or any cause matches | 如果异常或任何原因匹配则返回 true

    • getMessage

      public static String getMessage(Throwable throwable)
      Gets the exception message, falling back to the class name if null. 获取异常消息，如果为 null 则返回异常类名。
      Parameters:
      throwable - the exception | 异常
      Returns:
      the message or class name | 异常消息或类名

    • getRootCauseMessage

      public static String getRootCauseMessage(Throwable throwable)
      Gets the root cause message. 获取根本原因的消息。
      Parameters:
      throwable - the exception | 异常
      Returns:
      the root cause message | 根本原因的消息