Introduce feature flag for auto-closing AutoCloseable in Jupiter's ExtensionContext.Store

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

@@ -36,6 +36,10 @@ repository on GitHub.
   <<../user-guide/index.adoc#launcher-api-managing-state-across-test-engines, request-scoped>>
   resources.
 
+* CloseableResource is now deprecated and extends `AutoCloseable`. This change is
+  intended to improve the usability of the API and to align it with the standard Java
+  `AutoCloseable` interface.
+
 
 [[release-notes-5.13.0-M3-junit-jupiter]]
 === JUnit Jupiter

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

@@ -864,11 +864,15 @@ inner contexts may also be limited. Consult the corresponding Javadoc for detail
 methods available for storing and retrieving values via the `{ExtensionContext_Store}`.
 
 .`ExtensionContext.Store.CloseableResource`
-NOTE: An extension context store is bound to its extension context lifecycle. When an
+NOTE: `CloseableResource` is now deprecated and extends `AutoCloseable`.
+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.
 
+When the `junit.jupiter.store.autocloseable.as.closeableresource` property is set to `true`,
+any `AutoCloseable` instances stored via JUnit Jupiter\'s `Store` will be treated as `CloseableResource`.
+
 An example implementation of `CloseableResource` is shown below, using an `HttpServer`
 resource.
 

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

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

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

@@ -11,6 +11,7 @@
 package org.junit.jupiter.api.extension;
 
 import static java.util.Collections.unmodifiableList;
+import static org.apiguardian.api.API.Status.DEPRECATED;
 import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.INTERNAL;
 import static org.apiguardian.api.API.Status.STABLE;
@@ -503,16 +504,19 @@ interface Store {
 		 * inverse order they were added in.
 		 *
 		 * @since 5.1
+		 * @deprecated Please extend {@code AutoCloseable} directly.
 		 */
-		@API(status = STABLE, since = "5.1")
-		interface CloseableResource {
+		@SuppressWarnings("try")
+		@Deprecated
+		@API(status = DEPRECATED, since = "5.13")
+		interface CloseableResource extends AutoCloseable {
 
 			/**
 			 * Close underlying resources.
 			 *
-			 * @throws Throwable any throwable will be caught and rethrown
+			 * @throws Exception any exception will be caught and rethrown
 			 */
-			void close() throws Throwable;
+			void close() throws Exception;
 
 		}
 

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,7 +64,7 @@ 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
+	 * <li>If the callback adds a new {@link Store.CloseableResource} to the
 	 * {@link Store Store}, the resource is closed just after the instance is
 	 * destroyed.</li>
 	 * <li>The callbacks can now access data previously stored by
@@ -88,6 +87,7 @@ public interface TestInstantiationAwareExtension extends Extension {
 	 *                    configuration parameters; never {@code null}
 	 * @since 5.12
 	 */
+	@SuppressWarnings("deprecation")
 	@API(status = EXPERIMENTAL, since = "5.12")
 	default ExtensionContextScope getTestInstantiationExtensionContextScope(ExtensionContext rootContext) {
 		return ExtensionContextScope.DEFAULT;

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

@@ -210,6 +210,18 @@ 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 the use of {@link AutoCloseable} instances as
+	 * {@link org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource} resources: {@value}
+	 *
+	 * <p>By default, this feature is disabled.
+	 *
+	 * @since 5.13
+	 */
+	@SuppressWarnings("deprecation")
+	@API(status = EXPERIMENTAL, since = "5.13")
+	public static final String AUTOCLOSEABLE_AS_CLOSEABLERESOURCE_PROPERTY_NAME = JupiterConfiguration.AUTOCLOSEABLE_AS_CLOSEABLERESOURCE_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

@@ -75,6 +75,12 @@ public boolean isExtensionAutoDetectionEnabled() {
 			__ -> delegate.isExtensionAutoDetectionEnabled());
 	}
 
+	@Override
+	public boolean isAutocloseableAsCloseableResourceEnabled() {
+		return (boolean) cache.computeIfAbsent(AUTOCLOSEABLE_AS_CLOSEABLERESOURCE_PROPERTY_NAME,
+			__ -> delegate.isAutocloseableAsCloseableResourceEnabled());
+	}
+
 	@Override
 	public boolean isThreadDumpOnTimeoutEnabled() {
 		return (boolean) cache.computeIfAbsent(EXTENSIONS_TIMEOUT_THREAD_DUMP_ENABLED_PROPERTY_NAME,

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

@@ -112,6 +112,12 @@ public boolean isParallelExecutionEnabled() {
 		return configurationParameters.getBoolean(PARALLEL_EXECUTION_ENABLED_PROPERTY_NAME).orElse(false);
 	}
 
+	// TODO [6.0]: Switch the default to 'true' for this feature in JUnit5 6.0.
+	@Override
+	public boolean isAutocloseableAsCloseableResourceEnabled() {
+		return configurationParameters.getBoolean(AUTOCLOSEABLE_AS_CLOSEABLERESOURCE_PROPERTY_NAME).orElse(false);
+	}
+
 	@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,6 +42,7 @@ 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 AUTOCLOSEABLE_AS_CLOSEABLERESOURCE_PROPERTY_NAME = "junit.jupiter.store.autocloseable.as.closeableresource";
 	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";
@@ -60,6 +61,8 @@ public interface JupiterConfiguration {
 
 	boolean isParallelExecutionEnabled();
 
+	boolean isAutocloseableAsCloseableResourceEnabled();
+
 	boolean isExtensionAutoDetectionEnabled();
 
 	boolean isThreadDumpOnTimeoutEnabled();

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/AbstractExtensionContext.java

@@ -27,7 +27,6 @@
 import org.junit.jupiter.api.extension.ExecutableInvoker;
 import org.junit.jupiter.api.extension.Extension;
 import org.junit.jupiter.api.extension.ExtensionContext;
-import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
 import org.junit.jupiter.api.extension.MediaType;
 import org.junit.jupiter.api.function.ThrowingConsumer;
 import org.junit.jupiter.api.parallel.ExecutionMode;
@@ -51,10 +50,11 @@
  */
 abstract class AbstractExtensionContext<T extends TestDescriptor> implements ExtensionContextInternal, AutoCloseable {
 
+	@SuppressWarnings("deprecation")
 	private static final NamespacedHierarchicalStore.CloseAction<org.junit.platform.engine.support.store.Namespace> CLOSE_RESOURCES = (
 			__, ___, value) -> {
-		if (value instanceof CloseableResource) {
-			((CloseableResource) value).close();
+		if (value instanceof Store.CloseableResource) {
+			((Store.CloseableResource) value).close();
 		}
 	};
 

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/TempDirectory.java

@@ -53,7 +53,7 @@
 import org.junit.jupiter.api.extension.ExtensionConfigurationException;
 import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.api.extension.ExtensionContext.Namespace;
-import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
+import org.junit.jupiter.api.extension.ExtensionContext.Store;
 import org.junit.jupiter.api.extension.ParameterContext;
 import org.junit.jupiter.api.extension.ParameterResolver;
 import org.junit.jupiter.api.io.CleanupMode;
@@ -128,8 +128,9 @@ public void beforeEach(ExtensionContext context) {
 				.forEach(instance -> injectInstanceFields(context, instance));
 	}
 
+	@SuppressWarnings("deprecation")
 	private static void installFailureTracker(ExtensionContext context) {
-		context.getStore(NAMESPACE).put(FAILURE_TRACKER, (CloseableResource) () -> context.getParent() //
+		context.getStore(NAMESPACE).put(FAILURE_TRACKER, (Store.CloseableResource) () -> context.getParent() //
 				.ifPresent(parentContext -> {
 					if (selfOrChildFailed(context)) {
 						parentContext.getStore(NAMESPACE).put(CHILD_FAILED, true);
@@ -289,7 +290,8 @@ private static boolean selfOrChildFailed(ExtensionContext context) {
 				|| context.getStore(NAMESPACE).getOrDefault(CHILD_FAILED, Boolean.class, false);
 	}
 
-	static class CloseablePath implements CloseableResource {
+	@SuppressWarnings("deprecation")
+	static class CloseablePath implements Store.CloseableResource {
 
 		private static final Logger LOGGER = LoggerFactory.getLogger(CloseablePath.class);
 

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/TimeoutInvocationFactory.java

@@ -17,7 +17,6 @@
 
 import org.junit.jupiter.api.Timeout.ThreadMode;
 import org.junit.jupiter.api.extension.ExtensionContext.Store;
-import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
 import org.junit.jupiter.api.extension.InvocationInterceptor.Invocation;
 import org.junit.platform.commons.JUnitException;
 import org.junit.platform.commons.util.Preconditions;
@@ -52,7 +51,8 @@ private ScheduledExecutorService getThreadExecutorForSameThreadInvocation() {
 		return store.getOrComputeIfAbsent(SingleThreadExecutorResource.class).get();
 	}
 
-	private static abstract class ExecutorResource implements CloseableResource {
+	@SuppressWarnings({ "deprecation", "try" })
+	private static abstract class ExecutorResource implements Store.CloseableResource {
 
 		protected final ScheduledExecutorService executor;
 
@@ -65,16 +65,24 @@ ScheduledExecutorService get() {
 		}
 
 		@Override
-		public void close() throws Throwable {
+		public void close() throws Exception {
 			executor.shutdown();
-			boolean terminated = executor.awaitTermination(5, TimeUnit.SECONDS);
-			if (!terminated) {
+			try {
+				boolean terminated = executor.awaitTermination(5, TimeUnit.SECONDS);
+				if (!terminated) {
+					executor.shutdownNow();
+					throw new JUnitException("Scheduled executor could not be stopped in an orderly manner");
+				}
+			}
+			catch (InterruptedException exception) {
+				Thread.currentThread().interrupt();
 				executor.shutdownNow();
-				throw new JUnitException("Scheduled executor could not be stopped in an orderly manner");
+				throw new JUnitException("Scheduled executor could not be stopped in an orderly manner", exception);
 			}
 		}
 	}
 
+	@SuppressWarnings("try")
 	static class SingleThreadExecutorResource extends ExecutorResource {
 
 		@SuppressWarnings("unused")

junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedInvocationContext.java

@@ -76,6 +76,7 @@ private void storeParameterInfo(ExtensionContext context) {
 		new DefaultParameterInfo(declarations, accessor).store(context);
 	}
 
+	@SuppressWarnings({ "deprecation", "try" })
 	private static class CloseableArgument implements ExtensionContext.Store.CloseableResource {
 
 		private final AutoCloseable autoCloseable;
@@ -85,7 +86,7 @@ private static class CloseableArgument implements ExtensionContext.Store.Closeab
 		}
 
 		@Override
-		public void close() throws Throwable {
+		public void close() throws Exception {
 			this.autoCloseable.close();
 		}
 

jupiter-tests/src/test/java/org/junit/jupiter/api/extension/CloseableResourceIntegrationTests.java

@@ -46,6 +46,7 @@ void closesCloseableResourcesInExtensionContext(ExtensionContext extensionContex
 			store.put("baz", reportEntryOnClose(extensionContext, "3"));
 		}
 
+		@SuppressWarnings("deprecation")
 		private ExtensionContext.Store.CloseableResource reportEntryOnClose(ExtensionContext extensionContext,
 				String key) {
 			return () -> extensionContext.publishReportEntry(Map.of(key, "closed"));
@@ -78,6 +79,7 @@ void test() {
 
 	static class ThrowingOnCloseExtension implements BeforeEachCallback {
 
+		@SuppressWarnings("deprecation")
 		@Override
 		public void beforeEach(ExtensionContext context) {
 			context.getStore(GLOBAL).put("throwingResource", (ExtensionContext.Store.CloseableResource) () -> {

jupiter-tests/src/test/java/org/junit/jupiter/engine/ClassTemplateInvocationTests.java

@@ -74,7 +74,7 @@
 import org.junit.jupiter.api.extension.Extension;
 import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.api.extension.ExtensionContext.Namespace;
-import org.junit.jupiter.api.extension.ExtensionContext.Store.CloseableResource;
+import org.junit.jupiter.api.extension.ExtensionContext.Store;
 import org.junit.jupiter.api.extension.ParameterContext;
 import org.junit.jupiter.api.extension.ParameterResolutionException;
 import org.junit.jupiter.api.extension.ParameterResolver;
@@ -1175,7 +1175,8 @@ public Object resolveParameter(ParameterContext parameterContext, ExtensionConte
 			}
 		}
 
-		static class SomeResource implements CloseableResource {
+		@SuppressWarnings("deprecation")
+		static class SomeResource implements Store.CloseableResource {
 			private boolean closed;
 
 			@Override
@@ -1439,7 +1440,8 @@ public Object resolveParameter(ParameterContext parameterContext, ExtensionConte
 
 	}
 
-	private static class CustomCloseableResource implements CloseableResource {
+	@SuppressWarnings("deprecation")
+	private static class CustomCloseableResource implements Store.CloseableResource {
 
 		static boolean closed;
 

jupiter-tests/src/test/java/org/junit/jupiter/engine/TestTemplateInvocationTests.java

@@ -924,6 +924,7 @@ public Object resolveParameter(ParameterContext parameterContext, ExtensionConte
 
 	}
 
+	@SuppressWarnings("deprecation")
 	private static class CustomCloseableResource implements CloseableResource {
 
 		static boolean closed;

jupiter-tests/src/test/java/org/junit/jupiter/engine/extension/TestInstanceFactoryTests.java

@@ -737,6 +737,7 @@ void test2() {
 
 	private static abstract class AbstractTestInstanceFactory implements TestInstanceFactory {
 
+		@SuppressWarnings("deprecation")
 		@Override
 		public Object createTestInstance(TestInstanceFactoryContext factoryContext, ExtensionContext extensionContext) {
 			Class<?> testClass = factoryContext.getTestClass();

jupiter-tests/src/test/java/org/junit/jupiter/engine/extension/TestInstancePostProcessorTests.java

@@ -187,6 +187,7 @@ static abstract class AbstractInstancePostProcessor implements TestInstancePostP
 			this.name = name;
 		}
 
+		@SuppressWarnings("deprecation")
 		@Override
 		public void postProcessTestInstance(Object testInstance, ExtensionContext context) {
 			if (testInstance instanceof Named) {

jupiter-tests/src/test/java/org/junit/jupiter/engine/extension/TestInstancePreConstructCallbackTests.java

@@ -536,6 +536,7 @@ static abstract class AbstractTestInstancePreConstructCallback implements TestIn
 			this.name = name;
 		}
 
+		@SuppressWarnings("deprecation")
 		@Override
 		public void preConstructTestInstance(TestInstanceFactoryContext factoryContext, ExtensionContext context) {
 			assertThat(context.getTestInstance()).isNotPresent();

platform-tests/src/test/java/org/junit/jupiter/extensions/Heavyweight.java

@@ -57,6 +57,7 @@ interface Resource {
 	 * {@link ResourceValue#close()} method implementation is needed to comply
 	 * with both interfaces.
 	 */
+	@SuppressWarnings("deprecation")
 	static class ResourceValue implements Resource, CloseableResource, AutoCloseable {
 
 		static final AtomicInteger creations = new AtomicInteger();
@@ -80,6 +81,7 @@ public int usages() {
 		}
 	}
 
+	@SuppressWarnings("deprecation")
 	private static class CloseableOnlyOnceResource implements CloseableResource {
 
 		private final AtomicBoolean closed = new AtomicBoolean();

platform-tooling-support-tests/src/test/java/platform/tooling/support/tests/ManagedResource.java

@@ -100,6 +100,7 @@ private <T> Resource<T> getOrCreateResource(ExtensionContext extensionContext, C
 		}
 	}
 
+	@SuppressWarnings({ "deprecation", "try" })
 	class Resource<T> implements CloseableResource {
 
 		private final T value;
@@ -115,7 +116,7 @@ private T get() {
 		}
 
 		@Override
-		public void close() throws Throwable {
+		public void close() throws Exception {
 			((AutoCloseable) value).close();
 		}
 	}