LifecycleMethodExecutionExceptionHandler API description

Author: Mateusz Pietryga

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/LifecycleMethodExecutionExceptionHandler.java

@@ -1,19 +1,121 @@
 package org.junit.jupiter.api.extension;
 
+import org.apiguardian.api.API;
+
+import static org.apiguardian.api.API.Status.STABLE;
+
+/**
+ * {@code LifecycleMethodExecutionExceptionHandler} defines the API for
+ * {@link Extension Extensions} that wish to handle exceptions thrown during
+ * execution of lifecycle methods (annotated with {@code @BeforeAll},
+ * {@code @BeforeEach}, {@code @AfterEach} and {@code @AfterAll}.
+ *
+ * <p>Common use cases include swallowing an exception if it's anticipated or
+ * rolling back a transaction in certain error scenarios.
+ *
+ * <p>This extension needs to be declared on a class level if class level methods
+ * ({@code @BeforeAll}, {@code @AfterAll}) are to be covered
+ *
+ * <h3>Constructor Requirements</h3>
+ *
+ * <p>Consult the documentation in {@link Extension} for details on constructor
+ * requirements.
+ *
+ * @see TestExecutionExceptionHandler
+ *
+ * @since 5.5
+ */
+@API(status = STABLE, since = "5.5")
 public interface LifecycleMethodExecutionExceptionHandler extends Extension {
 
+    /**
+     * Handle the supplied {@link Throwable throwable}.
+     *
+     * <p>Implementors must perform one of the following.
+     * <ol>
+     * <li>Swallow the supplied {@code throwable}, thereby preventing propagation.</li>
+     * <li>Rethrow the supplied {@code throwable} <em>as is</em>.</li>
+     * <li>Throw a new exception, potentially wrapping the supplied {@code throwable}.</li>
+     * </ol>
+     *
+     * <p>If the supplied {@code throwable} is swallowed, subsequent
+     * {@code LifecycleMethodExecutionExceptionHandler} will not be invoked;
+     * otherwise, the next registered {@code LifecycleMethodExecutionExceptionHandler}
+     * (if there is one) will be invoked with any {@link Throwable} thrown by
+     * this handler.
+     *
+     * @param context the current extension context; never {@code null}
+     * @param throwable the {@code Throwable} to handle; never {@code null}
+     */
     default void handleBeforeAllMethodExecutionException(ExtensionContext context, Throwable throwable) throws Throwable {
         throw throwable;
     }
 
+    /**
+     * Handle the supplied {@link Throwable throwable}.
+     *
+     * <p>Implementors must perform one of the following.
+     * <ol>
+     * <li>Swallow the supplied {@code throwable}, thereby preventing
+     * propagation.</li>
+     * <li>Rethrow the supplied {@code throwable} <em>as is</em>.</li>
+     * <li>Throw a new exception, potentially wrapping the supplied {@code throwable}.</li>
+     * </ol>
+     *
+     * <p>If the supplied {@code throwable} is swallowed, subsequent
+     * {@code LifecycleMethodExecutionExceptionHandler}
+     * will not be invoked; otherwise, the next registered
+     * {@code LifecycleMethodExecutionExceptionHandler} (if there is one)
+     * will be invoked with any {@link Throwable} thrown by this handler.
+     *
+     * @param context the current extension context; never {@code null}
+     * @param throwable the {@code Throwable} to handle; never {@code null}
+     */
     default void handleBeforeEachMethodExecutionException(ExtensionContext context, Throwable throwable) throws Throwable {
         throw throwable;
     }
 
+    /**
+     * Handle the supplied {@link Throwable throwable}.
+     *
+     * <p>Implementors must perform one of the following.
+     * <ol>
+     * <li>Swallow the supplied {@code throwable}, thereby preventing propagation.</li>
+     * <li>Rethrow the supplied {@code throwable} <em>as is</em>.</li>
+     * <li>Throw a new exception, potentially wrapping the supplied {@code throwable}.</li>
+     * </ol>
+     *
+     * <p>If the supplied {@code throwable} is swallowed, subsequent
+     * {@code LifecycleMethodExecutionExceptionHandler} will not be invoked;
+     * otherwise, the next registered {@code LifecycleMethodExecutionExceptionHandler}
+     * (if there is one) will be invoked with any {@link Throwable} thrown by
+     * this handler.
+     *
+     * @param context the current extension context; never {@code null}
+     * @param throwable the {@code Throwable} to handle; never {@code null}
+     */
     default void handleAfterEachMethodExecutionException(ExtensionContext context, Throwable throwable) throws Throwable {
         throw throwable;
     }
 
+    /**
+     * Handle the supplied {@link Throwable throwable}.
+     *
+     * <p>Implementors must perform one of the following.
+     * <ol>
+     * <li>Swallow the supplied {@code throwable}, thereby preventing propagation.</li>
+     * <li>Rethrow the supplied {@code throwable} <em>as is</em>.</li>
+     * <li>Throw a new exception, potentially wrapping the supplied {@code throwable}.</li>
+     * </ol>
+     *
+     * <p>If the supplied {@code throwable} is swallowed, subsequent
+     * {@code LifecycleMethodExecutionExceptionHandler} will not be invoked; otherwise,
+     * the next registered {@code LifecycleMethodExecutionExceptionHandler} (if there
+     * is one) will be invoked with any {@link Throwable} thrown by this handler.
+     *
+     * @param context the current extension context; never {@code null}
+     * @param throwable the {@code Throwable} to handle; never {@code null}
+     */
     default void handleAfterAllMethodExecutionException(ExtensionContext context, Throwable throwable) throws Throwable {
         throw throwable;
     }