[MRESOLVER-470] Prepare for new changes regarding Artifact properties…

…/scopes (#411)

Changes:
* make ArtifactType usable in GAV string ctor cases (and the two ctors should behave same)
* deprecate old 1.x "list generators", point to newer ones that are more versatile
* update some Javadoc, clear up actual intent (and misconceptions)

---

https://issues.apache.org/jira/browse/MRESOLVER-470

maven-resolver-api/src/main/java/org/eclipse/aether/artifact/ArtifactProperties.java

@@ -54,6 +54,10 @@ public final class ArtifactProperties {
     /**
      * A boolean flag indicating whether the artifact is meant to be used for the compile/runtime/test build path of a
      * consumer project.
+     * <p>
+     * Note: This property is about "build path", whatever it means in the scope of the consumer project. It is NOT
+     * about Java classpath or anything alike. How artifact is being consumed depends heavily on the consumer project.
+     * Resolver is and will remain agnostic of consumer project use cases.
      */
     public static final String CONSTITUTES_BUILD_PATH = "constitutesBuildPath";
 

maven-resolver-api/src/main/java/org/eclipse/aether/artifact/DefaultArtifact.java

@@ -58,7 +58,7 @@ public final class DefaultArtifact extends AbstractArtifact {
      * format.
      */
     public DefaultArtifact(String coords) {
-        this(coords, Collections.<String, String>emptyMap());
+        this(coords, null, null);
     }
 
     /**
@@ -73,18 +73,51 @@ public DefaultArtifact(String coords) {
      * format.
      */
     public DefaultArtifact(String coords, Map<String, String> properties) {
+        this(coords, properties, null);
+    }
+
+    /**
+     * Creates a new artifact with the specified coordinates and type. If not specified in the artifact coordinates,
+     * the artifact's extension defaults to type extension (or "jar" if type is {@code null}) and
+     * classifier to type extension (or "" if type is {@code null}).
+     *
+     * @param coords The artifact coordinates in the format
+     *            {@code <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>}, must not be {@code null}.
+     * @param type The artifact type, may be {@code null}.
+     *
+     * @throws IllegalArgumentException If the artifact coordinates found in {@code coords} do not match the expected
+     * format.
+     */
+    public DefaultArtifact(String coords, ArtifactType type) {
+        this(coords, null, type);
+    }
+
+    /**
+     * Creates a new artifact with the specified coordinates, properties and type. If not specified in the artifact
+     * coordinates, the artifact's extension defaults to type extension (or "jar" if type is {@code null}) and
+     * classifier to type extension (or "" if type is {@code null}).
+     *
+     * @param coords The artifact coordinates in the format
+     *            {@code <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>}, must not be {@code null}.
+     * @param properties The artifact properties, may be {@code null}.
+     * @param type The artifact type, may be {@code null}.
+     *
+     * @throws IllegalArgumentException If the artifact coordinates found in {@code coords} do not match the expected
+     * format.
+     */
+    public DefaultArtifact(String coords, Map<String, String> properties, ArtifactType type) {
         Matcher m = COORDINATE_PATTERN.matcher(coords);
         if (!m.matches()) {
             throw new IllegalArgumentException("Bad artifact coordinates " + coords
                     + ", expected format is <groupId>:<artifactId>[:<extension>[:<classifier>]]:<version>");
         }
         groupId = m.group(1);
         artifactId = m.group(2);
-        extension = get(m.group(4), "jar");
-        classifier = get(m.group(6), "");
-        version = m.group(7);
-        file = null;
-        this.properties = copyProperties(properties);
+        extension = get(m.group(4), type == null ? "jar" : type.getExtension());
+        classifier = get(m.group(6), type == null ? "" : type.getClassifier());
+        this.version = emptify(m.group(7));
+        this.file = null;
+        this.properties = merge(properties, (type != null) ? type.getProperties() : null);
     }
 
     private static String get(String value, String defaultValue) {

maven-resolver-api/src/main/java/org/eclipse/aether/graph/DependencyNode.java

@@ -102,7 +102,7 @@ public interface DependencyNode {
 
     /**
      * Gets the artifact associated with this node. If this node is associated with a dependency, this is equivalent to
-     * {@code getDependency().getArtifact()}. Otherwise the artifact merely provides a label for this node in which case
+     * {@code getDependency().getArtifact()}. Otherwise, the artifact merely provides a label for this node in which case
      * the artifact must not be subjected to dependency collection/resolution.
      *
      * @return The associated artifact or {@code null} if none.

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/visitor/AbstractDepthFirstNodeListGenerator.java

@@ -46,7 +46,10 @@
  * is not used in Resolver and is kept only for backward compatibility reasons.
  *
  * @see AbstractDependencyNodeConsumerVisitor
+ *
+ * @deprecated See {@link AbstractDependencyNodeConsumerVisitor} that is more versatile.
  */
+@Deprecated
 abstract class AbstractDepthFirstNodeListGenerator implements DependencyVisitor {
 
     private final Map<DependencyNode, Object> visitedNodes;

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/visitor/LevelOrderDependencyNodeConsumerVisitor.java

@@ -31,6 +31,8 @@
  * free of duplicates.
  *
  * @since 2.0.0
+ *
+ * @see NodeListGenerator
  */
 public final class LevelOrderDependencyNodeConsumerVisitor extends AbstractDependencyNodeConsumerVisitor {
 

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/visitor/NodeListGenerator.java

@@ -35,6 +35,10 @@
  * offers several transformations, that are handy.
  *
  * @since 2.0.0
+ *
+ * @see PreorderDependencyNodeConsumerVisitor
+ * @see PostorderDependencyNodeConsumerVisitor
+ * @see LevelOrderDependencyNodeConsumerVisitor
  */
 public final class NodeListGenerator implements Consumer<DependencyNode> {
 

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/visitor/PostorderDependencyNodeConsumerVisitor.java

@@ -29,6 +29,8 @@
  * free of duplicates.
  *
  * @since 2.0.0
+ *
+ * @see NodeListGenerator
  */
 public final class PostorderDependencyNodeConsumerVisitor extends AbstractDependencyNodeConsumerVisitor {
 

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/visitor/PostorderNodeListGenerator.java

@@ -31,7 +31,10 @@
  *
  * @see PostorderDependencyNodeConsumerVisitor
  * @see NodeListGenerator
+ *
+ * @deprecated See {@link PostorderDependencyNodeConsumerVisitor} that is more versatile.
  */
+@Deprecated
 public final class PostorderNodeListGenerator extends AbstractDepthFirstNodeListGenerator {
 
     private final Stack<Boolean> visits;

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/visitor/PreorderDependencyNodeConsumerVisitor.java

@@ -29,6 +29,8 @@
  * free of duplicates.
  *
  * @since 2.0.0
+ *
+ * @see NodeListGenerator
  */
 public final class PreorderDependencyNodeConsumerVisitor extends AbstractDependencyNodeConsumerVisitor {
 

maven-resolver-util/src/main/java/org/eclipse/aether/util/graph/visitor/PreorderNodeListGenerator.java

@@ -31,7 +31,10 @@
  *
  * @see PreorderDependencyNodeConsumerVisitor
  * @see NodeListGenerator
+ *
+ * @deprecated See {@link PreorderDependencyNodeConsumerVisitor} that is more versatile.
  */
+@Deprecated
 public final class PreorderNodeListGenerator extends AbstractDepthFirstNodeListGenerator {
 
     /**