This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch agent/upgrade-guide in repository https://gitbox.apache.org/repos/asf/maven-resolver.git
commit 1e04caac2fbbd28f48e8e2b26bc929b80a865c4d 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 | 44 +++- .../graph/selector/OptionalDependencySelector.java | 6 +- .../graph/selector/ScopeDependencySelector.java | 7 +- src/site/markdown/api-compatibility.md | 2 +- src/site/markdown/upgrading-resolver.md | 234 ++++++++++++++++++--- .../markdown/using-resolver-in-maven-plugins.md | 38 +++- 10 files changed, 316 insertions(+), 40 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..9f9b7d9d9 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 {@code @TempDir} (JUnit 5) or {@code TemporaryFolder} (JUnit 4) instead, which clean 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) { @@ -129,11 +143,11 @@ public class TestFileUtils { return createTempFile(contents.getBytes(StandardCharsets.UTF_8), 1); } - @Deprecated /** * @throws IOException if an I/O error occurs - * @deprecated use @TempDir (JUnit 5) Or TemporaryFolder (JUnit 4) instead + * @deprecated use {@code @TempDir} (JUnit 5) or {@code TemporaryFolder} (JUnit 4) instead */ + @Deprecated public static File createTempFile(byte[] pattern, int repeat) throws IOException { mkdirs(TMP); File tmpFile = File.createTempFile("tmpfile-", ".data", TMP); @@ -208,6 +222,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 +247,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..b446964a2 100644 --- a/src/site/markdown/upgrading-resolver.md +++ b/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" +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 +116,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..15bf80270 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,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. | +| 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 Maven 4 + +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 both lines: + +* Compile against 1.9.x and keep calling `getFile()`, `setFile(File)` and + `new LocalRepository(File)`. They work unchanged in Maven 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 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 4. + Next, in your mojo source, you need to inject the repository related components and parameters:
