You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2024/08/16 08:23:07 UTC

(maven-resolver) branch feature/MRESOLVER-598-improve-javadoc-on-versionresolving created (now 5c6e2430)

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

kwin pushed a change to branch feature/MRESOLVER-598-improve-javadoc-on-versionresolving
in repository https://gitbox.apache.org/repos/asf/maven-resolver.git


      at 5c6e2430 [MRESOLVER-598] Improve Javadoc on version ranges

This branch includes the following new commits:

     new 5c6e2430 [MRESOLVER-598] Improve Javadoc on version ranges

The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



(maven-resolver) 01/01: [MRESOLVER-598] Improve Javadoc on version ranges

Posted by kw...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch feature/MRESOLVER-598-improve-javadoc-on-versionresolving
in repository https://gitbox.apache.org/repos/asf/maven-resolver.git

commit 5c6e24300790e1d4fb7e6d1d2d67cf6906452d8a
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Fri Aug 16 10:22:59 2024 +0200

    [MRESOLVER-598] Improve Javadoc on version ranges
    
    Point out that the exact syntax of a version depends on the underlying
    provider
---
 .../src/main/java/org/eclipse/aether/RepositorySystem.java        | 8 +++++---
 .../src/main/java/org/eclipse/aether/artifact/Artifact.java       | 4 ++++
 .../main/java/org/eclipse/aether/artifact/DefaultArtifact.java    | 8 ++++----
 3 files changed, 13 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 ddad8726..aafd49fc 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 @@ import org.eclipse.aether.resolution.VersionResult;
 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 @@ public interface RepositorySystem extends Closeable {
      * "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 7f920113..664e71f5 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
@@ -22,6 +22,8 @@ import java.io.File;
 import java.nio.file.Path;
 import java.util.Map;
 
+import org.eclipse.aether.RepositorySystemSession;
+
 /**
  * A specific artifact. In a nutshell, an artifact has identifying coordinates and optionally a file that denotes its
  * data. <em>Note:</em> Artifact instances are supposed to be immutable, e.g. any exposed mutator method returns a new
@@ -51,6 +53,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 52510302..080993ec 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 @@ public final class DefaultArtifact extends AbstractArtifact {
      * @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 final class DefaultArtifact extends AbstractArtifact {
      * @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 final class DefaultArtifact extends AbstractArtifact {
      * @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 final class DefaultArtifact extends AbstractArtifact {
      * @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}.
      */