This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-resolver.git

commit 5772b23fd2e7ab66c0bfcce675a52db94bbaa61e
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Nov 7 22:43:42 2026 +0100

    Rewrite the 1.x to 2.x upgrade guide and point deprecated API at its 
replacements
    
    The page still called 2.x upcoming and said that ArtifactProperties,
    DefaultArtifactType and the DependencyFilterUtils class path filters are
    deprecated and that dependency scopes are removed. None of that holds on the
    2.x line: scopes are delegated to ScopeManager and the Maven 3 helpers stay.
    The configuration key renames of 2.0.0 were documented nowhere.
---
 .../impl/collect/DefaultVersionFilterContext.java  |   3 +
 .../synccontext/named/NamedLockFactoryAdapter.java |  10 +-
 .../org/eclipse/aether/spi/locator/Service.java    |   6 +-
 .../eclipse/aether/spi/locator/ServiceLocator.java |   6 +-
 .../aether/internal/test/util/TestFileUtils.java   |  59 +++++-
 .../graph/selector/OptionalDependencySelector.java |   6 +-
 .../graph/selector/ScopeDependencySelector.java    |   7 +-
 src/site/markdown/api-compatibility.md             |   2 +-
 src/site/markdown/upgrading-resolver.md            | 235 ++++++++++++++++++---
 .../markdown/using-resolver-in-maven-plugins.md    |  40 +++-
 10 files changed, 331 insertions(+), 43 deletions(-)

diff --git 
a/maven-resolver-impl/src/main/java/org/eclipse/aether/internal/impl/collect/DefaultVersionFilterContext.java
 
b/maven-resolver-impl/src/main/java/org/eclipse/aether/internal/impl/collect/DefaultVersionFilterContext.java
index e872d054a..84ccc59f8 100644
--- 
a/maven-resolver-impl/src/main/java/org/eclipse/aether/internal/impl/collect/DefaultVersionFilterContext.java
+++ 
b/maven-resolver-impl/src/main/java/org/eclipse/aether/internal/impl/collect/DefaultVersionFilterContext.java
@@ -63,6 +63,9 @@ public final class DefaultVersionFilterContext implements 
VersionFilter.VersionF
 
     /**
      * The use of this method allows strictly single-threaded use of context. 
Is unused in production, only in tests.
+     *
+     * @deprecated Use {@link #initialize(Dependency, VersionRangeResult)} 
instead, which creates a new context and
+     * is safe to use from several threads.
      */
     @Deprecated
     public void set(Dependency dependency, VersionRangeResult result) {
diff --git 
a/maven-resolver-impl/src/main/java/org/eclipse/aether/internal/impl/synccontext/named/NamedLockFactoryAdapter.java
 
b/maven-resolver-impl/src/main/java/org/eclipse/aether/internal/impl/synccontext/named/NamedLockFactoryAdapter.java
index 1fc168eed..cba11733d 100644
--- 
a/maven-resolver-impl/src/main/java/org/eclipse/aether/internal/impl/synccontext/named/NamedLockFactoryAdapter.java
+++ 
b/maven-resolver-impl/src/main/java/org/eclipse/aether/internal/impl/synccontext/named/NamedLockFactoryAdapter.java
@@ -55,11 +55,14 @@ public final class NamedLockFactoryAdapter {
      * @since 1.7.0
      * @configurationSource {@link 
RepositorySystemSession#getConfigProperties()}
      * @configurationType {@link java.lang.Long}
-     * @deprecated
+     * @deprecated Use {@code aether.system.named.time} instead.
      */
     @Deprecated
     public static final String CONFIG_PROP_TIME = CONFIG_PROPS_PREFIX + "time";
 
+    /**
+     * @deprecated Use {@link 
DefaultNamedLockFactorySelector#DEFAULT_LOCK_WAIT_TIME} instead.
+     */
     @Deprecated
     public static final long DEFAULT_TIME = 
DefaultNamedLockFactorySelector.DEFAULT_LOCK_WAIT_TIME;
 
@@ -70,11 +73,14 @@ public final class NamedLockFactoryAdapter {
      * @since 1.7.0
      * @configurationSource {@link 
RepositorySystemSession#getConfigProperties()}
      * @configurationType {@link java.lang.String}
-     * @deprecated
+     * @deprecated Use {@code aether.system.named.timeUnit} instead.
      */
     @Deprecated
     public static final String CONFIG_PROP_TIME_UNIT = CONFIG_PROPS_PREFIX + 
"time.unit";
 
+    /**
+     * @deprecated Use {@link 
DefaultNamedLockFactorySelector#DEFAULT_LOCK_WAIT_TIME_UNIT} instead.
+     */
     @Deprecated
     public static final String DEFAULT_TIME_UNIT = 
DefaultNamedLockFactorySelector.DEFAULT_LOCK_WAIT_TIME_UNIT;
 
diff --git 
a/maven-resolver-supplier-mvn3/src/main/java/org/eclipse/aether/spi/locator/Service.java
 
b/maven-resolver-supplier-mvn3/src/main/java/org/eclipse/aether/spi/locator/Service.java
index 1b53edf1b..ae1ad2215 100644
--- 
a/maven-resolver-supplier-mvn3/src/main/java/org/eclipse/aether/spi/locator/Service.java
+++ 
b/maven-resolver-supplier-mvn3/src/main/java/org/eclipse/aether/spi/locator/Service.java
@@ -19,9 +19,13 @@
 package org.eclipse.aether.spi.locator;
 
 /**
- * This class here is merely to provide backward compatibility to Maven3. 
Pretend is not here.
+ * Binary-compatibility shim for Maven 3 code that still links against the 
Resolver 1.x locator-aware service API.
+ * Resolver 2.x does not provide a service locator: this interface is never 
implemented or looked up by Resolver
+ * itself, and it is not available on the class path of applications that do 
not use this module.
  *
  * @since 2.0.0
+ * @deprecated Use JSR-330 dependency injection (Eclipse Sisu, Guice) or
+ * {@link org.eclipse.aether.supplier.RepositorySystemSupplier} to obtain a 
{@code RepositorySystem}.
  */
 @Deprecated
 public interface Service {}
diff --git 
a/maven-resolver-supplier-mvn3/src/main/java/org/eclipse/aether/spi/locator/ServiceLocator.java
 
b/maven-resolver-supplier-mvn3/src/main/java/org/eclipse/aether/spi/locator/ServiceLocator.java
index fc79dfdcf..991cb3e26 100644
--- 
a/maven-resolver-supplier-mvn3/src/main/java/org/eclipse/aether/spi/locator/ServiceLocator.java
+++ 
b/maven-resolver-supplier-mvn3/src/main/java/org/eclipse/aether/spi/locator/ServiceLocator.java
@@ -21,9 +21,13 @@ package org.eclipse.aether.spi.locator;
 import java.util.List;
 
 /**
- * This class here is merely to provide backward compatibility to Maven3. 
Pretend is not here.
+ * Binary-compatibility shim for Maven 3 code that still links against the 
Resolver 1.x service locator API.
+ * Resolver 2.x does not provide a service locator: this interface is never 
implemented or looked up by Resolver
+ * itself, and it is not available on the class path of applications that do 
not use this module.
  *
  * @since 2.0.0
+ * @deprecated Use JSR-330 dependency injection (Eclipse Sisu, Guice) or
+ * {@link org.eclipse.aether.supplier.RepositorySystemSupplier} to obtain a 
{@code RepositorySystem}.
  */
 @Deprecated
 public interface ServiceLocator {
diff --git 
a/maven-resolver-test-util/src/main/java/org/eclipse/aether/internal/test/util/TestFileUtils.java
 
b/maven-resolver-test-util/src/main/java/org/eclipse/aether/internal/test/util/TestFileUtils.java
index 1fd17d7d7..4509d52b6 100644
--- 
a/maven-resolver-test-util/src/main/java/org/eclipse/aether/internal/test/util/TestFileUtils.java
+++ 
b/maven-resolver-test-util/src/main/java/org/eclipse/aether/internal/test/util/TestFileUtils.java
@@ -55,6 +55,13 @@ public class TestFileUtils {
         // hide constructor
     }
 
+    /**
+     * Deletes the files created by the temp-file helpers of this class.
+     *
+     * @throws IOException if an I/O error occurs
+     * @deprecated use the JUnit 5 {@code @TempDir} extension instead, which 
cleans up after
+     * themselves
+     */
     @Deprecated
     public static void deleteTempFiles() throws IOException {
         deleteFile(TMP);
@@ -96,6 +103,13 @@ public class TestFileUtils {
         return false;
     }
 
+    /**
+     * Creates a directory and its missing parents.
+     *
+     * @param directory the directory to create
+     * @return {@code true} if the directory exists afterwards
+     * @deprecated use {@code Files.createDirectories(Path)} instead
+     */
     @Deprecated
     public static boolean mkdirs(File directory) {
         if (directory == null) {
@@ -121,19 +135,28 @@ public class TestFileUtils {
     }
 
     /**
+     * Creates a temporary file with the given UTF-8 content.
+     *
+     * @param contents the content to write
+     * @return the temporary file
      * @throws IOException if an I/O error occurs
-     * @deprecated use @TempDir (JUnit 5) Or TemporaryFolder (JUnit 4) instead
+     * @deprecated use the JUnit 5 {@code @TempDir} extension instead
      */
     @Deprecated
     public static File createTempFile(String contents) throws IOException {
         return createTempFile(contents.getBytes(StandardCharsets.UTF_8), 1);
     }
 
-    @Deprecated
     /**
+     * Creates a temporary file holding the byte pattern the given number of 
times.
+     *
+     * @param pattern the bytes to repeat
+     * @param repeat how many times the pattern is written
+     * @return the temporary file
      * @throws IOException if an I/O error occurs
-     * @deprecated use @TempDir (JUnit 5) Or TemporaryFolder (JUnit 4) instead
+     * @deprecated use the JUnit 5 {@code @TempDir} extension instead
      */
+    @Deprecated
     public static File createTempFile(byte[] pattern, int repeat) throws 
IOException {
         mkdirs(TMP);
         File tmpFile = File.createTempFile("tmpfile-", ".data", TMP);
@@ -146,7 +169,7 @@ public class TestFileUtils {
      *
      * @return the temporary directory
      * @throws IOException if an I/O error occurs
-     * @deprecated use @TempDir (JUnit 5) Or TemporaryFolder (JUnit 4) instead
+     * @deprecated use the JUnit 5 {@code @TempDir} extension instead
      */
     @Deprecated
     public static File createTempDir() throws IOException {
@@ -158,7 +181,7 @@ public class TestFileUtils {
      *
      * @return the temporary directory
      * @throws IOException if an I/O error occurs
-     * @deprecated use {@code @TempDir} (JUnit 5) or {@code TemporaryFolder} 
(JUnit 4) instead
+     * @deprecated use the JUnit 5 {@code @TempDir} extension instead
      */
     @Deprecated
     public static File createTempDir(String suffix) throws IOException {
@@ -208,6 +231,15 @@ public class TestFileUtils {
         }
     }
 
+    /**
+     * Writes a byte pattern to a file the given number of times.
+     *
+     * @param file the file to write
+     * @param pattern the bytes to repeat
+     * @param repeat how many times the pattern is written
+     * @throws IOException if an I/O error occurs
+     * @deprecated use {@code Files.write(Path, byte[])} instead
+     */
     @Deprecated
     public static void writeBytes(File file, byte[] pattern, int repeat) 
throws IOException {
         file.deleteOnExit();
@@ -224,11 +256,28 @@ public class TestFileUtils {
         return new String(content, StandardCharsets.UTF_8);
     }
 
+    /**
+     * Writes a UTF-8 string to a file.
+     *
+     * @param file the file to write
+     * @param content the content to write
+     * @throws IOException if an I/O error occurs
+     * @deprecated use {@code Files.write(Path, byte[])} instead
+     */
     @Deprecated
     public static void writeString(File file, String content) throws 
IOException {
         writeBytes(file, content.getBytes(StandardCharsets.UTF_8), 1);
     }
 
+    /**
+     * Writes a UTF-8 string to a file and sets its last-modified time.
+     *
+     * @param file the file to write
+     * @param content the content to write
+     * @param timestamp the last-modified time to set, in milliseconds since 
the epoch
+     * @throws IOException if an I/O error occurs
+     * @deprecated use {@code Files.write(Path, byte[])} and {@code 
Files.setLastModifiedTime(Path, FileTime)} instead
+     */
     @Deprecated
     public static void writeString(File file, String content, long timestamp) 
throws IOException {
         writeBytes(file, content.getBytes(StandardCharsets.UTF_8), 1);
diff --git 
a/maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/selector/OptionalDependencySelector.java
 
b/maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/selector/OptionalDependencySelector.java
index 6ac25e815..e0889acd1 100644
--- 
a/maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/selector/OptionalDependencySelector.java
+++ 
b/maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/selector/OptionalDependencySelector.java
@@ -28,7 +28,11 @@ import static java.util.Objects.requireNonNull;
  * A dependency selector that excludes optional dependencies which occur 
beyond level one of the dependency graph.
  *
  * @see Dependency#isOptional()
- * @deprecated this class is deprecated. Use same named class from impl module 
instead.
+ * @deprecated Scope semantics belong to the consumer project since Resolver 
2.0.0. Obtain the selector from
+ * {@link 
org.eclipse.aether.scope.ScopeManager#getDependencySelector(org.eclipse.aether.RepositorySystemSession,
+ * org.eclipse.aether.scope.ResolutionScope)}, or use the session created by 
the {@code SessionBuilderSupplier} of
+ * the {@code maven-resolver-supplier-mvn3} or {@code 
maven-resolver-supplier-mvn4} module, which already carries the
+ * Maven scope-aware selectors.
  */
 @Deprecated
 public final class OptionalDependencySelector implements DependencySelector {
diff --git 
a/maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/selector/ScopeDependencySelector.java
 
b/maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/selector/ScopeDependencySelector.java
index 8c796d8d6..aa3f0d2f2 100644
--- 
a/maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/selector/ScopeDependencySelector.java
+++ 
b/maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/selector/ScopeDependencySelector.java
@@ -37,8 +37,11 @@ import static java.util.Objects.requireNonNull;
  * In particular, the filter is not aware of scopes that logically include 
other scopes.
  *
  * @see Dependency#getScope()
- * @deprecated this class is deprecated. Use same named class from impl module 
instead.
- * @see 
org.eclipse.aether.scope.ScopeManager#getDependencySelector(org.eclipse.aether.RepositorySystemSession,
 org.eclipse.aether.scope.ResolutionScope)
+ * @deprecated Scope semantics belong to the consumer project since Resolver 
2.0.0. Obtain the selector from
+ * {@link 
org.eclipse.aether.scope.ScopeManager#getDependencySelector(org.eclipse.aether.RepositorySystemSession,
+ * org.eclipse.aether.scope.ResolutionScope)}, or use the session created by 
the {@code SessionBuilderSupplier} of
+ * the {@code maven-resolver-supplier-mvn3} or {@code 
maven-resolver-supplier-mvn4} module, which already carries the
+ * Maven scope-aware selectors.
  */
 @Deprecated
 public final class ScopeDependencySelector implements DependencySelector {
diff --git a/src/site/markdown/api-compatibility.md 
b/src/site/markdown/api-compatibility.md
index ecc850a54..c502364fd 100644
--- a/src/site/markdown/api-compatibility.md
+++ b/src/site/markdown/api-compatibility.md
@@ -98,4 +98,4 @@ This incompatibility affects the Connector module and the 
`impl` module.
 Maven Resolver uses 
[JApiCmp](https://siom79.github.io/japicmp/MavenPlugin.html) to verify backward 
compatibility.
 Starting with version 1.9.0, Maven Resolver runs this plugin twice to verify 
source compatibility and binary compatibility.
 The plugin runs on the API, SPI, and Util modules.
-The compatibility baseline is version 1.8.0.
+On the 2.x line the compatibility baseline is version 1.9.18, set in the root 
POM.
diff --git a/src/site/markdown/upgrading-resolver.md 
b/src/site/markdown/upgrading-resolver.md
index a325befe7..e917c15f1 100644
--- a/src/site/markdown/upgrading-resolver.md
+++ b/src/site/markdown/upgrading-resolver.md
@@ -16,24 +16,93 @@
  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 3.10 and Maven 4 ship. 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 Maven 3.9 as well as in Maven 
3.10 or 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 3.10.x | Resolver 2.0.x | Maven 3.10.0 bundles 2.0.24. |
+| 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"
+way of handling sessions still works, it may produce resource leaks.
 Client code **managing Resolver** (like Maven) is strongly advised to upgrade
-session handling. Client code **using Resolver** (like Maven Mojos) 
-do not have to change anything, they should be able to continue to 
-function in very same way as before (as with Resolver 1.x).
+session handling. Client code **using Resolver** (like Maven Mojos)
+does not have to change anything, it continues to function in the very same way
+as before (as with Resolver 1.x).
 
 What changed on surface:
 * introduction of `RepositorySystemSession` nested interfaces 
`CloseableSession` and `SessionBuilder`.
@@ -48,23 +117,133 @@ Required changes in **consumer project code managing 
Resolver 2.x**:
 * to shallow-copy session instances (for alteration purposes) using existing 
`DefaultRepositorySystemSession` copy constructor is acceptable (this is what 
Mojos do).
 * to shallow-copy session instances but have new lifecycle as well, use 
`SessionBuilder#withRepositorySystemSession` on newly created builder instances.
 
+## Step 3: Move from File to Path
+
+Resolver 2.0.0 switched its API, SPI and Util modules from `java.io.File` to
+`java.nio.file.Path`. Every `File` method is still there and deprecated, 
delegating
+to the `Path` one, so existing binaries keep working. Replace them when you 
move
+to 2.x; the table lists the renames.
+
+| Module | Deprecated | Replacement |
+|---|---|---|
+| API | `Artifact#getFile()`, `Artifact#setFile(File)` | `getPath()`, 
`setPath(Path)` |
+| API | `Metadata#getFile()`, `Metadata#setFile(File)`, 
`MergeableMetadata#merge(File, File)` | `getPath()`, `setPath(Path)`, 
`merge(Path, Path)` |
+| API | `DefaultMetadata` constructors taking `File` | The same constructors 
taking `Path` |
+| API | `LocalRepository(String)`, `LocalRepository(File)`, 
`LocalRepository(File, String)`, `LocalRepository#getBasedir()` | 
`LocalRepository(Path)`, `LocalRepository(Path, String)`, `getBasePath()` |
+| API | `LocalArtifactResult` and `LocalMetadataResult` `getFile()`, 
`setFile(File)` | `getPath()`, `setPath(Path)` |
+| API | `LocalRepositoryManager#getPathForLocalArtifact` and the three sibling 
`getPathFor*` methods returning `String` | `getAbsolutePathForLocalArtifact` 
and siblings returning `Path` |
+| API | `RepositoryEvent#getFile()`, `RepositoryEvent.Builder#setFile(File)` | 
`getPath()`, `setPath(Path)` |
+| API | `TransferResource#getFile()`, 
`TransferResource#getTransferStartTime()`, the constructor taking `File` | 
`getPath()`, `getStartTime()`, the constructor taking `Path` |
+| SPI | `ArtifactDownload`, `ArtifactUpload`, `MetadataDownload`, 
`MetadataUpload` constructors taking `File`, and `setFile(File)` on them and on 
`ArtifactTransfer`, `MetadataTransfer` | The `Path` constructors, 
`setPath(Path)`, `getPath()` |
+| SPI | `GetTask#getDataFile()`, `GetTask#setDataFile(...)`, 
`PutTask#getDataFile()`, `PutTask#setDataFile(File)` | `getDataPath()`, 
`setDataPath(...)` |
+| SPI | `FileProcessor` | `PathProcessor` for file operations, 
`ChecksumProcessor` for checksum files |
+| Util | `NodeListGenerator#getFiles()` | `getPaths()` |
+
+A plugin that must still run on Maven 3.9 cannot call `getPath()`, because 
Maven
+3.9 ships Resolver 1.9.x without it. Keep `getFile()` there and suppress the
+warning; the plugin guide explains the options.
+
+## Step 4: Replace the deprecated Util helpers
+
+| Deprecated in 2.x | Replacement |
+|---|---|
+| `PreorderNodeListGenerator`, `PostorderNodeListGenerator` | 
`PreorderDependencyNodeConsumerVisitor` and 
`PostorderDependencyNodeConsumerVisitor` feeding a `NodeListGenerator`; 
`LevelOrderDependencyNodeConsumerVisitor` matches the order Resolver 2.x uses 
for class paths. |
+| `NearestVersionSelector` | `ConfigurableVersionSelector`, which also offers 
the "highest" strategy. |
+| `PredicateVersionFilter` | `ArtifactPredicateVersionFilter` |
+| `ScopeDependencySelector`, `OptionalDependencySelector` in 
`org.eclipse.aether.util.graph.selector` | The selectors a supplier session 
already carries, or `ScopeManager#getDependencySelector(session, 
resolutionScope)`. Scope semantics belong to the consumer project in 2.x. |
+| `ContextualSnapshotVersionFilter#CONFIG_PROP_ENABLE` 
(`aether.snapshotFilter`) | Add a `SnapshotVersionFilter` to the session to ban 
snapshots. |
+| `ChecksumUtils`, `FileUtils`, `ExecutorUtils` | `StringDigestUtil`, the 
`org.eclipse.aether.spi.io` processors, and the JDK. Resolver no longer uses 
these classes. |
+| `RepositoryPolicy#getUpdatePolicy()` | `getArtifactUpdatePolicy()` and 
`getMetadataUpdatePolicy()`. Resolver 2.x keeps the two policies apart; the old 
method returns the artifact one. |
+| `ArtifactResult#addException(Exception)` | `addException(ArtifactRepository, 
Exception)`, so the failure is attributed to a repository. |
+| `UnsolvableVersionConflictException(Collection)` | 
`UnsolvableVersionConflictException(String, Collection)` with a message. |
+| `BasicRepositoryConnectorConfigurationKeys#CONFIG_PROP_THREADS` 
(`aether.connector.basic.threads`) | `CONFIG_PROP_UPSTREAM_THREADS` and 
`CONFIG_PROP_DOWNSTREAM_THREADS` |
+
 ## Consumer Project Changes (if more needed)
 
-Maven Resolver 2.x now fully delegates multiple aspects to the consumer 
project, itself remaining "oblivious" about
-them. This was done to lessen (or better, fully remove) any overlap between 
the logic of the Resolver, and its major
-consumer project: Maven. The following aspects are fully delegated to consumer 
projects:
-* Most of the `ArtifactProperties` is deprecated (except two "core" ones: type 
and language), as it is really a matter of the consumer project to assign 
semantics to them.
-* The `ArtifactType` default implementation is deprecated, should be provided 
by consumer project instead, Resolver 2.x should not provide implementations 
for it.
-* Class path generation (in NodeListGenerator class variations in 
`org.eclipse.aether.util.graph.visitor` package) and class path filtering (in 
`DependencyFilterUtils`) is deprecated. It is the consumer app, based on own 
artifact properties, that can deduce how to build class path (or module path, 
or anything alike).
-* Dependency Scopes are fully removed. For Resolver, they were always "just 
labels". Resolver is now fully unaware of scopes (and for "system" artifacts 
has a dedicated handler exposed on session).
-
-For users of Maven Resolver Provider module, these changes will have clean 
migration path, as all the replacements for 
-items from the list above are present in 
`org.apache.maven:maven-resolver-provider` module. Still, for binary 
-compatibility, all affected classes are in fact left in place, but deprecated. 
Consumer projects should update 
-accordingly, and if they do use any deprecated classes from the resolver 
(affected modules are maven-resolver-api 
-and maven-resolver-util), they should switch to their counterparts, that are 
now present in maven-resolver-provider 
-module.
-
-Note: Resolver 2.x still fully supports "legacy" (Maven3-like) functionality, 
and if existing consumer
-code base adapts only the session related changes, consumer project can enjoy 
new features (like HTTP/2 transport),
-while keeping full compatibility, identical to Resolver 1.x release.
+Resolver 2.x delegates the Maven specific parts of dependency handling to the
+consumer project. Resolver itself treats dependency scopes as labels; the 
meaning
+of `compile`, `test`, or any other scope comes from the `ScopeManager` the
+session carries, and the two supplier modules configure it for Maven 3 and 
Maven 4
+semantics. The same applies to the `system` scope, which has its own
+`SystemDependencyScope` handler on the session.
+
+The Maven 3 era helpers stay available and are not deprecated: `JavaScopes`, 
the
+`ArtifactProperties` constants, `DefaultArtifactType`, and 
`DependencyFilterUtils`
+with its class path filters. They remain the right choice for code that must
+behave like Maven 3, and the `mvn3` supplier builds on them. Code that targets
+Maven 4 should take scopes, types and class path logic from Maven's own
+`maven-resolver-provider` and API instead, so that it agrees with the build it 
runs in.
+
+## Step 5: Update module coordinates
+
+| Resolver 1.9.x | Resolver 2.x |
+|---|---|
+| `maven-resolver-transport-http` (Apache HttpClient 4, package 
`org.eclipse.aether.transport.http`) | `maven-resolver-transport-apache` 
(Apache HttpClient 4, package `org.eclipse.aether.transport.apache`, factory 
`ApacheTransporterFactory`). The connector configuration keys moved, see step 
6. |
+| `maven-resolver-supplier` | `maven-resolver-supplier-mvn3` or 
`maven-resolver-supplier-mvn4`, see step 2. |
+| `maven-resolver-transport-wagon`, `maven-resolver-transport-file`, 
`maven-resolver-transport-classpath` | Unchanged coordinates; the configuration 
keys moved to the `aether.transport.*` namespace. |
+| `maven-resolver-named-locks-hazelcast` | Deprecated, support will be 
dropped. Use the default file locks, `maven-resolver-named-locks-ipc` (Java 17) 
for a lock daemon shared between JVMs, or `maven-resolver-named-locks-redisson` 
(Java 11). |
+
+New in 2.x, all optional:
+
+* `maven-resolver-transport-jdk`: HTTP/1.1 and HTTP/2 through `java.net.http`, 
a multi-release jar that is defunct on Java 8 and active on Java 11 and later. 
HTTP/3 since 2.0.21 on JDKs that support it.
+* `maven-resolver-transport-jetty`: HTTP/2 and HTTP/3 through Jetty, Java 17.
+* `maven-resolver-transport-url`: a small `java.net.URL` transport, Java 8.
+* `maven-resolver-transport-minio`: native S3 transport.
+* `maven-resolver-generator-gnupg` and `maven-resolver-generator-sigstore`: 
sign artifacts at deploy time, Java 17.
+
+When more than one HTTP transport is on the class path the highest priority 
wins:
+Jetty (15), then JDK (10), then Apache (5). The Wagon and URL transports have a
+negative priority and only serve when nothing else can. Set the 
`aether.priority.*`
+properties to change the order.
+
+## Step 6: Rename configuration keys
+
+The 2.x keys live under `aether.transport.*` for transports and `aether.lrm.*`,
+`aether.named.*`, `aether.system.*` for the rest. The full, generated list with
+defaults and the version each key appeared in is on the
+[Configuration Options](configuration.html) page. The renames below are the 
ones a
+1.9.x `settings.xml`, `.mvn/maven.config` or session setup is likely to 
contain.
+
+Resolver 2.x still reads the old key for the rows marked "yes" in the last 
column.
+Every other old key is ignored silently, so grep your configuration for
+`aether.connector.` and `aether.enhancedLocalRepository.` before upgrading.
+
+| Resolver 1.9.x key | Resolver 2.x key | Old key still read |
+|---|---|---|
+| `aether.connector.connectTimeout` | `aether.transport.http.connectTimeout` | 
no |
+| `aether.connector.requestTimeout` | `aether.transport.http.requestTimeout` | 
no |
+| `aether.connector.userAgent` | `aether.transport.http.userAgent` | yes |
+| `aether.connector.http.headers` (and `.headers.<repoId>`) | 
`aether.transport.http.headers` | no |
+| `aether.connector.http.preemptiveAuth`, `.preemptivePutAuth` | 
`aether.transport.http.preemptiveAuth`, `.preemptivePutAuth` | no |
+| `aether.connector.http.reuseConnections`, `.connectionMaxTtl`, 
`.maxConnectionsPerRoute` | `aether.transport.http.reuseConnections`, 
`.connectionMaxTtl`, `.maxConnectionsPerRoute` | no |
+| `aether.connector.http.expectContinue`, `.credentialEncoding`, 
`.supportWebDav` | `aether.transport.http.expectContinue`, 
`.credentialEncoding`, `.supportWebDav` | no |
+| `aether.connector.http.retryHandler.count`, `.interval`, `.intervalMax`, 
`.serviceUnavailable` | `aether.transport.http.retryHandler.count`, 
`.interval`, `.intervalMax`, `.serviceUnavailable` | no |
+| `aether.connector.http.retryHandler.name`, `.requestSentEnabled` | 
`aether.transport.apache.retryHandler.name`, `.requestSentEnabled` | no |
+| `aether.connector.http.followRedirects`, `.maxRedirects`, 
`.useSystemProperties` | `aether.transport.apache.followRedirects`, 
`.maxRedirects`, `.useSystemProperties` | no |
+| `aether.connector.bind.address` | `aether.transport.http.localAddress` | no |
+| `aether.connector.http.cacheState` | Removed. | no |
+| `aether.connector.https.securityMode` | 
`aether.transport.https.securityMode` | no |
+| `aether.connector.https.cipherSuites`, `.protocols` | 
`aether.transport.apache.https.cipherSuites`, `.protocols` | no |
+| `aether.connector.wagon.config` | `aether.transport.wagon.config` | no |
+| `aether.connector.perms.fileMode`, `.dirMode`, `.group` | 
`aether.transport.wagon.perms.fileMode`, `.dirMode`, `.group` | no |
+| `aether.connector.classpath.loader` | `aether.transport.classpath.loader` | 
no |
+| `aether.connector.persistedChecksums` | 
`aether.connector.basic.persistedChecksums` | no |
+| `aether.connector.smartChecksums` | 
`aether.connector.basic.includedChecksums` | yes |
+| `aether.connector.basic.threads` | `aether.connector.basic.upstreamThreads` 
and `.downstreamThreads` | yes, deprecated |
+| `aether.checksums.algorithms` | `aether.checksums.checksumAlgorithms` | yes |
+| `aether.enhancedLocalRepository.*` (`split`, `splitLocal`, `splitRemote`, 
`localPrefix`, `remotePrefix`, `releasesPrefix`, `snapshotsPrefix`, 
`splitRemoteRepository`, `splitRemoteRepositoryLast`, `trackingFilename`) | 
`aether.lrm.enhanced.*` with the same suffixes | yes |
+| `aether.syncContext.named.time`, `.time.unit` | `aether.system.named.time`, 
`.timeUnit` | yes, deprecated |
+| `aether.remoteRepositoryFilter.groupId.truncateOnSave` | Removed. | no |
+
+## Behaviour changes to expect
+
+These defaults changed between 1.9.x and 2.0.x. None of them needs a code 
change,
+but each can change what a build resolves or how fast it runs. The
+[Resolver 2.0.x Notable Features](release-highlights.html) page has the full 
list.
+
+* The breadth-first collector is the default; 
`aether.dependencyCollector.impl=df` restores the old one.
+* Named locks default to file locks with the GAECV name mapper.
+* Remote repository filtering is on by default.
+* Artifact and metadata update policies are separate.
+* `WarnChecksumPolicy` proceeds when a repository serves no checksums at all.
+* Class path order follows the level-order graph visitor.
diff --git a/src/site/markdown/using-resolver-in-maven-plugins.md 
b/src/site/markdown/using-resolver-in-maven-plugins.md
index 9c0f7c8b6..9c078003a 100644
--- a/src/site/markdown/using-resolver-in-maven-plugins.md
+++ b/src/site/markdown/using-resolver-in-maven-plugins.md
@@ -35,14 +35,14 @@ start, add the following dependencies to the plugin POM:
       <!-- required in all cases -->
       <groupId>org.apache.maven.resolver</groupId>
       <artifactId>maven-resolver-api</artifactId>
-      <version>1.9.22</version>
+      <version>1.9.27</version>
       <scope>provided</scope>
     </dependency>
     <dependency>
       <!-- optional helpers, might be superfluous depending on your use case 
-->
       <groupId>org.apache.maven.resolver</groupId>
       <artifactId>maven-resolver-util</artifactId>
-      <version>1.9.22</version>
+      <version>1.9.27</version>
       <!-- Scope: use compile to make plugin work in Maven 3.8 and earlier -->
       <scope>compile</scope>
     </dependency>
@@ -57,6 +57,42 @@ 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 Maven lines ship
+different Resolver lines:
+
+| Maven | Resolver | Notes |
+|---|---|---|
+| 3.9.x | 1.9.x | Maven 3.9.12 bundles 1.9.25. |
+| 3.10.x | 2.0.x | Maven 3.10.0 bundles 2.0.24. |
+| 4.0.x | 2.0.x | Maven 4.0.0-rc-7 bundles 2.0.23. |
+
+Compile against the Resolver line of the oldest Maven you support. A plugin
+built against 2.0.x that calls a method 1.9.x does not have, such as
+`Artifact#getPath()`, fails with `NoSuchMethodError` inside Maven 3.9.
+
+### Plugins that support Maven 3.9 and later
+
+Resolver 2.x deprecated every `java.io.File` method of the API in favour of
+`java.nio.file.Path`, see [Upgrading Resolver](upgrading-resolver.html). The
+`File` methods still exist in 2.x and delegate to the `Path` ones, while the
+`Path` methods do not exist in 1.9.x. For a plugin that runs in Maven 3.9 as 
well as
+in Maven 3.10 or 4:
+
+* Compile against 1.9.x and keep calling `getFile()`, `setFile(File)` and
+  `new LocalRepository(File)`. They work unchanged in Maven 3.10 and 4.
+* Keep `maven-resolver-api` in `provided` scope and do not shade or bundle any
+  Resolver module; the runtime version is always Maven's.
+* Convert at the boundary: call `artifact.getFile().toPath()` where your own
+  code wants a `Path`.
+* When the plugin drops Maven 3.9 support, raise the dependency to 2.0.x and
+  replace the `File` methods; the `-Xlint:deprecation` warnings point at each
+  call site.
+
+Everything deprecated in 1.9.x is removed in 2.x, so a plugin that compiles
+against 1.9.x without deprecation warnings also loads in Maven 3.10 and 4.
+
 Next, in your mojo source, you need to inject the repository related
 components and parameters:
 

Reply via email to