cstamas commented on code in PR #1794: URL: https://github.com/apache/maven-resolver/pull/1794#discussion_r2798386407
########## src/site/markdown/how-resolver-works.md: ########## @@ -0,0 +1,131 @@ +# How Resolver Works +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +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 +and building blocks of Resolver. + +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 +implementations of missing components. Historically, Maven module completing Resolver is the +`org.apache.maven:maven-resolver-provider` module. + +## Core Concepts + +At the core of Resolver lies the concept of **artifacts** and **repositories**. An artifact is basically a Review Comment: In resolver, this is solved by having immutable Artifact (which is iface) implementation: ```java Artifact a = new DefaultArtifact("G:A:V"); // makes a "coordinate only" assertNull(a.getFile()); // true ``` And _resolved artifact_ check is really `a.getFile() != null`. See https://github.com/apache/maven-resolver/blob/master/maven-resolver-api/src/main/java/org/eclipse/aether/artifact/Artifact.java Also check https://github.com/apache/maven-resolver/blob/master/maven-resolver-api/src/main/java/org/eclipse/aether/resolution/ArtifactResult.java#L216-L226 for similar checks. Maven 4 API OTOH _split the two_, and have classes like `ArtifactCoordinates` (just coordinates) and `Artifact` that is a "pointer to file in local repo" (resolved coordinates). Maven 3 APIs (like maven-artifact module, I personally consider deprecated) has yet another abstraction done with _mutable classes_ and where Artifact is in fact a mish-mash of "everything" (ie they have even a scope). Hence, personally, my lingo is: * `new DefaultArtifact("G:A:V")` is just an artifact coordinate * sending `Artifact` via `Repositorysystem#resolve...` method and getting it back makes `Artifact#getFile() != null` (makes it resolved) * in some cases (ie. locally built, packaged and prepping for install/deploy) client code does `Artifact.setFile()` but I consider that a tech detail. In most cases it is resolver who resolves artifact. tl;dr Resolver `Artifact` instance in client code is most often "just a coordinate", created with GAV and sent to `RepositorySystem` to resolve (as this document is mostly about "resolving" feature of Resolver). So, from this POV, it is correct to say "Artifact is just a coordinate" (as content behind it is procured by "resolution" feature of Resolver). -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
