From f03e2aae34e3a45f3c3306d1e864bbb82f9b2b92 Mon Sep 17 00:00:00 2001 From: Konrad Windszus Date: Fri, 16 Aug 2024 10:22:59 +0200 Subject: [PATCH] [MRESOLVER-598] Improve Javadoc on version ranges Point out that the exact syntax of a version depends on the underlying provider --- .../main/java/org/eclipse/aether/RepositorySystem.java | 8 +++++--- .../main/java/org/eclipse/aether/artifact/Artifact.java | 2 ++ .../java/org/eclipse/aether/artifact/DefaultArtifact.java | 8 ++++---- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystem.java b/maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystem.java index ddad8726d..aafd49fc2 100644 --- a/maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystem.java +++ b/maven-resolver-api/src/main/java/org/eclipse/aether/RepositorySystem.java @@ -70,7 +70,7 @@ public interface RepositorySystem extends Closeable { /** - * Expands a version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to + * Expands an artifact's version range to a list of matching versions, in ascending order. For example, resolves "[3.8,4.0)" to * "3.8", "3.8.1", "3.8.2". Note that the returned list of versions is only dependent on the configured repositories * and their contents, the list is not processed by the {@link RepositorySystemSession#getVersionFilter() session's * version filter}. @@ -79,11 +79,12 @@ public interface RepositorySystem extends Closeable { * though, the result contains simply the (parsed) input version, regardless of the repositories and their contents. * * @param session The repository session, must not be {@code null}. - * @param request The version range request, must not be {@code null}. + * @param request The version range request, must not be {@code null}. It holds the {@link Artifact} whose version range to resolve. * @return The version range result, never {@code null}. * @throws VersionRangeResolutionException If the requested range could not be parsed. Note that an empty range does * not raise an exception. * @see #newResolutionRepositories(RepositorySystemSession, List) + * @see Artifact#getVersion() */ VersionRangeResult resolveVersionRange(RepositorySystemSession session, VersionRangeRequest request) throws VersionRangeResolutionException; @@ -93,10 +94,11 @@ VersionRangeResult resolveVersionRange(RepositorySystemSession session, VersionR * "1.0-20090208.132618-23". * * @param session The repository session, must not be {@code null}. - * @param request The version request, must not be {@code null}. + * @param request The version request, must not be {@code null}. It holds the {@link Artifact} whose version to resolve. * @return The version result, never {@code null}. * @throws VersionResolutionException If the metaversion could not be resolved. * @see #newResolutionRepositories(RepositorySystemSession, List) + * @see Artifact#getVersion() */ VersionResult resolveVersion(RepositorySystemSession session, VersionRequest request) throws VersionResolutionException; diff --git a/maven-resolver-api/src/main/java/org/eclipse/aether/artifact/Artifact.java b/maven-resolver-api/src/main/java/org/eclipse/aether/artifact/Artifact.java index 7f920113b..40cd72599 100644 --- a/maven-resolver-api/src/main/java/org/eclipse/aether/artifact/Artifact.java +++ b/maven-resolver-api/src/main/java/org/eclipse/aether/artifact/Artifact.java @@ -51,6 +51,8 @@ public interface Artifact { * Gets the version of this artifact, for example "1.0-20100529-1213". Note that in case of meta versions like * "1.0-SNAPSHOT", the artifact's version depends on the state of the artifact. Artifacts that have been resolved or * deployed will usually have the meta version expanded. + * This may also return version ranges like "[1.0,2.0)". The exact syntax for (meta) versions and version ranges + * depends on the underlying provider (encapsulated in {@link RepositorySystem}). * * @return The version, never {@code null}. */ diff --git a/maven-resolver-api/src/main/java/org/eclipse/aether/artifact/DefaultArtifact.java b/maven-resolver-api/src/main/java/org/eclipse/aether/artifact/DefaultArtifact.java index 525103029..080993ec1 100644 --- a/maven-resolver-api/src/main/java/org/eclipse/aether/artifact/DefaultArtifact.java +++ b/maven-resolver-api/src/main/java/org/eclipse/aether/artifact/DefaultArtifact.java @@ -132,7 +132,7 @@ private static String get(String value, String defaultValue) { * @param groupId The group identifier of the artifact, may be {@code null}. * @param artifactId The artifact identifier of the artifact, may be {@code null}. * @param extension The file extension of the artifact, may be {@code null}. - * @param version The version of the artifact, may be {@code null}. + * @param version The version (may also be a meta version or version range) of the artifact, may be {@code null}. */ public DefaultArtifact(String groupId, String artifactId, String extension, String version) { this(groupId, artifactId, "", extension, version); @@ -146,7 +146,7 @@ public DefaultArtifact(String groupId, String artifactId, String extension, Stri * @param artifactId The artifact identifier of the artifact, may be {@code null}. * @param classifier The classifier of the artifact, may be {@code null}. * @param extension The file extension of the artifact, may be {@code null}. - * @param version The version of the artifact, may be {@code null}. + * @param version The version (may also be a meta version or version range) of the artifact, may be {@code null}. */ public DefaultArtifact(String groupId, String artifactId, String classifier, String extension, String version) { this(groupId, artifactId, classifier, extension, version, null, (File) null); @@ -162,7 +162,7 @@ public DefaultArtifact(String groupId, String artifactId, String classifier, Str * @param artifactId The artifact identifier of the artifact, may be {@code null}. * @param classifier The classifier of the artifact, may be {@code null}. * @param extension The file extension of the artifact, may be {@code null}. - * @param version The version of the artifact, may be {@code null}. + * @param version The version (may also be a meta version or version range) of the artifact, may be {@code null}. * @param type The artifact type from which to query classifier, file extension and properties, may be {@code null}. */ public DefaultArtifact( @@ -181,7 +181,7 @@ public DefaultArtifact( * @param artifactId The artifact identifier of the artifact, may be {@code null}. * @param classifier The classifier of the artifact, may be {@code null}. * @param extension The file extension of the artifact, may be {@code null}. - * @param version The version of the artifact, may be {@code null}. + * @param version The version (may also be a meta version or version range) of the artifact, may be {@code null}. * @param properties The properties of the artifact, may be {@code null} if none. * @param type The artifact type from which to query classifier, file extension and properties, may be {@code null}. */