Close AutoCloseable objects when closing ExtensionContext.Store

By default, instances of `AutoCloseable` are now closed when the `Store`
is closed in addition to instances of `CloseableResource`. The new
`junit.jupiter.extensions.store.close.autocloseable.enabled` config 
param allows reverting to the old behavior.

All core extensions implement both interfaces so they still work when 
the new behavior has been disabled. Extensions implemented in test code 
only implement `AutoCloseable` since they don't need to support that 
mode.

Resolves #4434.

---------

Co-authored-by: Marc Philipp <[email protected]>

Author: YongGoose

documentation/src/docs/asciidoc/release-notes/release-notes-5.13.0-M3.adoc

@@ -98,6 +98,14 @@ to start reporting discovery issues.
     - Blank `@SentenceFragment` declarations
     - `@BeforeParameterizedClassInvocation` and `@AfterParameterizedClassInvocation`
       methods declared in non-parameterized test classes
+* By default, `AutoCloseable` objects put into `ExtensionContext.Store` are now treated
+  like instances of `CloseableResource` (which has been deprecated) and are closed
+  automatically when the store is closed at the end of the test lifecycle. It's possible
+  to <<../user-guide/index.adoc#extensions-keeping-state-autocloseable-support, revert to the old behavior>>
+  via a configuration parameter. Please also see the
+  <<../user-guide/index.adoc#extensions-keeping-state-autocloseable-migration, migration note>>
+  for third-party extensions wanting to support both JUnit 5.13 and earlier versions.
+
 * `java.util.Locale` arguments are now converted according to the IETF BCP 47 language tag
   format. See the
   <<../user-guide/index.adoc#writing-tests-parameterized-tests-argument-conversion-implicit, User Guide>>

documentation/src/docs/asciidoc/user-guide/extensions.adoc

@@ -863,17 +863,22 @@ surrounding `ExtensionContext`. Since `ExtensionContexts` may be nested, the sco
 inner contexts may also be limited. Consult the corresponding Javadoc for details on the
 methods available for storing and retrieving values via the `{ExtensionContext_Store}`.
 
-.`ExtensionContext.Store.CloseableResource`
+[[extensions-keeping-state-autocloseable-support]]
+.Resource management via `_AutoCloseable_`
 NOTE: An extension context store is bound to its extension context lifecycle. When an
-extension context lifecycle ends it closes its associated store. All stored values
-that are instances of `CloseableResource` are notified by an invocation of their `close()`
-method in the inverse order they were added in.
-
-An example implementation of `CloseableResource` is shown below, using an `HttpServer`
+extension context lifecycle ends it closes its associated store. As of JUnit 5.13,
+all stored values that are instances of `AutoCloseable` are notified by an invocation of
+their `close()` method in the inverse order they were added in (unless the
+`junit.jupiter.extensions.store.close.autocloseable.enabled`
+<<running-tests-config-params, configuration parameter>> is set to `false`). Older
+versions only supported `CloseableResource`, which is deprecated but still available for
+backward compatibility.
+
+An example implementation of `AutoCloseable` is shown below, using an `HttpServer`
 resource.
 
 [source,java,indent=0]
-.`HttpServer` resource implementing `CloseableResource`
+.`HttpServer` resource implementing `AutoCloseable`
 ----
 include::{testDir}/example/extensions/HttpServerResource.java[tags=user_guide]
 ----
@@ -896,6 +901,33 @@ include::{testDir}/example/extensions/HttpServerExtension.java[tags=user_guide]
 include::{testDir}/example/HttpServerDemo.java[tags=user_guide]
 ----
 
+[[extensions-keeping-state-autocloseable-migration]]
+[TIP]
+.Migration Note for Resource Cleanup
+====
+
+Starting with JUnit Jupiter 5.13, the framework automatically closes resources stored in
+the `ExtensionContext.Store` that implement `AutoCloseable`. In earlier versions, only
+resources implementing `Store.CloseableResource` were automatically closed.
+
+If you're developing an extension that needs to support both JUnit Jupiter 5.13+ and
+earlier versions and your extension stores resources that need to be cleaned up, you
+should implement both interfaces:
+
+[source,java,indent=0]
+----
+public class MyResource implements Store.CloseableResource, AutoCloseable {
+    @Override
+    public void close() throws Exception {
+        // Resource cleanup code
+    }
+}
+----
+
+This ensures that your resource will be properly closed regardless of which JUnit Jupiter
+version is being used.
+====
+
 [[extensions-supported-utilities]]
 === Supported Utilities in Extensions
 

documentation/src/test/java/example/extensions/HttpServerResource.java

@@ -19,13 +19,11 @@
 
 import com.sun.net.httpserver.HttpServer;
 
-import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
-
 /**
- * Demonstrates an implementation of {@link CloseableResource} using an {@link HttpServer}.
+ * Demonstrates an implementation of {@link AutoCloseable} using an {@link HttpServer}.
  */
 // tag::user_guide[]
-class HttpServerResource implements CloseableResource {
+class HttpServerResource implements AutoCloseable {
 
 	private final HttpServer httpServer;
 

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

@@ -503,7 +503,9 @@ interface Store {
 		 * inverse order they were added in.
 		 *
 		 * @since 5.1
+		 * @deprecated Please extend {@code AutoCloseable} directly.
 		 */
+		@Deprecated
 		@API(status = STABLE, since = "5.1")
 		interface CloseableResource {
 
@@ -595,9 +597,11 @@ default <V> V getOrDefault(Object key, Class<V> requiredType, V defaultValue) {
 		 * <p>See {@link #getOrComputeIfAbsent(Object, Function, Class)} for
 		 * further details.
 		 *
-		 * <p>If {@code type} implements {@link ExtensionContext.Store.CloseableResource}
-		 * the {@code close()} method will be invoked on the stored object when
-		 * the store is closed.
+		 * <p>If {@code type} implements {@link CloseableResource} or
+		 * {@link AutoCloseable} (unless the
+		 * {@code junit.jupiter.extensions.store.close.autocloseable.enabled}
+		 * configuration parameter is set to {@code false}), then the {@code close()}
+		 * method will be invoked on the stored object when the store is closed.
 		 *
 		 * @param type the type of object to retrieve; never {@code null}
 		 * @param <V> the key and value type
@@ -606,6 +610,7 @@ default <V> V getOrDefault(Object key, Class<V> requiredType, V defaultValue) {
 		 * @see #getOrComputeIfAbsent(Object, Function)
 		 * @see #getOrComputeIfAbsent(Object, Function, Class)
 		 * @see CloseableResource
+		 * @see AutoCloseable
 		 */
 		@API(status = STABLE, since = "5.1")
 		default <V> V getOrComputeIfAbsent(Class<V> type) {
@@ -625,9 +630,11 @@ default <V> V getOrComputeIfAbsent(Class<V> type) {
 		 * <p>For greater type safety, consider using
 		 * {@link #getOrComputeIfAbsent(Object, Function, Class)} instead.
 		 *
-		 * <p>If the created value is an instance of {@link ExtensionContext.Store.CloseableResource}
-		 * the {@code close()} method will be invoked on the stored object when
-		 * the store is closed.
+		 * <p>If the created value is an instance of {@link CloseableResource} or
+		 * {@link AutoCloseable} (unless the
+		 * {@code junit.jupiter.extensions.store.close.autocloseable.enabled}
+		 * configuration parameter is set to {@code false}), then the {@code close()}
+		 * method will be invoked on the stored object when the store is closed.
 		 *
 		 * @param key the key; never {@code null}
 		 * @param defaultCreator the function called with the supplied {@code key}
@@ -638,6 +645,7 @@ default <V> V getOrComputeIfAbsent(Class<V> type) {
 		 * @see #getOrComputeIfAbsent(Class)
 		 * @see #getOrComputeIfAbsent(Object, Function, Class)
 		 * @see CloseableResource
+		 * @see AutoCloseable
 		 */
 		<K, V> Object getOrComputeIfAbsent(K key, Function<K, V> defaultCreator);
 
@@ -652,9 +660,11 @@ default <V> V getOrComputeIfAbsent(Class<V> type) {
 		 * a new value will be computed by the {@code defaultCreator} (given
 		 * the {@code key} as input), stored, and returned.
 		 *
-		 * <p>If {@code requiredType} implements {@link ExtensionContext.Store.CloseableResource}
-		 * the {@code close()} method will be invoked on the stored object when
-		 * the store is closed.
+		 * <p>If {@code requiredType} implements {@link CloseableResource} or
+		 * {@link AutoCloseable} (unless the
+		 * {@code junit.jupiter.extensions.store.close.autocloseable.enabled}
+		 * configuration parameter is set to {@code false}), then the {@code close()}
+		 * method will be invoked on the stored object when the store is closed.
 		 *
 		 * @param key the key; never {@code null}
 		 * @param defaultCreator the function called with the supplied {@code key}
@@ -666,6 +676,7 @@ default <V> V getOrComputeIfAbsent(Class<V> type) {
 		 * @see #getOrComputeIfAbsent(Class)
 		 * @see #getOrComputeIfAbsent(Object, Function)
 		 * @see CloseableResource
+		 * @see AutoCloseable
 		 */
 		<K, V> V getOrComputeIfAbsent(K key, Function<K, V> defaultCreator, Class<V> requiredType);
 
@@ -676,23 +687,26 @@ default <V> V getOrComputeIfAbsent(Class<V> type) {
 		 * ExtensionContexts} for the store's {@code Namespace} unless they
 		 * overwrite it.
 		 *
-		 * <p>If the {@code value} is an instance of {@link ExtensionContext.Store.CloseableResource}
-		 * the {@code close()} method will be invoked on the stored object when
-		 * the store is closed.
+		 * <p>If the {@code value} is an instance of {@link CloseableResource} or
+		 * {@link AutoCloseable} (unless the
+		 * {@code junit.jupiter.extensions.store.close.autocloseable.enabled}
+		 * configuration parameter is set to {@code false}), then the {@code close()}
+		 * method will be invoked on the stored object when the store is closed.
 		 *
 		 * @param key the key under which the value should be stored; never
 		 * {@code null}
 		 * @param value the value to store; may be {@code null}
 		 * @see CloseableResource
+		 * @see AutoCloseable
 		 */
 		void put(Object key, Object value);
 
 		/**
 		 * Remove the value that was previously stored under the supplied {@code key}.
 		 *
 		 * <p>The value will only be removed in the current {@link ExtensionContext},
-		 * not in ancestors. In addition, the {@link CloseableResource} API will not
-		 * be honored for values that are manually removed via this method.
+		 * not in ancestors. In addition, the {@link CloseableResource} and {@link AutoCloseable}
+		 * API will not be honored for values that are manually removed via this method.
 		 *
 		 * <p>For greater type safety, consider using {@link #remove(Object, Class)}
 		 * instead.
@@ -709,8 +723,8 @@ default <V> V getOrComputeIfAbsent(Class<V> type) {
 		 * under the supplied {@code key}.
 		 *
 		 * <p>The value will only be removed in the current {@link ExtensionContext},
-		 * not in ancestors. In addition, the {@link CloseableResource} API will not
-		 * be honored for values that are manually removed via this method.
+		 * not in ancestors. In addition, the {@link CloseableResource} and {@link AutoCloseable}
+		 * API will not be honored for values that are manually removed via this method.
 		 *
 		 * @param key the key; never {@code null}
 		 * @param requiredType the required type of the value; never {@code null}

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

@@ -16,7 +16,6 @@
 import org.apiguardian.api.API;
 import org.junit.jupiter.api.TestInstance;
 import org.junit.jupiter.api.extension.ExtensionContext.Store;
-import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
 
 /**
  * Interface for {@link Extension Extensions} that are aware and can influence
@@ -65,9 +64,11 @@ public interface TestInstantiationAwareExtension extends Extension {
 	 * <li>{@link ExtensionContext#getTestMethod() getTestMethod()} is no longer
 	 * empty, unless the {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS}
 	 * lifecycle is used.</li>
-	 * <li>If the callback adds a new {@link CloseableResource} to the
-	 * {@link Store Store}, the resource is closed just after the instance is
-	 * destroyed.</li>
+	 * <li>If the callback adds a new {@link Store.CloseableResource} or
+	 * {@link AutoCloseable} to the {@link Store Store} (unless the
+	 * {@code junit.jupiter.extensions.store.close.autocloseable.enabled}
+	 * configuration parameter is set to {@code false}), then
+	 * the resource is closed just after the instance is destroyed.</li>
 	 * <li>The callbacks can now access data previously stored by
 	 * {@link TestTemplateInvocationContext}, unless the
 	 * {@link TestInstance.Lifecycle#PER_CLASS PER_CLASS} lifecycle is used.</li>

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/Constants.java

@@ -210,6 +210,16 @@ public final class Constants {
 	@API(status = STABLE, since = "5.10")
 	public static final String PARALLEL_EXECUTION_ENABLED_PROPERTY_NAME = JupiterConfiguration.PARALLEL_EXECUTION_ENABLED_PROPERTY_NAME;
 
+	/**
+	 * Property name used to enable auto-closing of {@link AutoCloseable} instances
+	 *
+	 * <p>By default, auto-closing is enabled.
+	 *
+	 * @since 5.13
+	 */
+	@API(status = EXPERIMENTAL, since = "5.13")
+	public static final String CLOSING_STORED_AUTO_CLOSEABLE_ENABLED_PROPERTY_NAME = JupiterConfiguration.CLOSING_STORED_AUTO_CLOSEABLE_ENABLED_PROPERTY_NAME;
+
 	/**
 	 * Property name used to set the default test execution mode: {@value}
 	 *

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/config/CachingJupiterConfiguration.java

@@ -69,6 +69,12 @@ public boolean isParallelExecutionEnabled() {
 			__ -> delegate.isParallelExecutionEnabled());
 	}
 
+	@Override
+	public boolean isClosingStoredAutoCloseablesEnabled() {
+		return (boolean) cache.computeIfAbsent(CLOSING_STORED_AUTO_CLOSEABLE_ENABLED_PROPERTY_NAME,
+			__ -> delegate.isClosingStoredAutoCloseablesEnabled());
+	}
+
 	@Override
 	public boolean isExtensionAutoDetectionEnabled() {
 		return (boolean) cache.computeIfAbsent(EXTENSIONS_AUTODETECTION_ENABLED_PROPERTY_NAME,

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/config/DefaultJupiterConfiguration.java

@@ -112,6 +112,11 @@ public boolean isParallelExecutionEnabled() {
 		return configurationParameters.getBoolean(PARALLEL_EXECUTION_ENABLED_PROPERTY_NAME).orElse(false);
 	}
 
+	@Override
+	public boolean isClosingStoredAutoCloseablesEnabled() {
+		return configurationParameters.getBoolean(CLOSING_STORED_AUTO_CLOSEABLE_ENABLED_PROPERTY_NAME).orElse(true);
+	}
+
 	@Override
 	public boolean isExtensionAutoDetectionEnabled() {
 		return configurationParameters.getBoolean(EXTENSIONS_AUTODETECTION_ENABLED_PROPERTY_NAME).orElse(false);

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/config/JupiterConfiguration.java

@@ -42,14 +42,15 @@ public interface JupiterConfiguration {
 	String EXTENSIONS_AUTODETECTION_EXCLUDE_PROPERTY_NAME = "junit.jupiter.extensions.autodetection.exclude";
 	String DEACTIVATE_CONDITIONS_PATTERN_PROPERTY_NAME = "junit.jupiter.conditions.deactivate";
 	String PARALLEL_EXECUTION_ENABLED_PROPERTY_NAME = "junit.jupiter.execution.parallel.enabled";
+	String CLOSING_STORED_AUTO_CLOSEABLE_ENABLED_PROPERTY_NAME = "junit.jupiter.extensions.store.close.autocloseable.enabled";
 	String DEFAULT_EXECUTION_MODE_PROPERTY_NAME = Execution.DEFAULT_EXECUTION_MODE_PROPERTY_NAME;
 	String DEFAULT_CLASSES_EXECUTION_MODE_PROPERTY_NAME = Execution.DEFAULT_CLASSES_EXECUTION_MODE_PROPERTY_NAME;
 	String EXTENSIONS_AUTODETECTION_ENABLED_PROPERTY_NAME = "junit.jupiter.extensions.autodetection.enabled";
 	String EXTENSIONS_TIMEOUT_THREAD_DUMP_ENABLED_PROPERTY_NAME = PreInterruptCallback.THREAD_DUMP_ENABLED_PROPERTY_NAME;
 	String DEFAULT_TEST_INSTANCE_LIFECYCLE_PROPERTY_NAME = TestInstance.Lifecycle.DEFAULT_LIFECYCLE_PROPERTY_NAME;
 	String DEFAULT_DISPLAY_NAME_GENERATOR_PROPERTY_NAME = DisplayNameGenerator.DEFAULT_GENERATOR_PROPERTY_NAME;
 	String DEFAULT_TEST_METHOD_ORDER_PROPERTY_NAME = MethodOrderer.DEFAULT_ORDER_PROPERTY_NAME;
-	String DEFAULT_TEST_CLASS_ORDER_PROPERTY_NAME = ClassOrderer.DEFAULT_ORDER_PROPERTY_NAME;;
+	String DEFAULT_TEST_CLASS_ORDER_PROPERTY_NAME = ClassOrderer.DEFAULT_ORDER_PROPERTY_NAME;
 	String DEFAULT_TEST_INSTANTIATION_EXTENSION_CONTEXT_SCOPE_PROPERTY_NAME = ExtensionContextScope.DEFAULT_SCOPE_PROPERTY_NAME;
 
 	Predicate<Class<? extends Extension>> getFilterForAutoDetectedExtensions();
@@ -60,6 +61,8 @@ public interface JupiterConfiguration {
 
 	boolean isParallelExecutionEnabled();
 
+	boolean isClosingStoredAutoCloseablesEnabled();
+
 	boolean isExtensionAutoDetectionEnabled();
 
 	boolean isThreadDumpOnTimeoutEnabled();