Document how resolver works internally by cstamas · Pull Request #1794 · apache/maven-resolver

cstamas · 2026-02-11T15:55:39Z

To have a place to direct users asking wrong questions, but also to align "lingo" we use.

elharo · 2026-02-11T22:36:14Z

src/site/markdown/how-resolver-works.md

+under the License.
+-->
+
+Maven Artifact Resolver (former Aether) is central piece of Maven, and thus,


elharo · 2026-02-11T22:36:36Z

src/site/markdown/how-resolver-works.md

+-->
+
+Maven Artifact Resolver (former Aether) is central piece of Maven, and thus,
+is many times target of questions and curiosity how it actually works under the hood.


delete ", and thus,
is many times target of questions and curiosity how it actually works under the hood."

elharo · 2026-02-11T22:37:23Z

src/site/markdown/how-resolver-works.md

+
+Maven Artifact Resolver (former Aether) is central piece of Maven, and thus,
+is many times target of questions and curiosity how it actually works under the hood.
+This document tries to shed some light on this topic, and explain the main concepts


shed some light on this topic --> explain how resolver works under the hood

elharo · 2026-02-11T22:38:02Z

src/site/markdown/how-resolver-works.md

+This document tries to shed some light on this topic, and explain the main concepts
+and building blocks of Resolver.
+
+One important aspect of Resolver is that itself, alone is "incomplete". Integrating application, like Maven is


One important aspect of Resolver is that itself, alone --> Resolver along

elharo · 2026-02-11T22:38:53Z

src/site/markdown/how-resolver-works.md

+
+One important aspect of Resolver is that itself, alone is "incomplete". Integrating application, like Maven is
+the one that provides the "glue" (models) and logic how to resolve versions, ranges, build effective models.
+Hence, Resolver itself, alone is unusable. To make it usable, one needs to complement it with models and


Hence, Resolver itself, alone is unusable. To make it usable, one needs to complement it with models and
implementations of missing components. Historically, Maven module completing Resolver is the
org.apache.maven:maven-resolver-provider module.

-->

By itself, Resolver is unusable. One needs to complement it with models and implementations of missing components. Historically, the Maven module completing Resolver is
org.apache.maven:maven-resolver-provider.

elharo · 2026-02-11T22:56:37Z

src/site/markdown/how-resolver-works.md

+In general, steps "dependency graph collection" and "conflict resolution" are performed together, and lingo we use for that operation is "dependency collection".
+The "flattening" and "artifact resolving" are also usually done together, and we use for those the term "artifact resolving".
+To have the story more confusing, when all the steps are performed together is also called "dependency resolution".
+Resolver API reflects this terminology and offers methods doing collection, resolution or both.


The Resolve API

elharo · 2026-02-11T22:56:47Z

src/site/markdown/how-resolver-works.md

+To have the story more confusing, when all the steps are performed together is also called "dependency resolution".
+Resolver API reflects this terminology and offers methods doing collection, resolution or both.
+* 
+* Method `CollectResult collectDependencies(RepositorySystemSession session, CollectRequest request)` performs only the collection step,


elharo · 2026-02-11T22:57:03Z

src/site/markdown/how-resolver-works.md

+Resolver API reflects this terminology and offers methods doing collection, resolution or both.
+* 
+* Method `CollectResult collectDependencies(RepositorySystemSession session, CollectRequest request)` performs only the collection step,
+as name suggests. Hence, only steps "collection" and "conflict resolution" are performed.


its name
the steps

elharo · 2026-02-11T22:57:22Z

src/site/markdown/how-resolver-works.md

+* Method `DependencyResult resolveDependencies(RepositorySystemSession session, DependencyRequest request)` performs both 
+collection and resolution steps.
+
+Also, each subsequent step depends on the previous one, for example a "dirty graph" cannot be flattened (due possible cycles).


one. For example,

elharo · 2026-02-11T22:57:36Z

src/site/markdown/how-resolver-works.md

+collection and resolution steps.
+
+Also, each subsequent step depends on the previous one, for example a "dirty graph" cannot be flattened (due possible cycles).
+And many times, what you want depends on your use case. For example, to investigate dependency graph, one may 


And many times --> Many times

elharo · 2026-02-12T13:07:00Z

src/site/markdown/how-resolver-works.md

+This document tries to  explain how resolver works under the hood, and explain the main concepts
+and building blocks of Resolver.
+
+Resolver alone is "incomplete". Integrating application, like Maven is


"Integrating application, like Maven is
the one that provides the "glue" (models) and logic how to resolve versions, ranges, build effective models."

-->

Integrating applications like Maven provide the "glue" (models) and logic to resolve versions and ranges and build effective models.

elharo · 2026-02-12T13:07:54Z

src/site/markdown/how-resolver-works.md

+## Core Concepts
+
+At the core of Resolver are **artifacts** and **repositories**. An artifact is basically a 
+"symbolic coordinate" of some content. Usually it is a JAR, but it can be really anything, as long as it is


"An artifact is basically a
"symbolic coordinate" of some content."

This statement seems factually incorrect. An artifact is not a coordinate. It is the bytes.

elharo · 2026-02-12T13:09:02Z

src/site/markdown/how-resolver-works.md

+with one local repository (usually a directory on local filesystem) and zero or more remote repositories.
+
+The term "resolving" is a bit overloaded, but in general it involves following steps:
+* **dependency graph collection** builds the "dependency graph"


I meant the list in the doc, not this one list item. That is do you want to convert the four item list in these foru paragraphs to an ordered list?

elharo · 2026-02-12T13:09:27Z

src/site/markdown/how-resolver-works.md

+
+We call an artifact "resolvable" if it can be resolved from any available (local or remote) repository. To make an artifact
+"resolvable" from the local repository, one needs to "install" it. To make an artifact "resolvable" from a remote repository, 
+one needs to "deploy" it (this is over-simplification; publishing is new term, but it also involves deploy step).


an over-simplification

I' don't follow "publishing is new term, but it also involves deploy step)"

In "old times" you did deploy to remote repositories, even Central. But today, you "deploy" ONLY to your private repositories/MRM hosted ones, while to get something to Central you need publishing. Publishing is NOT anymore supported directly by Maven (and is NOT deploy, that is a lifecycle phase involved on each module, overlaid, publishing is very different today).

So "deploy" -> is lifecycle phase, usually involves m-deploy-p, happens per each module (while we do support "at end").
"publish" -> is what one needs to perform to get artifacts available from Central, involves calling (proprietary) APIs, zipping/packaging of all artifacts being published, performing validation, etc. In Maven 3 there is no "logically equivalent" place to perform it, hence it usually needs extra extensions like https://maveniverse.eu/docs/njord/

In Maven 4 there is a new lifecycle after:all that may serve as a hook, but still, handling (proprietary) API and zipping is not handled there either.

elharo · 2026-02-12T13:10:37Z

src/site/markdown/how-resolver-works.md

+
+### Dependency Graph Collection
+
+Collecting is the first step. Caller usually provides the root artifact along with the set of remote repositories to use.


Collection is the first step. The caller

elharo · 2026-02-12T13:14:45Z

src/site/markdown/how-resolver-works.md

+This is where filtering is applied as well.
+
+Resolver historically used "pre-order" to flatten the tree into a list, but Resolver 2 offers three strategies: "pre-order", 
+"post-order", and "level order" (the default). These strategies are currently fixed, but in the future we may offer a more 


I suggest deleting "These strategies are currently fixed, but in the future we may offer a more
flexible API for custom flattening strategies." I doubt that will happen, and if it does this can be updated then

elharo · 2026-02-12T13:15:38Z

src/site/markdown/how-resolver-works.md

+
+### Artifact Resolution
+
+Artifact resolution is the process of resolving (downloading and caching, if needed) the actual artifact payload from 


perhaps delete "payload". We haven't used the term before, though it might be useful to distinguish the BLOB from the BLOB+coordinates

elharo · 2026-02-12T13:16:27Z

src/site/markdown/how-resolver-works.md

+* Method `DependencyResult resolveDependencies(RepositorySystemSession session, DependencyRequest request)` performs both 
+collection and resolution steps.
+
+Also, each subsequent step depends on the previous one. For example a "dirty graph" cannot be flattened (due possible cycles).


Also, each --> Each

due --> due to

elharo · 2026-02-12T13:16:40Z

src/site/markdown/how-resolver-works.md

+collection and resolution steps.
+
+Also, each subsequent step depends on the previous one. For example a "dirty graph" cannot be flattened (due possible cycles).
+Many times, what you want depends on your use case. For example, to investigate dependency graph, one may 


the dependency graph

elharo · 2026-02-12T13:17:03Z

src/site/markdown/how-resolver-works.md

+Also, each subsequent step depends on the previous one. For example a "dirty graph" cannot be flattened (due possible cycles).
+Many times, what you want depends on your use case. For example, to investigate dependency graph, one may 
+want to collect the dirty graph, but not conflict resolve it. Moreover, dirty graphs are usually not even resolvable
+due cycles.


due to

though this is redundant with above

cstamas · 2026-02-12T14:29:02Z

Am merging this page too, but we can continue iterating and improving it later. Is still much better than nothing.

Document how resolver works internally

9873bf3

To have a place to direct users asking wrong questions, but also to align "lingo" we use.

cstamas added this to the 2.0.15 milestone Feb 11, 2026

cstamas requested review from gnodet, kwin and slawekjaranowski February 11, 2026 15:55

cstamas self-assigned this Feb 11, 2026

cstamas added the maintenance label Feb 11, 2026

cstamas added 4 commits February 11, 2026 17:02

Reword

cb47f81

Completeness

dafec37

More

0fedfd1

Mention workspace reader

8ec4b52

cstamas marked this pull request as ready for review February 11, 2026 17:29

cstamas mentioned this pull request Feb 11, 2026

Improve clarity and correctness in RRF documentation #1795

Merged

cstamas requested a review from elharo February 11, 2026 22:34

elharo requested changes Feb 11, 2026

View reviewed changes

cstamas added 2 commits February 12, 2026 12:58

Apply PR comments

d0c32f3

Merge remote-tracking branch 'upstream/master' into how-resolver-works

ba3b512

cstamas requested a review from elharo February 12, 2026 11:59

Missed one

8c8430c

elharo reviewed Feb 12, 2026

View reviewed changes

cstamas added 2 commits February 12, 2026 14:35

Merge remote-tracking branch 'upstream/master' into how-resolver-works

f555eb3

PR comments

c39dd4a

cstamas requested a review from elharo February 12, 2026 13:47

cstamas added documentation Improvements or additions to documentation and removed maintenance labels Feb 12, 2026

Make it an enumeration

3fdd649

cstamas merged commit d67da51 into apache:master Feb 12, 2026
14 checks passed

cstamas deleted the how-resolver-works branch February 12, 2026 14:32


		### Dependency Graph Collection

		Collecting is the first step. Caller usually provides the root artifact along with the set of remote repositories to use.


		### Artifact Resolution

		Artifact resolution is the process of resolving (downloading and caching, if needed) the actual artifact payload from

Conversation

cstamas commented Feb 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cstamas commented Feb 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants