Skip to content

Maven 4 API gaps for plugin authors without an issue #14001

Open

Description

@slachiewicz

New feature, improvement proposal

These gaps came up when Maven plugins were ported from the Maven 3 API to the Maven 4 API (see #13302). Each was checked on maven-4.0.x and master on 2026-11-14, and none has an open issue. This is a list to triage, not a request to implement all of it: each item can be picked up on its own or rejected. The design trackers for the surrounding work are #13460 and #13499.

Type and method names below use the maven-4.0.x spelling; master has noun-style accessors for the same members (url() for getUrl(), and so on).

Repositories and resolution

  • Metadata resolution, repository policies and artifact descriptors. Replaces the resolver calls RepositorySystem.resolveMetadata and readArtifactDescriptor, and the policies of the Maven 3 ArtifactRepository. RemoteRepository has only getId(), getUrl() and getProtocol(), so a plugin cannot read the release or snapshot policy of a repository it was handed. There is no service that resolves maven-metadata.xml with update and checksum policy (master has a read-only RepositoryMetadata type used by repository events) and none that returns an artifact descriptor, so relocation is re-implemented. Belongs in org.apache.maven.api.services and RemoteRepository. Hit in maven-archetype-plugin, maven-resolver-ant-tasks, maven-dependency-plugin, maven-doap-plugin. Related: v4 SPI: Repository event listener for artifact/metadata changes #13520 (repository events), Enhance relocation to work for all versions #11255 (relocation behavior).
  • Existence check and remote layout on Transport. Replaces Wagon.resourceExists and ArtifactRepository.pathOf(Artifact). Transport has get, getBytes, getString and put*, no way to ask whether a resource exists without downloading it. Session.getPathForRemoteArtifact returns the path in the local cache, not the location in the remote repository, so a plugin builds g/a/v/a-v.ext by hand. Needed by maven-doap-plugin, which now infers existence from a .sha1 file. Related: [MRESOLVER-555] Existence check should lax the repository update policy maven-resolver#1224 (update policy of the resolver's own existence check).
  • Session.withLocalRepository cannot change resolver configuration. Replaces cloning the RepositorySystemSession with aether.enhancedLocalRepository.split=false. withLocalRepository(LocalRepository) takes a path and copies the configuration of the outer session (AbstractSession in maven-impl), so a plugin installing into a staging repository gets the split layout of the invoking build. There is also no helper that merges two Settings objects, the role of the Maven 3 SettingsUtils.merge. Needed by maven-invoker-plugin (MINVOKER-377). Related: [MNG-8167] enable "split repo" in settings.xml #10601 (split repository switch in settings.xml).
  • Artifact, ArtifactCoordinates and DependencyCoordinates factories need a Session. Every method of ArtifactFactory, ArtifactCoordinatesFactory and DependencyCoordinatesFactory takes one, so helper code and unit tests cannot create coordinates without a full session. VersionParser and TypeRegistry already work without one. Needed by maven-dependency-tree, maven-mapping and maven-surefire-common.
  • A dependency selector for one resolution. Replaces setting an Aether DependencySelector on a copy of the RepositorySystemSession. DependencyResolverRequest takes a PathScope and nothing else that shapes the graph. The compile and test path scopes run in the resolver's ELIMINATE mode, where conflict resolution runs over the whole graph before the unwanted scopes are filtered out. That is Maven's class path semantics; a plugin that needs each class path mediated on its own cannot ask for it. Needed by maven-dependency-plugin, which picks the version a given class path would see (MDEP-726). Related: Test the depth semantics of the impl scope and optional selectors maven-resolver#2288 (tests of the scope selectors).

Project and model

  • Original (pre-interpolation) model on Project. Replaces MavenProject.getOriginalModel(). Project has getModel() only; plugins re-read the POM file with ModelXmlFactory, which returns the file as modified so far instead of the load-time state. ModelBuilderResult.getRawModel() exists on the builder service but is not reachable from a Project. Hit in maven-release-plugin (nine uses) and maven-enforcer-plugin.
  • Changing the includes or excludes of a project source root. Replaces Maven 3 Resource.addExclude on MavenProject.getResources(). SourceRoot exposes includes() and excludes() read-only, and ProjectManager can add a source root but not remove or replace one. A plugin that takes a file from a resource directory, processes it and writes the result cannot keep the resources plugin from copying the original as well. Needed by maven-remote-resources-plugin, which does this for project files that override a bundle resource (MRRESOURCES-10).
  • Strict reading rejects two elements of model version 4.0.0. <reports> under <project> and <goals> under <plugin> are deprecated fields that maven.mdo keeps for model version 4.0.0 only (MNG-7602), and the Maven 3 strict reader accepts them. reader-stax.vm generates the reader from the fields of the current model version, so MavenStaxReader in strict mode fails on both, on 4.0.0-rc-7 and on master. A plugin that reads Maven 3 POM fragments strictly, to fail on an unknown element, has to read leniently instead. Hit in maven-remote-resources-plugin (supplemental models).

Mojo configuration and toolchains

  • ${plugin.*} expressions. Replaces ${plugin}, ${plugin.artifactMap} and ${project.artifactMap} of the Maven 3 PluginParameterExpressionEvaluator. PluginParameterExpressionEvaluatorV4 resolves objects under session., project., mojo. and settings. only, on both branches. Hit in maven-surefire-plugin, maven-scm-publish-plugin, maven-changelog-plugin. Related: Add a classifier-aware artifact map (fix #6773) #13672 (merged; an artifact map on the Maven 3 MavenProject, not the evaluator).
  • ToolchainFactory is not injectable. Replaces ToolchainFactory.createToolchain(ToolchainModel) from Maven 3 maven-core. The Maven 4 interface in org.apache.maven.api.services does not extend Service, and DefaultToolchainManager receives the factories as a Map<String, ToolchainFactory>, so a plugin cannot get the jdk factory to turn a ToolchainModel into a Toolchain. Needed by maven-toolchains-plugin. Related: [MNG-8576] Investigate modifying the Toolchain API to be session/project scoped #10657 (scope of ToolchainManager).
  • Whether a mojo execution was requested on the command line. Replaces Maven 3 MojoExecution.getSource(). On maven-4.0.x there is no source, and getLifecyclePhase() returning null for a command line goal is not documented. On master the Javadoc of model(), executionId() and lifecyclePhase() says each is empty for a direct CLI invocation, but DefaultMojoExecution passes the Maven 3 execution id through, which is default-cli or the @id given on the command line, so executionId() is not empty; lifecyclePhase() is also empty for a goal forked by @Execute(goal = ...). Needed by maven-dependency-plugin (requireExplicitDependencies), which compares the execution id with default-cli instead.

Session and settings

  • Settings decryption. Replaces SettingsDecrypter.decrypt and SecDispatcher.decrypt. No maven-api-* module exposes a decrypt service; maven-impl decrypts inside DefaultSettingsBuilder. Plugins that need to decrypt a value of their own, such as a key store password or a passphrase looked up by server id, rebuild the dispatcher from internal classes of plexus-sec-dispatcher. Needed by maven-release-plugin, maven-gpg-plugin, maven-jarsigner-plugin. Related: [MNG-5356] Make encrypt/decrypt logic pluggable #6919 (pluggable crypto), [MNG-5438] cli parameter to use a custom path settings-security.xml #6494 (path of settings-security.xml).
  • Command line options that forked builds need. Replaces MavenExecutionRequest (isShowErrors(), user and global settings and toolchains files). BuildInvocation exists on master only; it carries goals, profiles, projects, failure behavior and offline, but not -e and not the files given with -s, -gs, -t and -gt. They are parsed into Options in maven-api-cli, and nothing hands them to a mojo through Session. Needed by maven-surefire-plugin (-e for the forked JVM), maven-javadoc-plugin (nested Maven runs).

Not included

These gaps already have an issue, so they are not repeated above:

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestmvn4trackingTracking issue with sub-issues

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions