Add some love to the API (#1310)

api/maven-api-core/pom.xml

@@ -28,7 +28,7 @@
 
   <artifactId>maven-api-core</artifactId>
   <name>Maven 4 API :: Core</name>
-  <description>Maven 4 API - Maven Core APIs.</description>
+  <description>Maven 4 API - Maven Core API</description>
 
   <dependencies>
     <dependency>

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

@@ -37,6 +37,7 @@ public interface Artifact {
      *
      * @return the unique identifier
      */
+    @Nonnull
     default String key() {
         return getGroupId()
                 + ':'

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

@@ -75,6 +75,7 @@ public interface ArtifactCoordinate {
     /**
      * Unique id identifying this artifact
      */
+    @Nonnull
     default String getId() {
         return getGroupId()
                 + ":" + getArtifactId()

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

@@ -22,7 +22,7 @@
 import org.apache.maven.api.annotations.Nullable;
 
 /**
- * A dependency exlusion.
+ * A dependency exclusion.
  *
  * @since 4.0.0
  * @see DependencyCoordinate#getExclusions()

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

@@ -26,6 +26,7 @@
 import org.apache.maven.api.annotations.Experimental;
 import org.apache.maven.api.annotations.Immutable;
 import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.annotations.Provider;
 
 /**
  * Represents a dependency node within a Maven project's dependency collector.
@@ -35,6 +36,7 @@
  */
 @Experimental
 @Immutable
+@Provider
 public interface Node {
 
     /**
@@ -78,13 +80,15 @@ public interface Node {
      * @param filter the filter to apply
      * @return a new filtered graph
      */
-    Node filter(Predicate<Node> filter);
+    @Nonnull
+    Node filter(@Nonnull Predicate<Node> filter);
 
     /**
      * Returns a string representation of this dependency node.
      *
      * @return the string representation
      */
+    @Nonnull
     String asString();
 
     /**

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

@@ -20,6 +20,8 @@
 
 import java.util.function.Supplier;
 
+import org.apache.maven.api.annotations.Provider;
+
 /**
  * This interface supplies the API for providing feedback to the user from the <code>Mojo</code>, using standard
  * <code>Maven</code> channels.<br>
@@ -30,6 +32,7 @@
  *
  * @since 4.0.0
  */
+@Provider
 public interface Log {
     /**
      * @return true if the <b>debug</b> error level is enabled

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

@@ -26,6 +26,7 @@
 import java.lang.annotation.Target;
 
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * Used to configure injection of Plexus components by
@@ -44,11 +45,13 @@
      * 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 "";
 }

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

@@ -26,6 +26,7 @@
 import java.lang.annotation.Target;
 
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * Used if your Mojo needs to fork a <a href="/ref/3.0.4/maven-core/lifecycles.html">lifecycle</a>.
@@ -44,6 +45,7 @@
      * Only one of {@link #customPhase()} and {@link #phase()} must be set.
      * @return the phase
      */
+    @Nonnull
     LifecyclePhase phase() default LifecyclePhase.NONE;
 
     /**
@@ -52,6 +54,7 @@
      * Only one of {@link #customPhase()} and {@link #phase()} must be set.
      * @return the custom phase id
      */
+    @Nonnull
     String customPhase() default "";
 
     /**
@@ -59,6 +62,7 @@
      * another goal of the same plugin.
      * @return the goal
      */
+    @Nonnull
     String goal() default "";
 
     /**
@@ -68,5 +72,6 @@
      * @see <a href="https://maven.apache.org/maven-plugin-api/lifecycle-mappings.html">Lifecycle Mappings</a>
      * @return the lifecycle id
      */
+    @Nonnull
     String lifecycle() default "";
 }

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

@@ -27,6 +27,7 @@
 
 import org.apache.maven.api.ResolutionScope;
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * This annotation will mark your class as a Mojo (ie. goal in a Maven plugin).
@@ -43,30 +44,35 @@
      * goal name (required).
      * @return the goal name
      */
+    @Nonnull
     String name();
 
     /**
      * default phase to bind your mojo.
      * @return the default phase
      */
+    @Nonnull
     LifecyclePhase defaultPhase() default LifecyclePhase.NONE;
 
     /**
      * the required dependency resolution scope.
      * @return the required dependency resolution scope
      */
+    @Nonnull
     ResolutionScope requiresDependencyResolution() 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;
 
     /**
@@ -91,5 +97,6 @@
      * configurator bean name.
      * @return the configurator bean name
      */
+    @Nonnull
     String configurator() default "";
 }

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

@@ -26,6 +26,7 @@
 import java.lang.annotation.Target;
 
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * Used to configure your Mojo parameters to be injected by
@@ -48,12 +49,14 @@
      * name of the bean property used to get/set the field: by default, field name is used.
      * @return the name of the bean property
      */
+    @Nonnull
     String name() default "";
 
     /**
      * alias supported to get parameter value.
      * @return the alias
      */
+    @Nonnull
     String alias() default "";
 
     /**
@@ -61,6 +64,7 @@
      * properties.
      * @return property name
      */
+    @Nonnull
     String property() default "";
 
     /**
@@ -70,6 +74,7 @@
      * PluginParameterExpressionEvaluator</a>.
      * @return the default value
      */
+    @Nonnull
     String defaultValue() default "";
 
     /**

api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstaller.java

@@ -25,6 +25,7 @@
 import org.apache.maven.api.Service;
 import org.apache.maven.api.Session;
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
 
 /**
  * Installs {@link Artifact}s to the local repository.
@@ -39,7 +40,7 @@ public interface ArtifactInstaller extends Service {
      * @throws ArtifactInstallerException in case of an error
      * @throws IllegalArgumentException in case {@code request} is {@code null}
      */
-    void install(ArtifactInstallerRequest request);
+    void install(@Nonnull ArtifactInstallerRequest request);
 
     /**
      * @param session the repository session

api/maven-api-core/src/main/java/org/apache/maven/api/services/Prompter.java

@@ -22,6 +22,8 @@
 
 import org.apache.maven.api.Service;
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.annotations.Nullable;
 
 /**
  * Service used to interact with the end user.
@@ -37,7 +39,8 @@ public interface Prompter extends Service {
      * @return the string entered by the user
      * @throws PrompterException if an exception occurs
      */
-    default String prompt(String message) throws PrompterException {
+    @Nonnull
+    default String prompt(@Nullable String message) throws PrompterException {
         return prompt(message, null, null);
     }
 
@@ -49,7 +52,8 @@ default String prompt(String message) throws PrompterException {
      * @return the string entered by the user
      * @throws PrompterException if an exception occurs
      */
-    default String prompt(String message, String defaultReply) throws PrompterException {
+    @Nonnull
+    default String prompt(@Nullable String message, @Nullable String defaultReply) throws PrompterException {
         return prompt(message, null, defaultReply);
     }
 
@@ -61,7 +65,8 @@ default String prompt(String message, String defaultReply) throws PrompterExcept
      * @return the string entered by the user
      * @throws PrompterException if an exception occurs
      */
-    default String prompt(String message, List<String> possibleValues) throws PrompterException {
+    @Nonnull
+    default String prompt(@Nullable String message, @Nullable List<String> possibleValues) throws PrompterException {
         return prompt(message, possibleValues, null);
     }
 
@@ -74,7 +79,9 @@ default String prompt(String message, List<String> possibleValues) throws Prompt
      * @return the string entered by the user
      * @throws PrompterException if an exception occurs
      */
-    String prompt(String message, List<String> possibleValues, String defaultReply) throws PrompterException;
+    @Nonnull
+    String prompt(@Nullable String message, @Nullable List<String> possibleValues, @Nullable String defaultReply)
+            throws PrompterException;
 
     /**
      * Prompts the user for a password.
@@ -83,7 +90,8 @@ default String prompt(String message, List<String> possibleValues) throws Prompt
      * @return the password entered by the user
      * @throws PrompterException if an exception occurs
      */
-    String promptForPassword(String message) throws PrompterException;
+    @Nonnull
+    String promptForPassword(@Nullable String message) throws PrompterException;
 
     /**
      * Displays a message to the user.
@@ -91,5 +99,5 @@ default String prompt(String message, List<String> possibleValues) throws Prompt
      * @param message the message to display
      * @throws PrompterException if an exception occurs
      */
-    void showMessage(String message) throws PrompterException;
+    void showMessage(@Nullable String message) throws PrompterException;
 }

api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java

@@ -97,6 +97,7 @@ default void write(@Nonnull T content, @Nonnull Writer writer) throws XmlWriterE
      * @throws XmlReaderException if an error occurs during the parsing
      * @see #toXmlString(Object)
      */
+    @Nonnull
     default T fromXmlString(@Nonnull String xml) throws XmlReaderException {
         return read(new StringReader(xml));
     }
@@ -109,6 +110,7 @@ default T fromXmlString(@Nonnull String xml) throws XmlReaderException {
      * @throws XmlWriterException if an error occurs during the transformation
      * @see #fromXmlString(String)
      */
+    @Nonnull
     default String toXmlString(@Nonnull T content) throws XmlWriterException {
         StringWriter sw = new StringWriter();
         write(content, sw);

api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java

@@ -27,6 +27,7 @@
 import org.apache.maven.api.annotations.Immutable;
 import org.apache.maven.api.annotations.Nonnull;
 import org.apache.maven.api.annotations.NotThreadSafe;
+import org.apache.maven.api.annotations.Nullable;
 
 /**
  * An XML reader request.
@@ -37,20 +38,27 @@
 @Immutable
 public interface XmlReaderRequest {
 
+    @Nullable
     Path getPath();
 
+    @Nullable
     URL getURL();
 
+    @Nullable
     InputStream getInputStream();
 
+    @Nullable
     Reader getReader();
 
+    @Nullable
     Transformer getTransformer();
 
     boolean isStrict();
 
+    @Nullable
     String getModelId();
 
+    @Nullable
     String getLocation();
 
     boolean isAddDefaultEntities();

api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java

@@ -23,6 +23,8 @@
 import java.nio.file.Path;
 
 import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.annotations.Nullable;
 
 /**
  * An XML writer request.
@@ -33,12 +35,16 @@
 @Experimental
 public interface XmlWriterRequest<T> {
 
+    @Nullable
     Path getPath();
 
+    @Nullable
     OutputStream getOutputStream();
 
+    @Nullable
     Writer getWriter();
 
+    @Nonnull
     T getContent();
 
     static <T> XmlWriterRequestBuilder<T> builder() {

api/maven-api-meta/pom.xml

@@ -27,7 +27,7 @@
   </parent>
 
   <artifactId>maven-api-meta</artifactId>
-  <name>Maven 4 API Meta annotations</name>
+  <name>Maven 4 API :: Meta annotations</name>
-  <description>Java annotations for Maven 4 Immutable API.</description>
+  <description>Maven 4 API - Java meta annotations.</description>
 
 </project>

api/maven-api-model/pom.xml

@@ -29,7 +29,7 @@ under the License.
   <artifactId>maven-api-model</artifactId>
 
   <name>Maven 4 API :: Model</name>
-  <description>Maven 4 API - Immutable Model for Maven POM (Project Object Model)</description>
+  <description>Maven 4 API - Immutable Model for Maven POM (Project Object Model).</description>
 
   <dependencies>
     <dependency>

api/maven-api-settings/pom.xml

@@ -29,7 +29,7 @@ under the License.
   <artifactId>maven-api-settings</artifactId>
 
   <name>Maven 4 API :: Settings</name>
-  <description>Maven 4 API - Immutable Settings model</description>
+  <description>Maven 4 API - Immutable Settings model.</description>
 
   <dependencies>
     <dependency>

api/maven-api-xml/pom.xml

@@ -27,8 +27,8 @@
   </parent>
 
   <artifactId>maven-api-xml</artifactId>
-  <name>Maven 4 API XML</name>
+  <name>Maven 4 API :: XML</name>
-  <description>Maven 4 API immutable XML helper.</description>
+  <description>Maven 4 API - Immutable XML.</description>
 
   <dependencies>
     <dependency>

api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlNode.java

@@ -30,6 +30,8 @@
 /**
  * An immutable xml node.
  *
+ * TODO: v4: add support for namespaces
+ *
  * @since 4.0.0
  */
 @Experimental

api/maven-api-xml/src/main/java/org/apache/maven/api/xml/package-info.java

@@ -0,0 +1,5 @@
+// CHECKSTYLE_OFF: RegexpHeader
+/**
+ * Maven immutable XML api.
+ */
+package org.apache.maven.api.xml;