/*
 * Copyright 2015-2020 the original author or authors.
 *
 * All rights reserved. This program and the accompanying materials are
 * made available under the terms of the Eclipse Public License v2.0 which
 * accompanies this distribution and is available at
 *
 * https://www.eclipse.org/legal/epl-v20.html
 */

package org.junit.jupiter.api.extension;

import static org.apiguardian.api.API.Status.EXPERIMENTAL;

import org.apiguardian.api.API;

LifecycleMethodExecutionExceptionHandler defines the API for Extensions that wish to handle exceptions thrown during the execution of @BeforeAll, @BeforeEach, @AfterEach, and @AfterAll lifecycle methods. 
Common use cases include swallowing an exception if it's anticipated,
logging errors, or rolling back a transaction in certain error scenarios.
Implementations of this extension API must be registered at the class level if exceptions thrown from @BeforeAll or @AfterAll methods are to be handled. When registered at the test level, only exceptions thrown from @BeforeEach or @AfterEach methods will be handled. 
Constructor Requirements
Consult the documentation in Extension for details on constructor requirements. 
Implementation Guidelines
An implementation of an exception handler method defined in this API must
perform one of the following.

Rethrow the supplied Throwable as is, which is the default implementation.
Swallow the supplied Throwable, thereby preventing propagation.
Throw a new exception, potentially wrapping the supplied Throwable.

If the supplied Throwable is swallowed by a handler method, subsequent handler methods for the same lifecycle will not be invoked; otherwise, the corresponding handler method of the next registered LifecycleMethodExecutionExceptionHandler (if there is one) will be invoked with any Throwable thrown by the previous handler. 
See Also:
TestExecutionExceptionHandler
Since:
5.5/**
 * {@code LifecycleMethodExecutionExceptionHandler} defines the API for
 * {@link Extension Extensions} that wish to handle exceptions thrown during
 * the execution of {@code @BeforeAll}, {@code @BeforeEach}, {@code @AfterEach},
 * and {@code @AfterAll} lifecycle methods.
 *
 * <p>Common use cases include swallowing an exception if it's anticipated,
 * logging errors, or rolling back a transaction in certain error scenarios.
 *
 * <p>Implementations of this extension API must be registered at the class level
 * if exceptions thrown from {@code @BeforeAll} or {@code @AfterAll} methods are
 * to be handled. When registered at the test level, only exceptions thrown from
 * {@code @BeforeEach} or {@code @AfterEach} methods will be handled.
 *
 * <h3>Constructor Requirements</h3>
 *
 * <p>Consult the documentation in {@link Extension} for details on constructor
 * requirements.
 *
 * <h3 id="implementation-guidelines">Implementation Guidelines</h3>
 *
 * <p>An implementation of an exception handler method defined in this API must
 * perform one of the following.
 *
 * <ol>
 * <li>Rethrow the supplied {@code Throwable} <em>as is</em>, which is the default implementation.</li>
 * <li>Swallow the supplied {@code Throwable}, thereby preventing propagation.</li>
 * <li>Throw a new exception, potentially wrapping the supplied {@code Throwable}.</li>
 * </ol>
 *
 * <p>If the supplied {@code Throwable} is swallowed by a handler method, subsequent
 * handler methods for the same lifecycle will not be invoked; otherwise, the
 * corresponding handler method of the next registered
 * {@code LifecycleMethodExecutionExceptionHandler} (if there is one) will be
 * invoked with any {@link Throwable} thrown by the previous handler.
 *
 * @see TestExecutionExceptionHandler
 * @since 5.5
 */
@API(status = EXPERIMENTAL, since = "5.5")
public interface LifecycleMethodExecutionExceptionHandler extends Extension {

	
Handle the supplied Throwable that was thrown during execution of a @BeforeAll lifecycle method. 
Please refer to the class-level Javadoc for
Implementation Guidelines.
Params:
context – the current extension context; never null
throwable – the Throwable to handle; never null/**
	 * Handle the supplied {@link Throwable} that was thrown during execution of
	 * a {@code @BeforeAll} lifecycle method.
	 *
	 * <p>Please refer to the class-level Javadoc for
	 * <a href="#implementation-guidelines">Implementation Guidelines</a>.
	 *
	 * @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 Throwable that was thrown during execution of a @BeforeEach lifecycle method. 
Please refer to the class-level Javadoc for
Implementation Guidelines.
Params:
context – the current extension context; never null
throwable – the Throwable to handle; never null/**
	 * Handle the supplied {@link Throwable} that was thrown during execution of
	 * a {@code @BeforeEach} lifecycle method.
	 *
	 * <p>Please refer to the class-level Javadoc for
	 * <a href="#implementation-guidelines">Implementation Guidelines</a>.
	 *
	 * @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 Throwable that was thrown during execution of a @AfterEach lifecycle method. 
Please refer to the class-level Javadoc for
Implementation Guidelines.
Params:
context – the current extension context; never null
throwable – the Throwable to handle; never null/**
	 * Handle the supplied {@link Throwable} that was thrown during execution of
	 * a {@code @AfterEach} lifecycle method.
	 *
	 * <p>Please refer to the class-level Javadoc for
	 * <a href="#implementation-guidelines">Implementation Guidelines</a>.
	 *
	 * @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 Throwable that was thrown during execution of a @AfterAll lifecycle method. 
Please refer to the class-level Javadoc for
Implementation Guidelines.
Params:
context – the current extension context; never null
throwable – the Throwable to handle; never null/**
	 * Handle the supplied {@link Throwable} that was thrown during execution of
	 * a {@code @AfterAll} lifecycle method.
	 *
	 * <p>Please refer to the class-level Javadoc for
	 * <a href="#implementation-guidelines">Implementation Guidelines</a>.
	 *
	 * @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;
	}

}