Support scanning for classpath resources (#3705)

Adds several new methods to ReflectionSupport to find or stream resource
objects in the classpath root, package, and modules.

A resource is represented via thew new `Resource` interface.

Resolves #3630.

Author: mpkorstanje

documentation/src/docs/asciidoc/release-notes/release-notes-5.11.0-RC1.adoc

@@ -29,6 +29,7 @@ repository on GitHub.
 * New `rootCause()` condition in `TestExecutionResultConditions` that matches if an
   exception's _root_ cause matches all supplied conditions, for use with the
   `EngineTestKit`.
+* `ReflectionSupport` now supports scanning for classpath resources.
 
 
 [[release-notes-5.11.0-RC1-junit-jupiter]]

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

@@ -67,7 +67,6 @@ private ReflectionSupport() {
 	 */
 	@API(status = DEPRECATED, since = "1.4")
 	@Deprecated
-	@SuppressWarnings("deprecation")
 	public static Optional<Class<?>> loadClass(String name) {
 		return ReflectionUtils.loadClass(name);
 	}
@@ -137,6 +136,28 @@ public static List<Class<?>> findAllClassesInClasspathRoot(URI root, Predicate<C
 		return ReflectionUtils.findAllClassesInClasspathRoot(root, classFilter, classNameFilter);
 	}
 
+	/**
+	 * Find all {@linkplain Resource resources} in the supplied classpath {@code root}
+	 * that match the specified {@code resourceFilter} predicate.
+	 *
+	 * <p>The classpath scanning algorithm searches recursively in subpackages
+	 * beginning with the root of the classpath.
+	 *
+	 * @param root the URI for the classpath root in which to scan; never
+	 * {@code null}
+	 * @param resourceFilter the resource type filter; never {@code null}
+	 * @return an immutable list of all such resources found; never {@code null}
+	 * but potentially empty
+	 * @since 1.11
+	 * @see #findAllResourcesInPackage(String, Predicate)
+	 * @see #findAllResourcesInModule(String, Predicate)
+	 */
+	@API(status = EXPERIMENTAL, since = "1.11")
+	public static List<Resource> findAllResourcesInClasspathRoot(URI root, Predicate<Resource> resourceFilter) {
+
+		return ReflectionUtils.findAllResourcesInClasspathRoot(root, resourceFilter);
+	}
+
 	/**
 	 * Find all {@linkplain Class classes} in the supplied classpath {@code root}
 	 * that match the specified {@code classFilter} and {@code classNameFilter}
@@ -162,6 +183,28 @@ public static Stream<Class<?>> streamAllClassesInClasspathRoot(URI root, Predica
 		return ReflectionUtils.streamAllClassesInClasspathRoot(root, classFilter, classNameFilter);
 	}
 
+	/**
+	 * Find all {@linkplain Resource resources} in the supplied classpath {@code root}
+	 * that match the specified {@code resourceFilter} predicate.
+	 *
+	 * <p>The classpath scanning algorithm searches recursively in subpackages
+	 * beginning with the root of the classpath.
+	 *
+	 * @param root the URI for the classpath root in which to scan; never
+	 * {@code null}
+	 * @param resourceFilter the resource type filter; never {@code null}
+	 * @return a stream of all such classes found; never {@code null}
+	 * but potentially empty
+	 * @since 1.11
+	 * @see #streamAllResourcesInPackage(String, Predicate)
+	 * @see #streamAllResourcesInModule(String, Predicate)
+	 */
+	@API(status = EXPERIMENTAL, since = "1.11")
+	public static Stream<Resource> streamAllResourcesInClasspathRoot(URI root, Predicate<Resource> resourceFilter) {
+
+		return ReflectionUtils.streamAllResourcesInClasspathRoot(root, resourceFilter);
+	}
+
 	/**
 	 * Find all {@linkplain Class classes} in the supplied {@code basePackageName}
 	 * that match the specified {@code classFilter} and {@code classNameFilter}
@@ -186,6 +229,29 @@ public static List<Class<?>> findAllClassesInPackage(String basePackageName, Pre
 		return ReflectionUtils.findAllClassesInPackage(basePackageName, classFilter, classNameFilter);
 	}
 
+	/**
+	 * Find all {@linkplain Resource resources} in the supplied {@code basePackageName}
+	 * that match the specified {@code resourceFilter} predicate.
+	 *
+	 * <p>The classpath scanning algorithm searches recursively in subpackages
+	 * beginning within the supplied base package.
+	 *
+	 * @param basePackageName the name of the base package in which to start
+	 * scanning; must not be {@code null} and must be valid in terms of Java
+	 * syntax
+	 * @param resourceFilter the resource type filter; never {@code null}
+	 * @return an immutable list of all such classes found; never {@code null}
+	 * but potentially empty
+	 * @since 1.11
+	 * @see #findAllResourcesInClasspathRoot(URI, Predicate)
+	 * @see #findAllResourcesInModule(String, Predicate)
+	 */
+	@API(status = EXPERIMENTAL, since = "1.11")
+	public static List<Resource> findAllResourcesInPackage(String basePackageName, Predicate<Resource> resourceFilter) {
+
+		return ReflectionUtils.findAllResourcesInPackage(basePackageName, resourceFilter);
+	}
+
 	/**
 	 * Find all {@linkplain Class classes} in the supplied {@code basePackageName}
 	 * that match the specified {@code classFilter} and {@code classNameFilter}
@@ -212,6 +278,30 @@ public static Stream<Class<?>> streamAllClassesInPackage(String basePackageName,
 		return ReflectionUtils.streamAllClassesInPackage(basePackageName, classFilter, classNameFilter);
 	}
 
+	/**
+	 * Find all {@linkplain Resource resources} in the supplied {@code basePackageName}
+	 * that match the specified {@code resourceFilter} predicate.
+	 *
+	 * <p>The classpath scanning algorithm searches recursively in subpackages
+	 * beginning within the supplied base package.
+	 *
+	 * @param basePackageName the name of the base package in which to start
+	 * scanning; must not be {@code null} and must be valid in terms of Java
+	 * syntax
+	 * @param resourceFilter the resource type filter; never {@code null}
+	 * @return a stream of all such resources found; never {@code null}
+	 * but potentially empty
+	 * @since 1.11
+	 * @see #streamAllResourcesInClasspathRoot(URI, Predicate)
+	 * @see #streamAllResourcesInModule(String, Predicate)
+	 */
+	@API(status = EXPERIMENTAL, since = "1.11")
+	public static Stream<Resource> streamAllResourcesInPackage(String basePackageName,
+			Predicate<Resource> resourceFilter) {
+
+		return ReflectionUtils.streamAllResourcesInPackage(basePackageName, resourceFilter);
+	}
+
 	/**
 	 * Find all {@linkplain Class classes} in the supplied {@code moduleName}
 	 * that match the specified {@code classFilter} and {@code classNameFilter}
@@ -236,6 +326,28 @@ public static List<Class<?>> findAllClassesInModule(String moduleName, Predicate
 		return ReflectionUtils.findAllClassesInModule(moduleName, classFilter, classNameFilter);
 	}
 
+	/**
+	 * Find all {@linkplain Resource resources} in the supplied {@code moduleName}
+	 * that match the specified {@code resourceFilter} predicate.
+	 *
+	 * <p>The module-path scanning algorithm searches recursively in all
+	 * packages contained in the module.
+	 *
+	 * @param moduleName the name of the module to scan; never {@code null} or
+	 * <em>empty</em>
+	 * @param resourceFilter the resource type filter; never {@code null}
+	 * @return an immutable list of all such resources found; never {@code null}
+	 * but potentially empty
+	 * @since 1.11
+	 * @see #findAllResourcesInClasspathRoot(URI, Predicate)
+	 * @see #findAllResourcesInPackage(String, Predicate)
+	 */
+	@API(status = EXPERIMENTAL, since = "1.11")
+	public static List<Resource> findAllResourcesInModule(String moduleName, Predicate<Resource> resourceFilter) {
+
+		return ReflectionUtils.findAllResourcesInModule(moduleName, resourceFilter);
+	}
+
 	/**
 	 * Find all {@linkplain Class classes} in the supplied {@code moduleName}
 	 * that match the specified {@code classFilter} and {@code classNameFilter}
@@ -261,6 +373,28 @@ public static Stream<Class<?>> streamAllClassesInModule(String moduleName, Predi
 		return ReflectionUtils.streamAllClassesInModule(moduleName, classFilter, classNameFilter);
 	}
 
+	/**
+	 * Find all {@linkplain Resource resources} in the supplied {@code moduleName}
+	 * that match the specified {@code resourceFilter} predicate.
+	 *
+	 * <p>The module-path scanning algorithm searches recursively in all
+	 * packages contained in the module.
+	 *
+	 * @param moduleName the name of the module to scan; never {@code null} or
+	 * <em>empty</em>
+	 * @param resourceFilter the resource type filter; never {@code null}
+	 * @return a stream of all such resources found; never {@code null}
+	 * but potentially empty
+	 * @since 1.11
+	 * @see #streamAllResourcesInClasspathRoot(URI, Predicate)
+	 * @see #streamAllResourcesInPackage(String, Predicate)
+	 */
+	@API(status = EXPERIMENTAL, since = "1.11")
+	public static Stream<Resource> streamAllResourcesInModule(String moduleName, Predicate<Resource> resourceFilter) {
+
+		return ReflectionUtils.streamAllResourcesInModule(moduleName, resourceFilter);
+	}
+
 	/**
 	 * Create a new instance of the specified {@link Class} by invoking
 	 * the constructor whose argument list matches the types of the supplied

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

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2015-2024 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.support;
+
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.util.function.Predicate;
+
+import org.apiguardian.api.API;
+
+/**
+ * Represents a resource on the classpath.
+ * @since 1.11
+ * @see ReflectionSupport#findAllResourcesInClasspathRoot(URI, Predicate)
+ * @see ReflectionSupport#findAllResourcesInPackage(String, Predicate)
+ * @see ReflectionSupport#findAllResourcesInModule(String, Predicate)
+ * @see ReflectionSupport#streamAllResourcesInClasspathRoot(URI, Predicate)
+ * @see ReflectionSupport#streamAllResourcesInPackage(String, Predicate)
+ * @see ReflectionSupport#streamAllResourcesInModule(String, Predicate)
+ */
+@API(status = EXPERIMENTAL, since = "1.11")
+public interface Resource {
+
+	/**
+	 * Get the resource name.
+	 * <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 URI to a resource.
+	 *
+	 * @return the uri of the resource; never {@code null}
+	 */
+	URI getUri();
+
+	/**
+	 * Returns an input stream for reading this resource.
+	 *
+	 * @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/util/ClassFileVisitor.java renamed to junit-platform-commons/src/main/java/org/junit/platform/commons/util/ClasspathFileVisitor.java

@@ -17,32 +17,33 @@
 import java.nio.file.Path;
 import java.nio.file.SimpleFileVisitor;
 import java.nio.file.attribute.BasicFileAttributes;
-import java.util.function.Consumer;
+import java.util.function.BiConsumer;
+import java.util.function.Predicate;
 
 import org.junit.platform.commons.logging.Logger;
 import org.junit.platform.commons.logging.LoggerFactory;
 
 /**
- * @since 1.0
+ * @since 1.11
  */
-class ClassFileVisitor extends SimpleFileVisitor<Path> {
+class ClasspathFileVisitor extends SimpleFileVisitor<Path> {
 
-	private static final Logger logger = LoggerFactory.getLogger(ClassFileVisitor.class);
+	private static final Logger logger = LoggerFactory.getLogger(ClasspathFileVisitor.class);
 
-	static final String CLASS_FILE_SUFFIX = ".class";
-	private static final String PACKAGE_INFO_FILE_NAME = "package-info" + CLASS_FILE_SUFFIX;
-	private static final String MODULE_INFO_FILE_NAME = "module-info" + CLASS_FILE_SUFFIX;
+	private final Path basePath;
+	private final BiConsumer<Path, Path> consumer;
+	private final Predicate<Path> filter;
 
-	private final Consumer<Path> classFileConsumer;
-
-	ClassFileVisitor(Consumer<Path> classFileConsumer) {
-		this.classFileConsumer = classFileConsumer;
+	ClasspathFileVisitor(Path basePath, Predicate<Path> filter, BiConsumer<Path, Path> consumer) {
+		this.basePath = basePath;
+		this.filter = filter;
+		this.consumer = consumer;
 	}
 
 	@Override
 	public FileVisitResult visitFile(Path file, BasicFileAttributes attributes) {
-		if (isNotPackageInfo(file) && isNotModuleInfo(file) && isClassFile(file)) {
-			classFileConsumer.accept(file);
+		if (filter.test(file)) {
+			consumer.accept(basePath, file);
 		}
 		return CONTINUE;
 	}
@@ -61,16 +62,4 @@ public FileVisitResult postVisitDirectory(Path dir, IOException ex) {
 		return CONTINUE;
 	}
 
-	private static boolean isNotPackageInfo(Path path) {
-		return !path.endsWith(PACKAGE_INFO_FILE_NAME);
-	}
-
-	private static boolean isNotModuleInfo(Path path) {
-		return !path.endsWith(MODULE_INFO_FILE_NAME);
-	}
-
-	private static boolean isClassFile(Path file) {
-		return file.getFileName().toString().endsWith(CLASS_FILE_SUFFIX);
-	}
-
 }

junit-platform-commons/src/main/java/org/junit/platform/commons/util/ClasspathFilters.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2015-2024 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.util;
+
+import java.nio.file.Path;
+import java.util.function.Predicate;
+
+/**
+ * @since 1.11
+ */
+class ClasspathFilters {
+
+	static final String CLASS_FILE_SUFFIX = ".class";
+	private static final String PACKAGE_INFO_FILE_NAME = "package-info" + CLASS_FILE_SUFFIX;
+	private static final String MODULE_INFO_FILE_NAME = "module-info" + CLASS_FILE_SUFFIX;
+
+	static Predicate<Path> classFiles() {
+		return file -> isNotPackageInfo(file) && isNotModuleInfo(file) && isClassFile(file);
+	}
+
+	static Predicate<Path> resourceFiles() {
+		return file -> !isClassFile(file);
+	}
+
+	private static boolean isNotPackageInfo(Path path) {
+		return !path.endsWith(PACKAGE_INFO_FILE_NAME);
+	}
+
+	private static boolean isNotModuleInfo(Path path) {
+		return !path.endsWith(MODULE_INFO_FILE_NAME);
+	}
+
+	private static boolean isClassFile(Path file) {
+		return file.getFileName().toString().endsWith(CLASS_FILE_SUFFIX);
+	}
+
+}