[MNG-8749] Remove PathTranslator and UrlNormalizer from public API

[elharo]

Fixes #10326 / MNG-8749.

Summary

PathTranslator and UrlNormalizer in org.apache.maven.api.services.model are pure stateless functions with exactly one implementation each, no external reimplementations, and no reason to be injectable. This PR removes both interfaces from the public API and converts their implementations to static utility methods.

Changes

Interfaces removed

• api/maven-api-spi/.../services/model/PathTranslator.java — deleted
• api/maven-api-spi/.../services/model/UrlNormalizer.java — deleted

Implementations converted to static utility classes

• DefaultPathTranslator — final class with private constructor; alignToBaseDirectory(String, Path) is now a static method
• DefaultUrlNormalizer — final class with private constructor; normalize(String) is now a static method

Both classes had their @Named, @Singleton, and @Inject annotations removed since they no longer participate in DI.

Internal consumers updated (6 classes)

• DefaultModelInterpolator — constructor reduced from 4 params to 2 (RootLocator, Interpolator); uses static calls
• DefaultModelPathTranslator — removed PathTranslator field and constructor param; uses static call
• DefaultModelUrlNormalizer — removed UrlNormalizer field and constructor param; uses static call
• DefaultModelBuilder — removed PathTranslator field and constructor param
• DefaultProfileActivationContext — removed PathTranslator from all constructors; uses static call
• maven-testing stubs (MojoExtension, RepositorySystemSupplier) — simplified constructor wiring

Rationale

Analysis of the 22 interfaces in org.apache.maven.api.services.model shows they fall into three tiers:

Tier	Interfaces	Reason to keep
Tier 1 — Actively reimplemented	ModelProcessor, ProfileActivator, ProfileSelector, ModelValidator, ModelInterpolator	Extensions override these in the wild
Tier 2 — Required by contracts	ProfileActivationContext, RootDetector, ModelVersionParser, ModelPathTranslator, ModelUrlNormalizer, LifecycleBindingsInjector, PluginConfigurationExpander, ModelTransformer, ModelParser, ModelNormalizer, DependencyManagementImporter, DependencyManagementInjector, InheritanceAssembler, PluginManagementInjector, ProfileInjector	Parameter types in extension APIs, ServiceLoader contracts, or composite orchestrators
Tier 3 — Safe to remove	PathTranslator, UrlNormalizer	Pure functions, zero external implementations, no extension point value

This PR removes Tier 3 — the two interfaces that provide no extension-point value and are better expressed as static methods.

[gnodet]

I don't think "single implementation" is a valid criterion for removing an SPI here. If it were, we'd need to remove nearly the entire services/model package — 14 out of 18 interfaces there have exactly one implementation:

DependencyManagementImporter, DependencyManagementInjector, InheritanceAssembler, ModelInterpolator, ModelNormalizer, ModelPathTranslator, ModelUrlNormalizer, ModelValidator, PluginConfigurationExpander, PluginManagementInjector, ProfileInjector, ProfileSelector, RootLocator, UrlNormalizer — all have a single impl.

That's not a design smell — that's the design. This package is an injection-based extension mechanism: each interface has one default implementation, and the interface exists so that extensions can swap in alternatives via DI. As I mentioned in the issue, plugins and extensions do customize model building by replacing individual components. Removing the interface and hardcoding DefaultPathTranslator in constructor signatures closes that extensibility point.

The cost of keeping a 1-method interface is effectively zero. The cost of removing it and needing to reintroduce it later is a breaking change for anyone who coded against the current shape.

[elharo]

I think this approach is a large heap of YAGNI. This is just the one example I happened to stumble in first. Removing it from the public API makes the API and system simpler and still allows it to be added in later if it anyone ever needs, though I very much doubt anyone ever will.

[gnodet]

I did some research into what plugins and extensions in the Maven ecosystem actually use from the services/model package. Here's what I found — it might help frame the discussion beyond PathTranslator specifically.

The package splits into three tiers based on real-world external usage:

Tier 1 — Actively reimplemented by plugins (must keep as SPI)

These have multiple independent custom implementations across the ecosystem (Maven 3 API today, which is the evidence base for what Maven 4 will need):

• ModelProcessor — polyglot-maven, jgitver, qoomon/maven-git-versioning-extension, maven-tiles, Spring Boot thin launcher. The most-replaced interface in the entire model-building SPI.
• ProfileActivator — random-maven/profile-activator-extension (MVEL), kpiwko/el-profile-activator, stephenc/docker-maven-profile-activator, rrialq/jsr223-profile-activator.
• ProfileSelector — random-maven (AND-linked activation), johnjcool/and-activation-profile-selector, sviperll/ozymandias.
• ModelValidator — JetBrains IntelliJ, XMvn/Fedora, Spring Gradle dependency-management-plugin.
• ModelInterpolator — flatten-maven-plugin, Spring Gradle, JetBrains IntelliJ.

Tier 2 — Required by Tier 1 contracts or deliberately extensible

Not reimplemented themselves, but needed by the interfaces that are:

• ProfileActivationContext — parameter type in ProfileActivator.isActive() and ProfileSelector.getActiveProfiles(). Removing it from the SPI breaks the contract for all Tier 1 activator/selector extensions.
• RootDetector — extends Service, loaded via ServiceLoader in DefaultRootLocator, already has 2 implementations (DotMvnRootDetector, PomXmlRootDetector). Explicitly designed for extension.
• ModelVersionParser — intentionally decoupled from VersionParser (the javadoc says so explicitly) to let model building work without a full Maven session. Used as a constructor parameter in PropertyProfileActivator.
• ModelResolver — already reimplemented against the Maven 4 API by mizdebsk/dola-gleaner.
• ProfileInjector, RootLocator — consumed externally.

Tier 3 — No external usage, safe to remove

Zero reimplementations, not part of any extension contract:

• PathTranslator — alignToBaseDirectory(String, Path)
• UrlNormalizer — normalize(String)

Both are pure stateless functions — no fields, no dependencies, no side effects. The entire Tier 3 SPI surface is two utility methods.

Rather than replacing interface-based DI with concrete-class-based DI (which keeps injecting a stateless singleton through 4+ constructors), a cleaner approach would be to make both static methods — eliminating the interface, the DI plumbing, and the constructor parameters from the 6 consumers altogether.

[elharo]

That makes sense. Static methods are good for pure functions like these. Not every function needs to be turned into a pluggable object. Some should just work.

[gnodet]

Clean removal of two pure-function SPI interfaces (PathTranslator, UrlNormalizer) from the public API, converting them to static methods on final utility classes. Well-motivated — both are stateless functions with no fields, no dependencies, no side effects, and zero external reimplementations (confirmed by gnodet's Tier 1/2/3 analysis). Eliminates unnecessary DI boilerplate across 6+ constructor chains.

Observations (informational):

• The compat layer is unaffected — org.apache.maven.project.path.PathTranslator and org.apache.maven.model.path.UrlNormalizer are separate deprecated interfaces in different packages.
• Three incidental changes from the rebase commit (unused IOException import removal, blank line cleanup, test throws clause) are harmless but ideally would be in a separate commit for cleaner history.
• Since 4.0.0 is still in RC, this API removal is appropriate timing. The priority:blocker on the JIRA issue aligns with the rc-7 milestone target.

📋 PR Metadata

Aspect	Current	Suggested
Labels	(none)	removed

---

_{🤖 This review was generated by ForgeBot.}

[github-actions]

@elharo Please assign appropriate label to PR according to the type of change.