Introduce org.junit.platform.commons.io.Resource

Resolves #4876.

Author: marcphilipp

documentation/src/docs/asciidoc/release-notes/release-notes-6.0.0-RC3.adoc

@@ -32,12 +32,36 @@ JUnit repository on GitHub.
   - `LauncherDiscoveryRequestBuilder.outputDirectoryProvider(OutputDirectoryProvider)`
   - `TestPlan.getOutputDirectoryProvider()`
   - `EngineTestKit.Builder.outputDirectoryProvider(OutputDirectoryProvider)`
+* Deprecate `org.junit.platform.commons.support.Resource` interface in favor of the new
+  `org.junit.platform.commons.io.Resource` one.
+* Deprecate `Resource`-related methods in `ReflectionSupport` in favor of corresponding
+  methods in new `ResourceSupport` class:
+  - `findAllResourcesInClasspathRoot(URI, Predicate)`
+  - `findAllResourcesInModule(String, Predicate)`
+  - `findAllResourcesInPackage(String, Predicate)`
+  - `streamAllResourcesInClasspathRoot(URI, Predicate)`
+  - `streamAllResourcesInModule(String, Predicate)`
+  - `streamAllResourcesInPackage(String, Predicate)`
+  - `tryToGetResources(String)`
+  - `tryToGetResources(String, ClassLoader)`
+* Deprecate `DiscoverySelectors.selectClasspathResource(Set)` method in favor of
+  `selectClasspathResourceByName(Set)`.
+* Deprecate `ClasspathResourceSelector.getClasspathResources()` method in favor of
+  `getResources()`.
+* Deprecate
+  `EngineDiscoveryRequestResolver.Builder.addResourceContainerSelectorResolver(Predicate)`
+  method in favor of `addResourceContainerSelectorResolver(ResourceFilter)`.
+* Deprecate `Resource`-related methods in `ClasspathScanner` in favor of new methods using
+  `org.junit.platform.commons.io.Resource` and `ResourceFilter`:
+  - `scanForResourcesInPackage(String, Predicate)`
+  - `scanForResourcesInClasspathRoot(URI, Predicate)`
 
 [[release-notes-6.0.0-RC3-junit-platform-new-features-and-improvements]]
 ==== New Features and Improvements
 
-* New `Resource.from(String, URI)` static factory method for creating an
-  `org.junit.platform.commons.support.Resource`.
+* New classpath resource abstraction in `org.junit.platform.commons.io.Resource` with
+  support class for loading resources or finding them on the classpath via static utility
+  methods in the new `org.junit.platform.commons.support.ResourceSupport` class.
 
 
 [[release-notes-6.0.0-RC3-junit-jupiter]]

junit-platform-commons/src/main/java/module-info.java

@@ -27,6 +27,7 @@
 	exports org.junit.platform.commons;
 	exports org.junit.platform.commons.annotation;
 	exports org.junit.platform.commons.function;
+	exports org.junit.platform.commons.io;
 	exports org.junit.platform.commons.logging to
 			org.junit.jupiter.api,
 			org.junit.jupiter.engine,

junit-platform-commons/src/main/java/org/junit/platform/commons/io/DefaultResource.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2015-2025 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.platform.commons.io;
+
+import java.net.URI;
+
+import org.jspecify.annotations.Nullable;
+import org.junit.platform.commons.PreconditionViolationException;
+import org.junit.platform.commons.annotation.Contract;
+
+/**
+ * Default implementation of {@link Resource}.
+ *
+ * @since 6.0
+ */
+record DefaultResource(String name, URI uri) implements Resource {
+
+	DefaultResource {
+		checkNotNull(name, "name");
+		checkNotNull(uri, "uri");
+	}
+
+	@Override
+	public String getName() {
+		return this.name;
+	}
+
+	@Override
+	public URI getUri() {
+		return this.uri;
+	}
+
+	// Cannot use Preconditions due to package cycle
+	@Contract("null, _ -> fail; !null, _ -> param1")
+	private static <T> void checkNotNull(@Nullable T input, String title) {
+		if (input == null) {
+			throw new PreconditionViolationException(title + " must not be null");
+		}
+	}
+
+}

junit-platform-commons/src/main/java/org/junit/platform/commons/io/Resource.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2015-2025 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.platform.commons.io;
+
+import static org.apiguardian.api.API.Status.MAINTAINED;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+
+import org.apiguardian.api.API;
+
+/**
+ * {@code Resource} represents a resource on the classpath.
+ *
+ * <p><strong>WARNING</strong>: a {@code Resource} must provide correct
+ * {@link Object#equals(Object) equals} and {@link Object#hashCode() hashCode}
+ * implementations since a {@code Resource} may potentially be stored in a
+ * collection or map.
+ *
+ * @since 6.0
+ * @see org.junit.platform.commons.support.ResourceSupport#findAllResourcesInClasspathRoot(URI, ResourceFilter)
+ * @see org.junit.platform.commons.support.ResourceSupport#findAllResourcesInPackage(String, ResourceFilter)
+ * @see org.junit.platform.commons.support.ResourceSupport#findAllResourcesInModule(String, ResourceFilter)
+ * @see org.junit.platform.commons.support.ResourceSupport#streamAllResourcesInClasspathRoot(URI, ResourceFilter)
+ * @see org.junit.platform.commons.support.ResourceSupport#streamAllResourcesInPackage(String, ResourceFilter)
+ * @see org.junit.platform.commons.support.ResourceSupport#streamAllResourcesInModule(String, ResourceFilter)
+ */
+@API(status = MAINTAINED, since = "6.0")
+public interface Resource {
+
+	/**
+	 * Create a new {@link Resource} with the given name and URI.
+	 *
+	 * @param name the name of the resource; never {@code null}
+	 * @param uri the URI of the resource; never {@code null}
+	 * @return a new {@code Resource}
+	 * @since 6.0
+	 */
+	static Resource of(String name, URI uri) {
+		return new DefaultResource(name, uri);
+	}
+
+	/**
+	 * Get the name of this resource.
+	 *
+	 * <p>The resource name is a {@code /}-separated path. The path is relative
+	 * to the classpath root in which the resource is located.
+	 *
+	 * @return the resource name; never {@code null}
+	 */
+	String getName();
+
+	/**
+	 * Get the URI of this resource.
+	 *
+	 * @return the URI of the resource; never {@code null}
+	 */
+	URI getUri();
+
+	/**
+	 * Get an {@link InputStream} for reading this resource.
+	 *
+	 * <p>The default implementation delegates to {@link java.net.URL#openStream()}
+	 * for this resource's {@link #getUri() URI}.
+	 *
+	 * @return an input stream for this resource; never {@code null}
+	 * @throws IOException if an I/O exception occurs
+	 */
+	default InputStream getInputStream() throws IOException {
+		return getUri().toURL().openStream();
+	}
+
+}

junit-platform-commons/src/main/java/org/junit/platform/commons/io/ResourceFilter.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2015-2025 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.platform.commons.io;
+
+import static org.apiguardian.api.API.Status.MAINTAINED;
+
+import java.util.function.Predicate;
+
+import org.apiguardian.api.API;
+
+/**
+ * Resource filter used by reflection and classpath scanning support.
+ *
+ * @since 6.0
+ * @see Resource
+ */
+@API(status = MAINTAINED, since = "6.0")
+public class ResourceFilter {
+
+	/**
+	 * Create a {@link ResourceFilter} instance from a predicate.
+	 *
+	 * @param resourcePredicate the resource predicate; never {@code null}
+	 * @return an instance of {@code ResourceFilter}; never {@code null}
+	 */
+	public static ResourceFilter of(Predicate<? super Resource> resourcePredicate) {
+		return new ResourceFilter(resourcePredicate);
+	}
+
+	private final Predicate<? super Resource> predicate;
+
+	private ResourceFilter(Predicate<? super Resource> predicate) {
+		this.predicate = predicate;
+	}
+
+	public boolean match(Resource resource) {
+		return predicate.test(resource);
+	}
+
+}

junit-platform-commons/src/main/java/org/junit/platform/commons/io/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * IO-related interfaces and support classes
+ */
+
+@NullMarked
+package org.junit.platform.commons.io;
+
+import org.jspecify.annotations.NullMarked;

junit-platform-commons/src/main/java/org/junit/platform/commons/support/AnnotationSupport.java

@@ -44,6 +44,7 @@
  * @see ClassSupport
  * @see ModifierSupport
  * @see ReflectionSupport
+ * @see ResourceSupport
  */
 @API(status = MAINTAINED, since = "1.0")
 public final class AnnotationSupport {

junit-platform-commons/src/main/java/org/junit/platform/commons/support/ClassSupport.java

@@ -31,6 +31,7 @@
  * @see AnnotationSupport
  * @see ModifierSupport
  * @see ReflectionSupport
+ * @see ResourceSupport
  */
 @API(status = MAINTAINED, since = "1.1")
 public final class ClassSupport {

junit-platform-commons/src/main/java/org/junit/platform/commons/support/DefaultResource.java

@@ -20,6 +20,7 @@
  *
  * @since 1.11
  */
+@SuppressWarnings("removal")
 record DefaultResource(String name, URI uri) implements Resource {
 
 	public DefaultResource {

junit-platform-commons/src/main/java/org/junit/platform/commons/support/ModifierSupport.java

@@ -33,6 +33,7 @@
  * @see AnnotationSupport
  * @see ClassSupport
  * @see ReflectionSupport
+ * @see ResourceSupport
  */
 @API(status = MAINTAINED, since = "1.4")
 public final class ModifierSupport {