Maven Resolver

Maven Resolver is a separate Apache project (an artifact resolution library, not a plugin and not part of the POM model). Maven calls it a repository system and hands it a session: an object that holds the local repository, the mirrors, proxies and credentials from settings.xml, the caches and, most importantly for this page, the configuration properties. Before 3.5.0 the library was the Eclipse Aether project; the project was renamed when Maven took it over, but the Java packages are still org.eclipse.aether, and the key prefix of every option is still aether.. The jars in the lib directory of each distribution show the modules (the listing is of the three distributions used for this page):

The names say what the pieces are: an api and an spi (what Maven calls, what extensions can implement), util, the impl of the repository system, the named-locks that serialise concurrent builds on the same local repository, a connector-basic that turns a request into transport calls according to the repository layout, and the transports (HTTP, file:, and the bridge to Wagon). The last jar is not part of the Resolver project: maven-resolver-provider belongs to Maven and carries the Maven-specific rules — how to read a POM for a dependency, relocation, version ranges, the default scope rules. Its version is the Maven version.

The Resolver releases follow the Maven ones: Maven 3.5.0 introduced the Apache Maven Resolver line, Maven 3.9 uses 1.9, and Maven 3.10 and Maven 4 use the 2.0 line. The release notes of 3.10.0 give the reason: the aim was to align Maven 3 and Maven 4 on the same Resolver version. Because of that, a Maven 3.10 build and a Maven 4 build behave alike in the Resolver, even where the rest of the two differs; and a number of option names changed between 1.x and 2.x, which the section on Upgrading from Resolver 1.x to 2.x collects.

Source: Maven 3.10.0 release notes and Maven Resolver

The Resolver is configured with configuration properties, named aether.<area>.<option>. The Maven page says it in one sentence: use system variables. The values are strings, converted to the type of the option:

Maven fills the session from several places and sets some defaults of its own, so a few options have a different default in Maven than in the Resolver (the documentation sends the reader to the Maven class DefaultRepositorySystemSessionFactory for the details). Where can a user set an option? The experiments used one option whose effect can be observed — aether.system.dependencyVisitor — and the order in which Maven loads a plugin’s dependencies, which the section The dependency visitor and class path order explains. levelOrder is the default of Maven 3.10; preOrder is the older behaviour. The question for each place is whether the order in the plugin realm became the old one (b d c e) or stayed b c d e:

The lessons: a user property counts wherever it comes from (command line, .mvn/maven.config, the environment variables MAVEN_OPTS and MAVEN_ARGS); the command line wins over a settings profile; a settings profile counts when it is named in activeProfiles, with -P, or is activeByDefault, but not when its activation is a jdk, os, property or file condition (the session is built before those are evaluated); and a property in the POM is never seen, because the session exists before any POM is read. Maven 4.0.0-rc-7 gave the same results for the activeByDefault and the conditions. The place to put a property that the whole team needs is .mvn/maven.config, which is committed with the project; the page on Configuring Maven explains the file, and the repositories page lists the Resolver options of the transport.

Repository id suffix. Options marked "Supports Repo ID Suffix" in the documentation can be set for one repository by appending a period and the repository id: aether.transport.http.preemptiveAuth.tidepool-group=true, aether.remoteRepositoryFilter.prefixes.central=false. The next sections use it.

What the documentation page is. The page "Maven Resolver: Configuration Options" lists about 170 options of the latest Resolver release, including transports that Maven does not ship (Jetty, MinIO, JDK HttpClient), with the type, the default, the release that introduced the option ("Since") and whether it supports the suffix. An option that is not in the Resolver jars of your Maven is ignored without a message. Always check the release column against the table of Resolver versions above.

Source: Maven Resolver: Configuration Options, Set Configuration from Apache Maven

The debug output of Maven shows the Resolver’s choices. For a download from Central with an empty local repository:

Maven 3.9.16 printed the same kind of lines with HttpTransporter (the Resolver 1.9 transport class) and no lines about prefixes or lock factories. The available lock factories are the Resolver 2 named-locks; the option aether.syncContext.named.factory (since 1.9.1) selects one of file-lock, rwlock-local, semaphore-local and noop. file-lock is what lets two Maven processes that share a local repository wait for each other; noop turns the locking off and is only for a repository nobody else writes to. In the -X header Maven also lists the user properties it received, among them every aether.* option on the command line (for example aether.system.dependencyVisitor: levelOrder), which is the quickest way to see that a property reached the build.

The idea of the filter — ask a remote repository only for what it can have, so that builds are faster and private names do not leak to public repositories — and the prefixes filter with Central’s published .meta/prefixes.txt are described on Repositories, Mirrors & Repository Managers, with the case of a mirror. This section adds the rest: what the filter does to a request, what to do when it is wrong, and the groupId filter.

A repository publishes a checksum next to each artifact, and Maven compares it with the file it downloaded. That detects a damaged download; it does not detect an attacker who changes the file and its checksum, or a repository that has been replaced. Trusted checksums move the source of truth out of the repository: Resolver checks every resolved artifact against a checksum that you keep, in your own files. The feature has two parts: a post-processor (aether.artifactResolver.postProcessor.trustedChecksums, since 1.9.0, default false) that does the verification or the recording, and a source of the trusted values, the layout of which is also chosen with options. The sparse directory source (aether.trustedChecksumsSource.sparseDirectory) stores one file per artifact file in a tree that looks like a repository; the summary file source (aether.trustedChecksumsSource.summaryFile) is the alternative that keeps them in a summary file (not run here). For both, .basedir sets the directory (default .checksums of the local repository) and .originAware (default true) separates the checksums by repository id.

The experiment recorded the checksums of the project of the previous section, then verified, then broke one value. The options (the same for each step, shown once) are the first line, and record switches the recording on:

Recording wrote 87 checksum files (POMs and JARs, the plugins' included), and the one for commons-lang3 is the value that Central publishes. A later build with trustedChecksums=true and no record accepted a fresh local repository on all three Maven releases. Then the value was replaced by forty zeros:

Maven 3.9.16 and 4.0.0-rc-7 failed the same way. The message says where the expected value came from (PROVIDED, by the sparseDirectory source). An artifact without a recorded checksum is accepted by default; with aether.artifactResolver.postProcessor.trustedChecksums.failIfMissing=true (since 1.9.0) it is rejected, which turns the files into an allow-list of every file the build may use:

Other options: .checksumAlgorithms (default SHA-1; list several, comma separated, to record and check them all), .snapshots (include snapshots, default false) and, since Resolver 2.0.11, .scope (all by default, or project to check the project’s dependencies and leave the plugins out). Keep the recorded tree in version control, review its changes like a lock file, and put the options in .mvn/maven.config. The file-level checks of the repository and the signatures of the artifacts are part of the page on Security & Reproducible Builds; Gradle’s equivalent is dependency verification (Dependency Locking, Verification & Caching).

Source: Maven Resolver: Configuration Options, aether.artifactResolver.postProcessor.trustedChecksums

The local repository is by default one tree for the artifacts you installed and the ones downloaded from any repository (the repositories page describes its _remote.repositories records and the effects). Resolver 1.8.1 and later can split the tree. The flags are split (the main switch, default false), splitLocal, splitRemote, splitRemoteRepository and splitRemoteRepositoryLast. The experiment ran mvn install of a small project that depends on commons-lang3 (so one installed artifact and one downloaded artifact) on an empty repository, with each combination, and looked at where the two jars went:

The first level is installed and cached. splitLocal and splitRemote add a releases or snapshots level below it (the names come from the prefix options such as aether.lrm.enhanced.snapshotsPrefix, default snapshots); splitRemoteRepository adds a directory per repository (the repository id and, in Resolver 2, a hash of the URL), and splitRemoteRepositoryLast swaps the order of version and repository. The point is that what a build installed is kept apart from what it downloaded, and, with splitRemoteRepository, the downloads of one repository can be kept or dropped without touching the others — a CI server can cache the cached part between runs without restoring installed. The flag names changed between the Resolver lines, and the experiment checked both:

(The Resolver 2 jar still contains the keys aether.enhancedLocalRepository.localPrefix, .releasesPrefix, .remotePrefix, .snapshotsPrefix, .split, .splitLocal, .splitRemote, .splitRemoteRepository and .splitRemoteRepositoryLast next to the aether.lrm.enhanced.* ones.) Write the aether.enhancedLocalRepository.* form in a file that must work on Maven 3.9 and 3.10 both, and the aether.lrm.enhanced.* form for Maven 3.10 and later.

Source: Maven Resolver: Configuration Options, aether.lrm.enhanced.split

The Resolver builds the dependency graph (a tree with the nearest-wins decisions applied; see Dependencies, Scopes & Mediation) and then needs a list: the files to put in a class path. The option aether.system.dependencyVisitor (since 2.0.0) chooses how the graph is flattened: preOrder (depth first, a library followed by its own dependencies), levelOrder (breadth first, all direct dependencies, then their dependencies) or postOrder (dependencies before the library that needs them). The documentation says that Maven 4 uses levelOrder by default, where Maven 3 used preOrder, and the release notes of 3.10.0 list "Classpath ordering change" under the potentially breaking changes: -Daether.system.dependencyVisitor=preOrder restores the earlier order.

The order only matters when two libraries contain the same class or resource, and the first on the class path wins. The experiment has the smallest graph where the three orders differ: app depends on b and c; b depends on d; c depends on e. All five were installed in a local repository. The order was read from the list of libraries added to the class loader of a plugin that declares b and c as its own dependencies (the -X lines Included: ... of the plugin realm):

So the change is real: the default of Maven 3.10 and 4.0.0-rc-7 is levelOrder, preOrder gives the old order, and Maven 3.9.16 does not read the property at all. But the same experiment gave an unexpected result for the project’s own class path. The compile class path of app (read from the compilePath the compiler plugin receives, and again from dependency:build-classpath) was b d c e on all three releases and for all four values of the property:

In Maven 3.10.0 the source of LifecycleDependencyResolver builds the project’s artifacts by walking the dependency graph depth first (through RepositoryUtils.toArtifacts in maven-core), while the plugin realms in the experiment followed the list that the Resolver flattens with the visitor. This matters for a migration: the visitor option changes the order of the libraries that plugins see (for example the dependencies you add to a plugin’s <dependencies>), not, in this test, the order of the compile and test class paths of a project; the release notes state the change in more general terms. On Maven 4.0.0-rc-7 the project’s class path was also b d c e for every value. If the class path order of a project is critical, do not rely on either: make the intent explicit with exclusions and dependencyManagement (see Dependency Management & BOMs) and check with dependency:tree.

Source: Maven Resolver: Configuration Options, aether.system.dependencyVisitor and Maven 3.10.0 release notes, Classpath ordering change

For a user of Maven the move from Maven 3.9 to 3.10 is the move from Resolver 1.9 to 2.0. The Resolver project’s own upgrade page is addressed to the developers of programs that embed the Resolver; for them it says the upgrade should be "smooth sailing" as long as the code does not use deprecated classes of the 1.x line. Its changes:

For a user the visible changes found in the experiments are:

The first two rows are described with their consequences on the repositories page (the User-Agent option aether.connector.userAgent of Resolver 1.9 is aether.transport.http.userAgent in 2.0, and the old name is ignored by Maven 3.10). A build that sets aether.* options in .mvn/maven.config for Maven 3.9 therefore needs a review when Maven is upgraded: some options silently stop working, as the table shows, because an option the Resolver does not know is not an error.

Source: Maven Resolver: Upgrading Resolver, Upgrading from 1.x to 2.x

The Resolver is not tied to Maven. The Maven Resolver Ant Tasks use the same library to resolve and deploy from an Ant build (see Maven Resolver Ant Tasks). Apache Ivy has its own resolver and cache model (Ivy: Settings & Resolvers). Gradle has its own dependency resolution engine, with its own cache, metadata formats and verification (Dependency Resolution, Conflicts & Capabilities); the Maven concepts of this page map to repository content filtering (Repositories & Content Filtering) for the remote repository filters, and to dependency verification for the trusted checksums. The shared overview is in Dependency Management Fundamentals.

The books of the bibliography predate the Resolver as an Apache project (Maven 3.5.0): they have no aether.* options, no remote repository filtering, no trusted checksums, no split local repository, no named locks and no choice of the transport. Today’s documentation attributes all of that to the Resolver, which ships as a separate set of jars with each Maven.