gnodet-bot commented on code in PR #2280:
URL: https://github.com/apache/maven-resolver/pull/2280#discussion_r4503901335
##########
src/site/markdown/using-resolver-in-maven-plugins.md:
##########
@@ -57,6 +57,40 @@ set by the Maven core so be sure to
compile/test your plugin against the version of `maven-resolver-api` that is
used by the minimum version of Maven that your plugin wants to support.
+## Which Resolver version to compile against
+
+Maven supplies the Resolver API at runtime, and the two Maven lines ship
+different Resolver lines:
+
+| Maven | Resolver | Notes |
+|---|---|---|
+| 3.9.x | 1.9.x | Maven 3.9.12 bundles 1.9.25. |
Review Comment:
⚠️ **Stale version data** (same issue as the identical row in
`upgrading-resolver.md`): Maven 3.9.16 bundles Resolver 1.9.27, not
3.9.12/1.9.25.
```suggestion
| 3.9.x | 1.9.x | Maven 3.9.16 bundles 1.9.27. |
```
##########
src/site/markdown/upgrading-resolver.md:
##########
@@ -16,24 +16,92 @@
limitations under the License.
-->
-This page will collect quick guides for developers upgrading from one to
-another major version of Resolver.
+This page collects quick guides for developers upgrading from one major
+version of Resolver to another.
# Upgrading from 1.x to 2.x
-Maven Resolver upcoming major version 2.x should be "smooth sailing", as long
you
-do not depend (directly or indirectly) on **deprecated** classes from Resolver
-1.x line. Always use latest 1.x release to check for deprecated classes.
+Resolver 2.x is the line that Maven 4 ships. Maven 3.9.x stays on Resolver
1.9.x.
+Both lines are maintained, so pick the line that matches the Maven version your
+code runs in. A Maven plugin that must run in both Maven 3.9 and Maven 4 has
its
+own guide: [Using Resolver in Maven
Plugins](using-resolver-in-maven-plugins.html).
+
+| Your code runs in | Compile against | Notes |
+|---|---|---|
+| Maven 3.9.x | Resolver 1.9.x | Maven 3.9.12 bundles 1.9.25. |
Review Comment:
⚠️ **Stale version data.** The latest 3.9.x release is Maven 3.9.16
(2026-05-13), which bundles Resolver **1.9.27** — not 3.9.12/1.9.25.
The PR already uses 1.9.27 in the POM snippets in
`using-resolver-in-maven-plugins.md`, making this row inconsistent within the
same PR.
```suggestion
| Maven 3.9.x | Resolver 1.9.x | Maven 3.9.16 bundles 1.9.27. |
```
##########
src/site/markdown/upgrading-resolver.md:
##########
@@ -16,24 +16,92 @@
limitations under the License.
-->
-This page will collect quick guides for developers upgrading from one to
-another major version of Resolver.
+This page collects quick guides for developers upgrading from one major
+version of Resolver to another.
# Upgrading from 1.x to 2.x
-Maven Resolver upcoming major version 2.x should be "smooth sailing", as long
you
-do not depend (directly or indirectly) on **deprecated** classes from Resolver
-1.x line. Always use latest 1.x release to check for deprecated classes.
+Resolver 2.x is the line that Maven 4 ships. Maven 3.9.x stays on Resolver
1.9.x.
+Both lines are maintained, so pick the line that matches the Maven version your
+code runs in. A Maven plugin that must run in both Maven 3.9 and Maven 4 has
its
+own guide: [Using Resolver in Maven
Plugins](using-resolver-in-maven-plugins.html).
+
+| Your code runs in | Compile against | Notes |
+|---|---|---|
+| Maven 3.9.x | Resolver 1.9.x | Maven 3.9.12 bundles 1.9.25. |
+| Maven 4.0.x | Resolver 2.0.x | Maven 4.0.0-rc-7 bundles 2.0.23. |
+| Your own application | Resolver 2.0.x | Use a supplier module to bootstrap,
see below. |
+
+The API, SPI and Util modules of 2.x stay binary compatible with 1.9.x for code
+that does not use anything deprecated in 1.9.x. Everything that 1.9.x marks
+`@Deprecated` is gone in 2.x. The rest of this page walks through the changes
in
+the order you will meet them.
+
+## Step 1: Clean up on the latest 1.9.x first
+
+Build against the latest 1.9.x release with `-Xlint:deprecation` enabled and
+replace every deprecated usage. Each item below has a replacement that already
+exists on 1.9.x, so this step does not require 2.x.
+
+| Deprecated in 1.9.x, removed in 2.x | Replacement |
+|---|---|
+| `org.eclipse.aether.spi.log.Logger`, `LoggerFactory`, `NullLoggerFactory` |
SLF4J. Resolver 2.x logs through SLF4J only. |
+| `org.eclipse.aether.spi.locator.ServiceLocator`, `Service`,
`org.eclipse.aether.impl.DefaultServiceLocator`,
`org.eclipse.aether.impl.guice.AetherModule` | Dependency injection or a
supplier module, see step 2. |
+| No-argument constructors of components, such as `new
DefaultRepositorySystem()`, `new BasicRepositoryConnectorFactory()`, `new
HttpTransporterFactory()`, `new WagonTransporterFactory()` | Components use
constructor injection only. Obtain them from the injector or from
`RepositorySystemSupplier`. |
+| `org.eclipse.aether.transform.FileTransformer`, `FileTransformerManager`,
`TransformException`, `RepositorySystemSession#getFileTransformerManager()` |
Removed without a direct replacement. Maven 4 builds its consumer POM itself.
For install and deploy time changes implement the
`org.eclipse.aether.spi.artifact.transformer.ArtifactTransformer` SPI (since
2.0.5). To add generated artifacts such as signatures implement
`org.eclipse.aether.spi.artifact.generator.ArtifactGeneratorFactory`. |
+| `org.eclipse.aether.spi.connector.checksum.ProvidedChecksumsSource` |
`org.eclipse.aether.spi.checksums.ProvidedChecksumsSource` |
+| `org.eclipse.aether.impl.SyncContextFactory` |
`org.eclipse.aether.spi.synccontext.SyncContextFactory` |
+| `org.eclipse.aether.util.StringUtils` | Removed. Use your own helper or the
JDK. |
+| `TransferResource(String repositoryUrl, String resourceName, File file,
RequestTrace trace)` | The constructor that also takes the repository id. In
2.x the file argument is a `Path`. |
+| `ChecksumFailureException(String expected, String actual)` |
`ChecksumFailureException(String expected, String expectedKind, String actual)`
on 1.9.x. On 2.x prefer the factory methods `mismatch`, `noneAvailable` and
`processingFailure`. |
+| `DefaultMirrorSelector#add` with six arguments | The overload that also
takes the `blocked` flag. |
+| `ChecksumUtils#read(File)`, `ChecksumUtils#calc(...)` | `ChecksumProcessor`
and `ChecksumAlgorithmFactorySelector` from the SPI module. On 2.x the whole
`ChecksumUtils` class is deprecated; `StringDigestUtil` covers the string
digests. |
+
+## Step 2: Bootstrap without the service locator
+
+Inside Maven nothing changes: inject `RepositorySystem` and take the session
from
+the `repositorySystemSession` parameter, as the [plugin
guide](using-resolver-in-maven-plugins.html) shows.
+
+Outside Maven the service locator is gone. The 1.9.x `maven-resolver-supplier`
+module became two modules, both exposing
`org.eclipse.aether.supplier.RepositorySystemSupplier`
+and `org.eclipse.aether.supplier.SessionBuilderSupplier`:
+
+| Module | Scope semantics | Java |
+|---|---|---|
+| `maven-resolver-supplier-mvn3` | Maven 3: `compile`, `provided`, `runtime`,
`test`, `system`, with `test` and `provided` dropped transitively | 8 |
+| `maven-resolver-supplier-mvn4` | Maven 4: the Maven 4 build scopes and
resolution scopes | 17 |
+
+Choose `mvn3` when the application must resolve exactly like Maven 3 did, for
+example a tool that compares its result with `dependency:tree`. Choose `mvn4`
+when it should behave like Maven 4. The `mvn3` module also carries the
deprecated
+`org.eclipse.aether.spi.locator` interfaces as linkage shims, so Maven 3 code
that
+references them still loads; Resolver never calls them.
+
+```java
+RepositorySystem system = new RepositorySystemSupplier().get();
+RepositorySystemSession.SessionBuilder builder = new
SessionBuilderSupplier(system)
+ .get()
+ .withLocalRepositoryBaseDirectories(Paths.get("target/local-repo"));
+try (RepositorySystemSession.CloseableSession session = builder.build()) {
+ // use system and session
+}
+system.shutdown();
+```
+
+Both suppliers are plain classes you can subclass to swap a component, which is
+what `DefaultServiceLocator#setServices` used to do. Applications that already
+use Eclipse Sisu or Guice keep injecting `RepositorySystem`: the components
carry
+`javax.inject` annotations and a Sisu index, and `AetherModule` is not needed.
## Session handling changes
Maven Resolver 2.x introduced "onSessionEnd" hooks, that became required for
-some of the new features (like HTTP/2 transports are). While existing
"Resolver 1.x"
-way of handling session will still work, it may produce resource leaks.
+some of the new features (like HTTP/2 transports are). While the existing
"Resolver 1.x"
Review Comment:
💬 **Grammar nit** (the PR edited this sentence): `"(like HTTP/2 transports
are)"` has no predicate complement — the sentence reads: *"some of the new
features (like HTTP/2 transports are)"*. The PR already polished the
surrounding text; consider:
```suggestion
some of the new features (the HTTP/2 transport being one example). While the
existing "Resolver 1.x"
```
--
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]
