Rename coordinate -> coordinates and ResolvedArtifact -> DownloadedArtifact

Author: gnodet

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

@@ -23,11 +23,15 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * Pointer to a resolved resource such as a <abbr>JAR</abbr> file or <abbr>WAE</abbr> application.
- * Each {@code Artifact} instance is basically an exact pointer to a file in a Maven repository.
- * {@code Artifact} instances are created when <dfn>resolving</dfn> {@link ArtifactCoordinate} instances.
+ * A Maven artifact is a file, typically a JAR, that is produced and used by Maven projects.
+ * It is identified by a unique combination of a group ID, artifact ID, version, classifier,
+ * and extension, and it is stored in a repository for dependency management and build purposes.
+ *
+ * <p>Each {@code Artifact} instance is basically an exact pointer to a file in a Maven repository.
+ * {@code Artifact} instances are created when <dfn>resolving</dfn> {@link ArtifactCoordinates} instances.
  * Resolving is the process that selects a {@linkplain #getVersion() particular version}
- * and downloads the artifact in the local repository.  This operation returns a {@link ResolvedArtifact}.
+ * and downloads the artifact in the local repository.  This operation returns a {@link DownloadedArtifact}.
+ * </p>
  *
  * @since 4.0.0
  */
@@ -38,7 +42,7 @@ public interface Artifact {
      * {@return a unique identifier for this artifact}.
      * The identifier is composed of groupId, artifactId, extension, classifier, and version.
      *
-     * @see ArtifactCoordinate#getId()
+     * @see ArtifactCoordinates#getId()
      */
     @Nonnull
     default String key() {
@@ -56,26 +60,26 @@ default String key() {
     /**
      * {@return the group identifier of the artifact}.
      *
-     * @see ArtifactCoordinate#getGroupId()
+     * @see ArtifactCoordinates#getGroupId()
      */
     @Nonnull
     String getGroupId();
 
     /**
      * {@return the identifier of the artifact}.
      *
-     * @see ArtifactCoordinate#getArtifactId()
+     * @see ArtifactCoordinates#getArtifactId()
      */
     @Nonnull
     String getArtifactId();
 
     /**
-     * {@return the version of the artifact}. Contrarily to {@link ArtifactCoordinate},
+     * {@return the version of the artifact}. Contrarily to {@link ArtifactCoordinates},
      * each {@code Artifact} is associated to a specific version instead of a range of versions.
      * If the {@linkplain #getBaseVersion() base version} contains a meta-version such as {@code SNAPSHOT},
      * those keywords are replaced by, for example, the actual timestamp.
      *
-     * @see ArtifactCoordinate#getVersionConstraint()
+     * @see ArtifactCoordinates#getVersionConstraint()
      */
     @Nonnull
     Version getVersion();
@@ -93,7 +97,7 @@ default String key() {
      * Returns the classifier of the artifact.
      *
      * @return the classifier or an empty string if none, never {@code null}
-     * @see ArtifactCoordinate#getClassifier()
+     * @see ArtifactCoordinates#getClassifier()
      */
     @Nonnull
     String getClassifier();
@@ -103,7 +107,7 @@ default String key() {
      * The dot separator is <em>not</em> included in the returned string.
      *
      * @return the file extension or an empty string if none, never {@code null}
-     * @see ArtifactCoordinate#getExtension()
+     * @see ArtifactCoordinates#getExtension()
      */
     @Nonnull
     String getExtension();
@@ -117,11 +121,11 @@ default String key() {
     boolean isSnapshot();
 
     /**
-     * {@return coordinate with the same identifiers as this artifact}.
-     * This is a shortcut for {@code session.createArtifactCoordinate(artifact)}.
+     * {@return coordinates with the same identifiers as this artifact}.
+     * This is a shortcut for {@code session.createArtifactCoordinates(artifact)}.
      *
-     * @see org.apache.maven.api.Session#createArtifactCoordinate(Artifact)
+     * @see org.apache.maven.api.Session#createArtifactCoordinates(Artifact)
      */
     @Nonnull
-    ArtifactCoordinate toCoordinate();
+    ArtifactCoordinates toCoordinates();
 }

api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinate.java renamed to api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinates.java

@@ -23,15 +23,15 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * Partial identification of an {@code Artifact} in a Maven repository.
- * Each {@code ArtifactCoordinate} instance is basically a pointer to a file in the Maven repository,
+ * Partial identification of an {@link Artifact} in a Maven repository.
+ * Each {@code ArtifactCoordinates} instance is basically a pointer to a file in the Maven repository,
  * except that the exact version may not be known yet.
  *
  * @since 4.0.0
  */
 @Experimental
 @Immutable
-public interface ArtifactCoordinate {
+public interface ArtifactCoordinates {
     /**
      * {@return the group identifier of the artifact}.
      */

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

@@ -23,7 +23,7 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * A result of collecting, flattening and resolving {@code DependencyCoordinate}s.
+ * A result of collecting, flattening and resolving {@link DependencyCoordinates}s.
  * Dependency is the output of the <dfn>collection</dfn> process, which builds the graph of dependencies,
  * followed by <dfn>flattening</dfn> and <dfn>resolution</dfn>.
  * The version selection is done for each dependency during the collection phase.
@@ -40,7 +40,7 @@ public interface Dependency extends Artifact {
      * a modular-<abbr>JAR</abbr> if it is intended to be placed on the module-path,
      * a <abbr>JAR</abbr> containing test classes, <i>etc.</i>
      *
-     * @see DependencyCoordinate#getType()
+     * @see DependencyCoordinates#getType()
      */
     @Nonnull
     Type getType();
@@ -49,25 +49,25 @@ public interface Dependency extends Artifact {
      * {@return the time at which the dependency will be used}.
      * If may be, for example, at compile time only, at run time or at test time.
      *
-     * @see DependencyCoordinate#getScope()
+     * @see DependencyCoordinates#getScope()
      */
     @Nonnull
     DependencyScope getScope();
 
     /**
      * Returns whether the dependency is optional or mandatory.
-     * Contrarily to {@link DependencyCoordinate}, the obligation of a {@code Dependency} is always present.
+     * Contrarily to {@link DependencyCoordinates}, the obligation of a {@code Dependency} is always present.
      * The value is computed during the dependencies collection phase.
      *
      * @return {@code true} if the dependency is optional, or {@code false} if mandatory
-     * @see DependencyCoordinate#getOptional()
+     * @see DependencyCoordinates#getOptional()
      */
     boolean isOptional();
 
     /**
-     * {@return coordinate with the same identifiers as this dependency}
+     * {@return coordinates with the same identifiers as this dependency}
      */
     @Nonnull
     @Override
-    DependencyCoordinate toCoordinate();
+    DependencyCoordinates toCoordinates();
 }

api/maven-api-core/src/main/java/org/apache/maven/api/DependencyCoordinate.java renamed to api/maven-api-core/src/main/java/org/apache/maven/api/DependencyCoordinates.java

@@ -26,7 +26,7 @@
 import org.apache.maven.api.annotations.Nullable;
 
 /**
- * {@code ArtifactCoordinate} completed with information about how the artifact will be used.
+ * {@code ArtifactCoordinates} completed with information about how the artifact will be used.
  * This information include the dependency type (main classes, test classes, <i>etc.</i>),
  * a scope (compile-time, run-time <i>etc.</i>), an obligation (whether the dependency
  * is optional or mandatory), and possible exclusions for transitive dependencies.
@@ -37,7 +37,7 @@
  */
 @Experimental
 @Immutable
-public interface DependencyCoordinate extends ArtifactCoordinate {
+public interface DependencyCoordinates extends ArtifactCoordinates {
     /**
      * {@return the type of the dependency}. A dependency can be a <abbr>JAR</abbr> file,
      * a modular-<abbr>JAR</abbr> if it is intended to be placed on the module-path,

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

@@ -50,7 +50,7 @@ public enum DependencyScope {
 
     /**
      * Undefined. When no scope is explicitly given, UNDEFINED will be used, but its meaning will depend on
-     * whether the DependencyCoordinate is used in dependency management, in which case it means the scope is not
+     * whether the DependencyCoordinates is used in dependency management, in which case it means the scope is not
      * explicitly managed by this managed dependency, or as a real dependency, in which case, the scope
      * will default to {@link #COMPILE}.
      */

api/maven-api-core/src/main/java/org/apache/maven/api/ResolvedArtifact.java renamed to api/maven-api-core/src/main/java/org/apache/maven/api/DownloadedArtifact.java

@@ -20,12 +20,17 @@
 
 import java.nio.file.Path;
 
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Immutable;
+
 /**
  * An {@link Artifact} that has been resolved, i.e. downloaded to the local repository.
  *
  * @since 4.0.0
  */
-public interface ResolvedArtifact extends Artifact {
+@Experimental
+@Immutable
+public interface DownloadedArtifact extends Artifact {
 
     /**
      * {@return the actual file that has been downloaded in the file system}

api/maven-api-core/src/main/java/org/apache/maven/api/ResolvedDependency.java renamed to api/maven-api-core/src/main/java/org/apache/maven/api/DownloadedDependency.java

@@ -18,4 +18,14 @@
  */
 package org.apache.maven.api;
 
-public interface ResolvedDependency extends Dependency, ResolvedArtifact {}
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Immutable;
+
+/**
+ * A {@link Dependency} that has been resolved, i.e. downloaded to the local repository.
+ *
+ * @since 4.0.0
+ */
+@Experimental
+@Immutable
+public interface DownloadedDependency extends Dependency, DownloadedArtifact {}

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

@@ -25,7 +25,7 @@
  * A dependency exclusion.
  *
  * @since 4.0.0
- * @see DependencyCoordinate#getExclusions()
+ * @see DependencyCoordinates#getExclusions()
  */
 @Experimental
 public interface Exclusion {

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

@@ -27,7 +27,13 @@
 import org.apache.maven.api.model.Plugin;
 
 /**
- * Lifecycle definition
+ * A Maven lifecycle is a sequence of predefined phases that govern the build process
+ * of a Maven project. Each phase represents a specific step, such as compiling the
+ * code, running tests, packaging the project, and deploying it. Executing a phase
+ * triggers all preceding phases, ensuring that each step of the build process is
+ * completed in the correct order. The three main lifecycles in Maven are
+ * {@link #DEFAULT default}, {@link #CLEAN clean}, and {@link #SITE site}, with the
+ * {@code default} lifecycle being the most commonly used for project builds.
  *
  * @since 4.0.0
  */

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

@@ -21,6 +21,7 @@
 import java.nio.file.Path;
 
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Immutable;
 
 /**
  * An {@link Artifact} that is being produced by a {@link Project} during the build.
@@ -42,4 +43,5 @@
  * @see org.apache.maven.api.services.ArtifactManager#setPath(ProducedArtifact, Path)
  */
 @Experimental
+@Immutable
 public interface ProducedArtifact extends Artifact {}