Relocate `Resource` to `commons.io` package and deprecate existing interface

[sbrannen]

Overview

As I mentioned in #4876, org.junit.platform.commons.support.Resource causes cycles between the support, scanning, and util packages in junit-platform-commons.

Since it's rather likely that we will have the need to support additional I/O types at the platform level in the future, it's probably best that we relocate Resource to a new org.junit.platform.commons.io package and deprecate the existing interface.

Specifically, I am proposing the following.

1. Introduce org.junit.platform.commons.io.Resource as a copy of org.junit.platform.commons.support.Resource.
2. Have org.junit.platform.commons.support.Resource extend org.junit.platform.commons.io.Resource.
3. Deprecate org.junit.platform.commons.support.Resource for removal.
4. Update all APIs that reference org.junit.platform.commons.support.Resource to reference org.junit.platform.commons.io.Resource instead.

Since org.junit.platform.commons.support.Resource is a relatively new API, we assume that it is not actively used by many projects yet. In light of that, we are considering making these breaking changes for JUnit 6.0.

However, we hope that affected users will only need to change their imports from org.junit.platform.commons.support.Resource to org.junit.platform.commons.io.Resource to address any issues.

Related Issues

• Detect and remove package cycles within the code base #4876

[sbrannen]

@mpkorstanje, we would appreciate your feedback on this proposal.

[sbrannen]

Update

I spiked an implementation of the proposal in the following feature branch.

main...sbrannen:junit-framework:issues/4885-commons.io.Resource

[mpkorstanje]

Currently Resource is in active use by Cucumber.

From a technical point of view, this is indeed a small and manageable change but will create a barrier where both JUnit and Cucumber will have to be upgraded at the same time. In the past, when Spring was involved, this resulted in some friction:

• Upgrade from Cucumber 7.23.0 to 7.24.0 fails Gradle with "TestEngine with ID 'cucumber' failed to discover tests" cucumber/cucumber-jvm#3044
• Cannot upgrade to Cucumber 7.24.0 cucumber/cucumber-jvm#3027
• https://github.com/orgs/cucumber/discussions/2262

So I would prefer a non-breaking upgrade path, but I'm not sure if one exists.

Cucumber depends on both consumers and producers of Resource through:

    private static final EngineDiscoveryRequestResolver<CucumberEngineDescriptor> resolver = EngineDiscoveryRequestResolver
            .<CucumberEngineDescriptor> builder()
            .addSelectorResolver(context -> new FileContainerSelectorResolver(FeatureIdentifier::isFeature))
            .addResourceContainerSelectorResolver(resource -> isFeature(resource.getName()))
...

and:

    @Override
    public Resolution resolve(ClasspathResourceSelector selector, Context context) {
        Set<Resource> resources = selector.getClasspathResources();
...

And I think the proposed step no. 4 would break the addResourceContainerSelectorResolver but I can't say that for certain without actually trying that out.

[mpkorstanje]

Jinx! I'll try the feature branch.