Support scanning for classpath resources

[mpkorstanje]

Overview

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

A resource is represented as:

public interface Resource {
	String getName();

	URI getUri();

	default InputStream getInputStream() throws IOException {
		return getUri().toURL().openStream();
	}
}

Fixes: #3630

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

---

Definition of Done

• There are no TODOs left in the code
• Method preconditions are checked and documented in the method's Javadoc
• Coding conventions (e.g. for logging) have been followed
• Change is covered by automated tests including corner cases, errors, and exception handling
• Public API has Javadoc and @API annotations
• Change is documented in the User Guide and Release Notes

[sbrannen]

Thanks for the PR, @mpkorstanje! 👍

We'll try to find some time to properly review it in the coming weeks (months?).

[mpkorstanje]

Cheers! No problem.

[marcphilipp]

I'll have a look at the coverage later. I'm out of time for now.

That's my bad (again). Rebasing should fix it.

[mpkorstanje]

Cheers! Might be good to document the switches for coverage and predictive test selection in the CONTRIBUTING.md.

[marcphilipp]

Cheers! Might be good to document the switches for coverage and predictive test selection in the CONTRIBUTING.md.

Done in c8beae0. Do you think that's clear enough?

[marcphilipp]

I briefly discussed this PR with the team. We think restricting the resources to remove "duplicates" is too limiting. Instead, a filter that checks that Resource.getUri() equals ClassLoader.getResource could be used with a default implementation provided as a static method in ResourceFilter. WDYT?

[mpkorstanje]

Done in c8beae0. Do you think that's clear enough?

Yes. Though I now seem to have some problems generating the coverage report at all now. I'll have to look into this later.

We think restricting the resources to remove "duplicates" is too limiting. Instead, a filter that checks that Resource.getUri() equals ClassLoader.getResource could be used with a default implementation provided as a static method in ResourceFilter. WDYT?

Seems reasonable. I'll have a look at the plumbing.

[marcphilipp]

@mpkorstanje Do you have time to continue working on this? We'd like to include it in the 5.11 RC1 which is ~3 weeks from now.

[mpkorstanje]

I've pushed the plumbing changes.

I'm mostly stuck on #3718. I think there are some subtleties that could maybe propagate backwards into this PR. But I suppose we can keep evolving the API as needed. So we can consider this done.

[marcphilipp]

Agreed. Let's finish this one and then focus on #3718. I can also take a more active role there if you don't have the time.

[mpkorstanje]

That would be appreciated!

[marcphilipp]

@mpkorstanje Do you think it would make sense to add a Predicate<Resource> as a constant that allows filtering out duplicates?

Predicate<Resource> DEFAULT_RESOURCE = resource -> {
	try {
		URL defaultResourceUrl = ClassLoaderUtils.getDefaultClassLoader().getResource(resource.getName());
		return defaultResourceUrl != null && resource.getUri().equals(defaultResourceUrl.toURI());
	}
	catch (URISyntaxException e) {
		throw new JUnitException("Failed to convert URL of resource to URI", e);
	}
};

[mpkorstanje]

@mpkorstanje Do you think it would make sense to add a Predicate as a constant that allows filtering out duplicates?

Not in this iteration I'd think. You're about to go down the same rabbit hole I spend a week in. 😉

A predicate would not work. It would not remove duplicates, but rather remove all shadowed resources. Instead you would need a function that transform a resources into a "canonical" version of the resource. Then you can de-duplicate the canonical resources. In #3718 I wrote a few functions to just that, a good starting point would be the ResourceContainerSelectorResolver from there look at ResourceUtils.getClasspathResource() and ReflectionSupport.tryToGetResource().

You could probably cherry pick those in.

[marcphilipp]

Not in this iteration I'd think. You're about to go down the same rabbit hole I spend a week in. 😉

Thanks for writing that up! I'll reply on the other PR.

A predicate would not work. It would not remove duplicates, but rather remove all shadowed resources.

Isn't that what you were after? Wouldn't it only allow canonical resources to pass the predicate?

[mpkorstanje]

Isn't that what you were after? Wouldn't it only allow canonical resources to pass the predicate?

That depends. When discovering a class in classpath root a, we currently load a class from classpath root b, if b shadows a.

Do we want the same behaviour for resources? If so we need a function, if not, then a predicate will do.

[marcphilipp]

I see what you mean now... 🤔

I'm pondering whether it makes sense to include this PR in 5.11 without #3718 and, if so, when we would ship the latter. WDYT?

[mpkorstanje]

I think it would make sense to ship this PR as it would unlock #3628. That was the original motivation for splitting these PRs.

[marcphilipp]

@mpkorstanje Thanks for all your hard work! 👍