Maven 4.x w/ Resolver 2.0.14-SNAPSHOT

.mvn/maven.config

@@ -1 +1,2 @@
--DsessionRootDirectory=${session.rootDirectory}
+-DsessionRootDirectory=${session.rootDirectory}
+-Dapache.snapshots

api/maven-api-core/src/main/java/org/apache/maven/api/Constants.java

@@ -545,7 +545,10 @@ public final class Constants {
      *     <li>"release" - query only release repositories to discover versions</li>
      *     <li>"snapshot" - query only snapshot repositories to discover versions</li>
      * </ul>
-     * Default (when unset) is existing Maven behaviour: "release_or_snapshots".
+     * Default (when unset) is using request carried nature. Hence, this configuration really makes sense with value
+     * {@code "auto"}, while ideally callers needs update and use newly added method on version range request to
+     * express preference.
+     *
      * @since 4.0.0
      */
     @Config(defaultValue = "release_or_snapshot")

api/maven-api-core/src/main/java/org/apache/maven/api/services/VersionRangeResolverRequest.java

@@ -32,83 +32,210 @@
 import static java.util.Objects.requireNonNull;
 
 /**
+ * A request to resolve a version range to a list of matching versions.
+ * This request is used by {@link VersionRangeResolver} to expand version ranges
+ * (e.g., "[3.8,4.0)") into concrete versions available in the configured repositories.
  *
  * @since 4.0.0
  */
 @Experimental
 public interface VersionRangeResolverRequest extends RepositoryAwareRequest {
 
+    /**
+     * Specifies which type of repositories to query when resolving version ranges.
+     * This controls whether to search in release repositories, snapshot repositories, or both.
+     *
+     * @since 4.0.0
+     */
+    enum Nature {
+        /**
+         * Query only release repositories to discover versions.
+         */
+        RELEASE,
+        /**
+         * Query only snapshot repositories to discover versions.
+         */
+        SNAPSHOT,
+        /**
+         * Query both release and snapshot repositories to discover versions.
+         * This is the default behavior.
+         */
+        RELEASE_OR_SNAPSHOT
+    }
+
+    /**
+     * Gets the artifact coordinates whose version range should be resolved.
+     * The coordinates may contain a version range (e.g., "[1.0,2.0)") or a single version.
+     *
+     * @return the artifact coordinates, never {@code null}
+     */
     @Nonnull
     ArtifactCoordinates getArtifactCoordinates();
 
+    /**
+     * Gets the nature of repositories to query when resolving the version range.
+     * This determines whether to search in release repositories, snapshot repositories, or both.
+     *
+     * @return the repository nature, never {@code null}
+     */
+    @Nonnull
+    Nature getNature();
+
+    /**
+     * Creates a version range resolver request using the session's repositories.
+     *
+     * @param session the session to use, must not be {@code null}
+     * @param artifactCoordinates the artifact coordinates whose version range should be resolved, must not be {@code null}
+     * @return the version range resolver request, never {@code null}
+     */
     @Nonnull
     static VersionRangeResolverRequest build(
             @Nonnull Session session, @Nonnull ArtifactCoordinates artifactCoordinates) {
-        return build(session, artifactCoordinates, null);
+        return build(session, artifactCoordinates, null, null);
     }
 
+    /**
+     * Creates a version range resolver request.
+     *
+     * @param session the session to use, must not be {@code null}
+     * @param artifactCoordinates the artifact coordinates whose version range should be resolved, must not be {@code null}
+     * @param repositories the repositories to use, or {@code null} to use the session's repositories
+     * @return the version range resolver request, never {@code null}
+     */
     @Nonnull
     static VersionRangeResolverRequest build(
             @Nonnull Session session,
             @Nonnull ArtifactCoordinates artifactCoordinates,
             @Nullable List<RemoteRepository> repositories) {
+        return build(session, artifactCoordinates, repositories, null);
+    }
+
+    /**
+     * Creates a version range resolver request.
+     *
+     * @param session the session to use, must not be {@code null}
+     * @param artifactCoordinates the artifact coordinates whose version range should be resolved, must not be {@code null}
+     * @param repositories the repositories to use, or {@code null} to use the session's repositories
+     * @param nature the nature of repositories to query when resolving the version range, or {@code null} to use the default
+     * @return the version range resolver request, never {@code null}
+     */
+    @Nonnull
+    static VersionRangeResolverRequest build(
+            @Nonnull Session session,
+            @Nonnull ArtifactCoordinates artifactCoordinates,
+            @Nullable List<RemoteRepository> repositories,
+            @Nullable Nature nature) {
         return builder()
                 .session(requireNonNull(session, "session cannot be null"))
                 .artifactCoordinates(requireNonNull(artifactCoordinates, "artifactCoordinates cannot be null"))
                 .repositories(repositories)
+                .nature(nature)
                 .build();
     }
 
+    /**
+     * Creates a new builder for version range resolver requests.
+     *
+     * @return a new builder, never {@code null}
+     */
     @Nonnull
     static VersionResolverRequestBuilder builder() {
         return new VersionResolverRequestBuilder();
     }
 
+    /**
+     * Builder for {@link VersionRangeResolverRequest}.
+     */
     @NotThreadSafe
     class VersionResolverRequestBuilder {
         Session session;
         RequestTrace trace;
         ArtifactCoordinates artifactCoordinates;
         List<RemoteRepository> repositories;
+        Nature nature = Nature.RELEASE_OR_SNAPSHOT;
 
+        /**
+         * Sets the session to use for the request.
+         *
+         * @param session the session, must not be {@code null}
+         * @return this builder, never {@code null}
+         */
         public VersionResolverRequestBuilder session(Session session) {
             this.session = session;
             return this;
         }
 
+        /**
+         * Sets the request trace for debugging and diagnostics.
+         *
+         * @param trace the request trace, may be {@code null}
+         * @return this builder, never {@code null}
+         */
         public VersionResolverRequestBuilder trace(RequestTrace trace) {
             this.trace = trace;
             return this;
         }
 
+        /**
+         * Sets the artifact coordinates whose version range should be resolved.
+         *
+         * @param artifactCoordinates the artifact coordinates, must not be {@code null}
+         * @return this builder, never {@code null}
+         */
         public VersionResolverRequestBuilder artifactCoordinates(ArtifactCoordinates artifactCoordinates) {
             this.artifactCoordinates = artifactCoordinates;
             return this;
         }
 
+        /**
+         * Sets the nature of repositories to query when resolving the version range.
+         * If {@code null} is provided, defaults to {@link Nature#RELEASE_OR_SNAPSHOT}.
+         *
+         * @param nature the repository nature, or {@code null} to use the default
+         * @return this builder, never {@code null}
+         */
+        public VersionResolverRequestBuilder nature(Nature nature) {
+            this.nature = Objects.requireNonNullElse(nature, Nature.RELEASE_OR_SNAPSHOT);
+            return this;
+        }
+
+        /**
+         * Sets the repositories to use for resolving the version range.
+         *
+         * @param repositories the repositories, or {@code null} to use the session's repositories
+         * @return this builder, never {@code null}
+         */
         public VersionResolverRequestBuilder repositories(List<RemoteRepository> repositories) {
             this.repositories = repositories;
             return this;
         }
 
+        /**
+         * Builds the version range resolver request.
+         *
+         * @return the version range resolver request, never {@code null}
+         */
         public VersionRangeResolverRequest build() {
-            return new DefaultVersionResolverRequest(session, trace, artifactCoordinates, repositories);
+            return new DefaultVersionResolverRequest(session, trace, artifactCoordinates, repositories, nature);
         }
 
         private static class DefaultVersionResolverRequest extends BaseRequest<Session>
                 implements VersionRangeResolverRequest {
             private final ArtifactCoordinates artifactCoordinates;
             private final List<RemoteRepository> repositories;
+            private final Nature nature;
 
             @SuppressWarnings("checkstyle:ParameterNumber")
             DefaultVersionResolverRequest(
                     @Nonnull Session session,
                     @Nullable RequestTrace trace,
                     @Nonnull ArtifactCoordinates artifactCoordinates,
-                    @Nullable List<RemoteRepository> repositories) {
+                    @Nullable List<RemoteRepository> repositories,
+                    @Nonnull Nature nature) {
                 super(session, trace);
-                this.artifactCoordinates = artifactCoordinates;
+                this.artifactCoordinates = requireNonNull(artifactCoordinates);
                 this.repositories = validate(repositories);
+                this.nature = requireNonNull(nature);
             }
 
             @Nonnull
@@ -123,23 +250,31 @@ public List<RemoteRepository> getRepositories() {
                 return repositories;
             }
 
+            @Nonnull
+            @Override
+            public Nature getNature() {
+                return nature;
+            }
+
             @Override
             public boolean equals(Object o) {
                 return o instanceof DefaultVersionResolverRequest that
                         && Objects.equals(artifactCoordinates, that.artifactCoordinates)
-                        && Objects.equals(repositories, that.repositories);
+                        && Objects.equals(repositories, that.repositories)
+                        && nature == that.nature;
             }
 
             @Override
             public int hashCode() {
-                return Objects.hash(artifactCoordinates, repositories);
+                return Objects.hash(artifactCoordinates, repositories, nature);
             }
 
             @Override
             public String toString() {
                 return "VersionResolverRequest[" + "artifactCoordinates="
                         + artifactCoordinates + ", repositories="
-                        + repositories + ']';
+                        + repositories + ", nature="
+                        + nature + ']';
             }
         }
     }

compat/maven-compat/pom.xml

@@ -115,6 +115,10 @@ under the License.
       <groupId>org.apache.maven.resolver</groupId>
       <artifactId>maven-resolver-util</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.apache.maven.resolver</groupId>
+      <artifactId>maven-resolver-impl</artifactId>
+    </dependency>
 
     <dependency>
       <groupId>org.codehaus.plexus</groupId>
@@ -212,11 +216,6 @@ under the License.
       <artifactId>maven-resolver-spi</artifactId>
       <scope>test</scope>
     </dependency>
-    <dependency>
-      <groupId>org.apache.maven.resolver</groupId>
-      <artifactId>maven-resolver-impl</artifactId>
-      <scope>test</scope>
-    </dependency>
     <dependency>
       <groupId>org.apache.maven.resolver</groupId>
       <artifactId>maven-resolver-connector-basic</artifactId>