[MNG-8134] Add a @Resolution annotation to mojos to inject project dependencies collection / resolution result

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

@@ -33,7 +33,7 @@
  * Represents a dependency node within a Maven project's dependency collector.
  *
  * @since 4.0.0
- * @see org.apache.maven.api.services.DependencyCollectorResult#getRoot()
+ * @see org.apache.maven.api.services.DependencyResolverResult#getRoot()
  */
 @Experimental
 @Immutable

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

@@ -496,25 +496,25 @@ Artifact createArtifact(
     boolean isVersionSnapshot(@Nonnull String version);
 
     /**
-     * Shortcut for {@code getService(DependencyCollector.class).collect(...)}
+     * Shortcut for {@code getService(DependencyResolver.class).collect(...)}
      *
      * @param artifact artifact for which to get the dependencies, including transitive ones
      * @return root node of the dependency graph for the given artifact
      *
-     * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Artifact)
-     * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
+     * @see org.apache.maven.api.services.DependencyResolver#collect(Session, Artifact)
+     * @throws org.apache.maven.api.services.DependencyResolverException if the dependency collection failed
      */
     @Nonnull
     Node collectDependencies(@Nonnull Artifact artifact);
 
     /**
-     * Shortcut for {@code getService(DependencyCollector.class).collect(...)}
+     * Shortcut for {@code getService(DependencyResolver.class).collect(...)}
      *
      * @param project project for which to get the dependencies, including transitive ones
      * @return root node of the dependency graph for the given project
      *
-     * @see org.apache.maven.api.services.DependencyCollector#collect(Session, Project)
-     * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
+     * @see org.apache.maven.api.services.DependencyResolver#collect(Session, Project)
+     * @throws org.apache.maven.api.services.DependencyResolverException if the dependency collection failed
      */
     @Nonnull
     Node collectDependencies(@Nonnull Project project);
@@ -524,13 +524,13 @@ Artifact createArtifact(
      * only concerned about determining the coordinates of the transitive dependencies and does not actually resolve the
      * artifact files.
      * <p>
-     * Shortcut for {@code getService(DependencyCollector.class).resolve(...)}
+     * Shortcut for {@code getService(DependencyResolver.class).resolve(...)}
      *
      * @param dependency dependency for which to get transitive dependencies
      * @return root node of the dependency graph for the given artifact
      *
-     * @see org.apache.maven.api.services.DependencyCollector#collect(Session, DependencyCoordinate)
-     * @throws org.apache.maven.api.services.DependencyCollectorException if the dependency collection failed
+     * @see org.apache.maven.api.services.DependencyResolver#collect(Session, DependencyCoordinate)
+     * @throws org.apache.maven.api.services.DependencyResolverException if the dependency collection failed
      */
     @Nonnull
     Node collectDependencies(@Nonnull DependencyCoordinate dependency);

api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Mojo.java

@@ -29,10 +29,23 @@
 import org.apache.maven.api.annotations.Nonnull;
 
 /**
- * This annotation will mark your class as a Mojo (ie. goal in a Maven plugin).
- * The mojo can be annotated with {@code jakarta.inject.*} annotations.
+ * This annotation will mark your class as a Mojo, which is the implementation of a goal in a Maven plugin.
+ * <p>
+ * The mojo can be annotated with {@code org.apache.maven.api.di.*} annotations to
+ * control the lifecycle of the mojo itself, and to inject other beans.
+ * </p>
+ * <p>
+ * The mojo class can also be injected with an {@link Execute} annotation to specify a
+ * forked lifecycle.
+ * </p>
+ * <p>
  * The {@link Parameter} annotation can be added on fields to inject data
  * from the plugin configuration or from other components.
+ * </p>
+ * <p>
+ * Fields can also be annotated with the {@link Resolution} annotation to be injected
+ * with the dependency collection or resolution result for the project.
+ * </p>
  *
  * @since 4.0.0
  */
@@ -81,4 +94,22 @@
      */
     @Nonnull
     String configurator() default "";
+
+    /**
+     * Indicates whether dependency collection will be
+     * required when executing the Mojo.
+     * If not set, it will be inferred from the fields
+     * annotated with the {@link Resolution} annotation.
+     */
+    @Nonnull
+    boolean dependencyCollection() default false;
+
+    /**
+     * Comma separated list of path scopes that will be
+     * required for dependency resolution.
+     * If not set, it will be inferred from the fields
+     * annotated with the {@link Resolution} annotation.
+     */
+    @Nonnull
+    String dependencyResolutionPathScopes() default "";
 }

api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Resolution.java

@@ -0,0 +1,74 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api.plugin.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.apache.maven.api.annotations.Experimental;
+
+/**
+ * Indicates that a given field will be injected with the result of
+ * a dependency collection or resolution request. Whether a collection
+ * or resolution request is performed is controlled by the {@link #pathScope()}
+ * field, the injected field type and the {@link #requestType()}.
+ * <p>
+ * If the {@code requestType} is not set explicitly, it will be inferred
+ * from the {@code pathScope} and the injected field type. If the type
+ * is {@link org.apache.maven.api.Node Node} and {@code pathScope == ""},
+ * then the dependencies will be <i>collected</i>.
+ * If the type is {@link org.apache.maven.api.Node Node} or
+ * {@code List<}{@link org.apache.maven.api.Node Node}{@code >},
+ * and {@code pathScope != ""}, the dependencies will be <i>flattened</i>.
+ * Else the dependencies will be <i>resolved</i> and {@code pathScope} must be non empty,
+ * and the field type can be {@link org.apache.maven.api.Node Node},
+ * {@code List<}{@link org.apache.maven.api.Node Node}{@code >},
+ * {@link org.apache.maven.api.services.DependencyResolverResult DependencyResolverResult},
+ * {@code List<}{@link java.nio.file.Path Path}{@code >},
+ * {@code Map<}{@link org.apache.maven.api.PathType PathType}{@code , List<}{@link java.nio.file.Path Path}{@code >>},
+ * or {@code Map<}{@link org.apache.maven.api.Dependency Dependency}{@code , }{@link java.nio.file.Path Path}{@code >}.
+ *
+ * @since 4.0.0
+ */
+@Experimental
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
+public @interface Resolution {
+
+    /**
+     * The id of a {@link org.apache.maven.api.PathScope} enum value.
+     * If specified, a dependency resolution request will be issued,
+     * else a dependency collection request will be done.
+     *
+     * @return the id of the path scope
+     */
+    String pathScope() default "";
+
+    /**
+     * The request type, in case the default one is not correct.
+     * Valid values are {@code collect}, {@code flatten}, or {@code resolve}.
+     *
+     * @return the request type
+     */
+    String requestType() default "";
+}