[MNG-7947] Plugin API

api/maven-api-core/pom.xml

@@ -51,6 +51,15 @@
       <artifactId>maven-api-toolchain</artifactId>
       <version>4.0.0-alpha-9-SNAPSHOT</version>
     </dependency>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-api-plugin</artifactId>
+      <version>4.0.0-alpha-9-SNAPSHOT</version>
+    </dependency>
+    <dependency>
+      <groupId>jakarta.inject</groupId>
+      <artifactId>jakarta.inject-api</artifactId>
+    </dependency>
   </dependencies>
 
 </project>

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

@@ -22,23 +22,37 @@
 
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Nonnull;
-import org.apache.maven.api.model.Plugin;
+import org.apache.maven.api.model.PluginExecution;
+import org.apache.maven.api.plugin.descriptor.MojoDescriptor;
 import org.apache.maven.api.xml.XmlNode;
 
 /**
- * A {@code MojoExecution}
+ * A {@code MojoExecution} represents a single execution of a Maven Plugin during a given build.
+ * An instance of this object is bound to the {@link org.apache.maven.api.di.MojoExecutionScoped}
+ * and available as {@code mojoExecution} within {@link org.apache.maven.api.plugin.annotations.Parameter}
+ * expressions.
  */
 @Experimental
 public interface MojoExecution {
+
     @Nonnull
     Plugin getPlugin();
 
+    @Nonnull
+    PluginExecution getModel();
+
+    @Nonnull
+    MojoDescriptor getDescriptor();
+
     @Nonnull
     String getExecutionId();
 
     @Nonnull
     String getGoal();
 
+    @Nonnull
+    String getLifecyclePhase();
+
     @Nonnull
     Optional<XmlNode> getConfiguration();
 }

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

@@ -0,0 +1,58 @@
+/*
+ * 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;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.plugin.descriptor.PluginDescriptor;
+import org.apache.maven.api.plugin.descriptor.lifecycle.Lifecycle;
+
+/**
+ * Represents a maven plugin runtime
+ */
+@Experimental
+public interface Plugin {
+
+    @Nonnull
+    org.apache.maven.api.model.Plugin getModel();
+
+    @Nonnull
+    PluginDescriptor getDescriptor();
+
+    @Nonnull
+    List<Lifecycle> getLifecycles();
+
+    @Nonnull
+    ClassLoader getClassLoader();
+
+    @Nonnull
+    Artifact getArtifact();
+
+    @Nonnull
+    default Collection<Dependency> getDependencies() {
+        return getDependenciesMap().values();
+    }
+
+    @Nonnull
+    Map<String, Dependency> getDependenciesMap();
+}

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

@@ -214,6 +214,13 @@ ArtifactCoordinate createArtifactCoordinate(
     @Nonnull
     DependencyCoordinate createDependencyCoordinate(@Nonnull ArtifactCoordinate coordinate);
 
+    /**
+     * Shortcut for <code>getService(DependencyFactory.class).create(...)</code>
+     * @see DependencyCoordinateFactory#create(Session, Dependency)
+     */
+    @Nonnull
+    DependencyCoordinate createDependencyCoordinate(@Nonnull Dependency dependency);
+
     /**
      * Shortcut for <code>getService(ArtifactFactory.class).create(...)</code>
      * @see org.apache.maven.api.services.ArtifactFactory#create(Session, String, String, String, String)

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

@@ -29,7 +29,7 @@
 @Experimental
 public interface VersionRange {
 
-    // TODO: add access to the version information
+    // TODO: v4: add access to the version information
 
     /**
      * Determines whether the specified version is contained within this range.

api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Component.java → api/maven-api-core/src/main/java/org/apache/maven/api/di/MojoExecutionScoped.java

@@ -16,42 +16,26 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.api.plugin.annotations;
+package org.apache.maven.api.di;
 
 import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-import org.apache.maven.api.annotations.Experimental;
-import org.apache.maven.api.annotations.Nonnull;
+import jakarta.inject.Scope;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Used to configure injection of Plexus components by
- * <a href="/ref/current/maven-core/apidocs/org/apache/maven/plugin/MavenPluginManager.html">
- * <code>MavenPluginManager.getConfiguredMojo(...)</code></a>.
+ * Indicates that the annotated bean has a lifespan limited to a given mojo execution,
+ * which means each mojo execution will result in a different instance being injected.
  *
  * @since 4.0.0
  */
-@Experimental
+@Scope
 @Documented
-@Retention(RetentionPolicy.CLASS)
-@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
-@Inherited
-public @interface Component {
-    /**
-     * role of the component to inject.
-     * @return the role
-     */
-    @Nonnull
-    Class<?> role() default Object.class;
-
-    /**
-     * hint of the component to inject.
-     * @return the hint
-     */
-    @Nonnull
-    String hint() default "";
-}
+@Retention(RUNTIME)
+@Target({TYPE, METHOD})
+public @interface MojoExecutionScoped {}

api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/InstantiationStrategy.java → api/maven-api-core/src/main/java/org/apache/maven/api/di/SessionScoped.java

@@ -16,29 +16,26 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.api.plugin.annotations;
+package org.apache.maven.api.di;
 
-import org.apache.maven.api.annotations.Experimental;
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import jakarta.inject.Scope;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Component instantiation strategy.
+ * Indicates that annotated component should be instantiated before session execution starts
+ * and discarded after session execution completes.
  *
  * @since 4.0.0
  */
-@Experimental
-public enum InstantiationStrategy {
-    PER_LOOKUP("per-lookup"),
-    SINGLETON("singleton"),
-    KEEP_ALIVE("keep-alive"),
-    POOLABLE("poolable");
-
-    private final String id;
-
-    InstantiationStrategy(String id) {
-        this.id = id;
-    }
-
-    public String id() {
-        return this.id;
-    }
-}
+@Scope
+@Documented
+@Retention(RUNTIME)
+@Target({TYPE, METHOD})
+public @interface SessionScoped {}

api/maven-api-core/src/main/java/org/apache/maven/api/feature/Features.java

@@ -34,6 +34,8 @@ public final class Features {
 
     /**
      * Name of the Maven user property to enable or disable the build/consumer POM feature.
+     *
+     * TODO: v4: remove experimental bit
      */
     public static final String BUILDCONSUMER = "maven.experimental.buildconsumer";
 

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

@@ -0,0 +1,39 @@
+/*
+ * 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;
+
+import java.util.List;
+
+import org.apache.maven.api.annotations.Consumer;
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.plugin.descriptor.lifecycle.Lifecycle;
+
+/**
+ * Interface that can be provided by the plugin to wire in custom lifecycles
+ * leveraged using the {@link org.apache.maven.api.plugin.annotations.Execute}
+ * annotation.  If a {@code META-INF/maven/lifecycle.xml} file is packaged
+ * in the plugin, Maven will provide a default implementation that will parse
+ * the file and return the contained lifecycle definitions.
+ */
+@Experimental
+@Consumer
+public interface LifecycleProvider {
+
+    List<Lifecycle> getLifecycles();
+}

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

@@ -31,6 +31,9 @@
 
 /**
  * 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.
+ * The {@link Parameter} annotation can be added on fields to inject data
+ * from the plugin configuration or from other components.
  *
  * @since 4.0.0
  */
@@ -59,27 +62,20 @@
      * @return the required dependency resolution scope
      */
     @Nonnull
-    ResolutionScope requiresDependencyResolution() default ResolutionScope.NONE;
+    ResolutionScope dependencyResolutionRequired() default ResolutionScope.NONE;
 
     /**
      * the required dependency collection scope.
      * @return the required dependency collection scope
      */
     @Nonnull
-    ResolutionScope requiresDependencyCollection() default ResolutionScope.NONE;
-
-    /**
-     * your Mojo instantiation strategy. (Only <code>per-lookup</code> and <code>singleton</code> are supported)
-     * @return the instantiation strategy
-     */
-    @Nonnull
-    InstantiationStrategy instantiationStrategy() default InstantiationStrategy.PER_LOOKUP;
+    ResolutionScope dependencyCollectionRequired() default ResolutionScope.NONE;
 
     /**
      * does your mojo requires a project to be executed?
      * @return requires a project
      */
-    boolean requiresProject() default true;
+    boolean projectRequired() default true;
 
     /**
      * if the Mojo uses the Maven project and its child modules.
@@ -91,9 +87,10 @@
      * does this Mojo need to be online to be executed?
      * @return need to be online
      */
-    boolean requiresOnline() default false;
+    boolean onlineRequired() default false;
 
     /**
+     * TODO: v4: add a SPI for the configurator
      * configurator bean name.
      * @return the configurator bean name
      */