This is an automated email from the ASF dual-hosted git repository.
gnodet pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/master by this push:
new 29e239000b Add some love to the API (#1310)
29e239000b is described below
commit 29e239000b28de94b052d2d5cb15812daee2c5a3
Author: Guillaume Nodet <gno...@gmail.com>
AuthorDate: Fri Nov 17 16:52:15 2023 +0100
Add some love to the API (#1310)
---
api/maven-api-core/pom.xml | 2 +-
.../src/main/java/org/apache/maven/api/Artifact.java | 1 +
.../org/apache/maven/api/ArtifactCoordinate.java | 1 +
.../main/java/org/apache/maven/api/Exclusion.java | 2 +-
.../src/main/java/org/apache/maven/api/Node.java | 6 +++++-
.../main/java/org/apache/maven/api/plugin/Log.java | 3 +++
.../maven/api/plugin/annotations/Component.java | 3 +++
.../apache/maven/api/plugin/annotations/Execute.java | 5 +++++
.../apache/maven/api/plugin/annotations/Mojo.java | 7 +++++++
.../maven/api/plugin/annotations/Parameter.java | 5 +++++
.../apache/maven/api/services/ArtifactInstaller.java | 3 ++-
.../java/org/apache/maven/api/services/Prompter.java | 20 ++++++++++++++------
.../apache/maven/api/services/xml/XmlFactory.java | 2 ++
.../maven/api/services/xml/XmlReaderRequest.java | 8 ++++++++
.../maven/api/services/xml/XmlWriterRequest.java | 6 ++++++
api/maven-api-meta/pom.xml | 4 ++--
api/maven-api-model/pom.xml | 2 +-
api/maven-api-settings/pom.xml | 2 +-
api/maven-api-xml/pom.xml | 4 ++--
.../main/java/org/apache/maven/api/xml/XmlNode.java | 2 ++
.../java/org/apache/maven/api/xml/package-info.java | 5 +++++
21 files changed, 77 insertions(+), 16 deletions(-)
diff --git a/api/maven-api-core/pom.xml b/api/maven-api-core/pom.xml
index 20f50385f0..ac94ace4ac 100644
--- a/api/maven-api-core/pom.xml
+++ b/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>
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/Artifact.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/Artifact.java
index 5cb9279b9d..b2d68f1faf 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Artifact.java
+++ b/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()
+ ':'
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinate.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinate.java
index 6de0b67f26..553e60fad3 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/ArtifactCoordinate.java
+++
b/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()
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
index 9a413017af..3c578c0962 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Exclusion.java
@@ -22,7 +22,7 @@ import org.apache.maven.api.annotations.Experimental;
import org.apache.maven.api.annotations.Nullable;
/**
- * A dependency exlusion.
+ * A dependency exclusion.
*
* @since 4.0.0
* @see DependencyCoordinate#getExclusions()
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/Node.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/Node.java
index 0b18298aaf..0d0e7037a9 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/Node.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/Node.java
@@ -26,6 +26,7 @@ import java.util.stream.Stream;
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 @@ import org.apache.maven.api.annotations.Nonnull;
*/
@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();
/**
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
index 9e19d5f2d0..2e28129d04 100644
--- a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
+++ b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/Log.java
@@ -20,6 +20,8 @@ package org.apache.maven.api.plugin;
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 @@ import java.util.function.Supplier;
*
* @since 4.0.0
*/
+@Provider
public interface Log {
/**
* @return true if the <b>debug</b> error level is enabled
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Component.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Component.java
index ab8cbf250a..305d3cc392 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Component.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Component.java
@@ -26,6 +26,7 @@ import java.lang.annotation.RetentionPolicy;
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 @@ 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 "";
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Execute.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Execute.java
index c133a127c8..1cfdfc6c77 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Execute.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Execute.java
@@ -26,6 +26,7 @@ import java.lang.annotation.RetentionPolicy;
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 @@ public @interface Execute {
* Only one of {@link #customPhase()} and {@link #phase()} must be set.
* @return the phase
*/
+ @Nonnull
LifecyclePhase phase() default LifecyclePhase.NONE;
/**
@@ -52,6 +54,7 @@ public @interface Execute {
* Only one of {@link #customPhase()} and {@link #phase()} must be set.
* @return the custom phase id
*/
+ @Nonnull
String customPhase() default "";
/**
@@ -59,6 +62,7 @@ public @interface Execute {
* another goal of the same plugin.
* @return the goal
*/
+ @Nonnull
String goal() default "";
/**
@@ -68,5 +72,6 @@ public @interface Execute {
* @see <a
href="https://maven.apache.org/maven-plugin-api/lifecycle-mappings.html";>Lifecycle
Mappings</a>
* @return the lifecycle id
*/
+ @Nonnull
String lifecycle() default "";
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Mojo.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Mojo.java
index b32404e2a6..de5f7b016a 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Mojo.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Mojo.java
@@ -27,6 +27,7 @@ import java.lang.annotation.Target;
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 @@ public @interface Mojo {
* 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 @@ public @interface Mojo {
* configurator bean name.
* @return the configurator bean name
*/
+ @Nonnull
String configurator() default "";
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Parameter.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Parameter.java
index 5c2dc51f44..415f6a507d 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Parameter.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/plugin/annotations/Parameter.java
@@ -26,6 +26,7 @@ import java.lang.annotation.RetentionPolicy;
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 @@ public @interface Parameter {
* 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 @@ public @interface Parameter {
* properties.
* @return property name
*/
+ @Nonnull
String property() default "";
/**
@@ -70,6 +74,7 @@ public @interface Parameter {
* PluginParameterExpressionEvaluator</a>.
* @return the default value
*/
+ @Nonnull
String defaultValue() default "";
/**
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstaller.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstaller.java
index 41598baa22..00500ab7eb 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstaller.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/ArtifactInstaller.java
@@ -25,6 +25,7 @@ import org.apache.maven.api.Artifact;
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
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Prompter.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Prompter.java
index 0878961a23..29f2a75fc7 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/Prompter.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/Prompter.java
@@ -22,6 +22,8 @@ import java.util.List;
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 @@ public interface Prompter extends Service {
* @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 @@ public interface Prompter extends Service {
* @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 @@ public interface Prompter extends Service {
* @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 @@ public interface Prompter extends Service {
* @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 @@ public interface Prompter extends Service {
* @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;
}
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
index 3fbd2fdcb0..6fae7f943a 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlFactory.java
@@ -97,6 +97,7 @@ public interface XmlFactory<T> extends Service {
* @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 @@ public interface XmlFactory<T> extends Service {
* @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);
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
index 69f3cdeaea..3087e3a0b9 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlReaderRequest.java
+++
b/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.Experimental;
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 @@ import org.apache.maven.api.annotations.NotThreadSafe;
@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();
diff --git
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
index e60ec76cc1..f9a305dc3f 100644
---
a/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
+++
b/api/maven-api-core/src/main/java/org/apache/maven/api/services/xml/XmlWriterRequest.java
@@ -23,6 +23,8 @@ import java.io.Writer;
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 @@ import org.apache.maven.api.annotations.Experimental;
@Experimental
public interface XmlWriterRequest<T> {
+ @Nullable
Path getPath();
+ @Nullable
OutputStream getOutputStream();
+ @Nullable
Writer getWriter();
+ @Nonnull
T getContent();
static <T> XmlWriterRequestBuilder<T> builder() {
diff --git a/api/maven-api-meta/pom.xml b/api/maven-api-meta/pom.xml
index 688422645c..820af57c95 100644
--- a/api/maven-api-meta/pom.xml
+++ b/api/maven-api-meta/pom.xml
@@ -27,7 +27,7 @@
</parent>
<artifactId>maven-api-meta</artifactId>
- <name>Maven 4 API Meta annotations</name>
- <description>Java annotations for Maven 4 Immutable API.</description>
+ <name>Maven 4 API :: Meta annotations</name>
+ <description>Maven 4 API - Java meta annotations.</description>
</project>
diff --git a/api/maven-api-model/pom.xml b/api/maven-api-model/pom.xml
index 58a2640688..559c83962d 100644
--- a/api/maven-api-model/pom.xml
+++ b/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>
diff --git a/api/maven-api-settings/pom.xml b/api/maven-api-settings/pom.xml
index 4878366485..145724a61c 100644
--- a/api/maven-api-settings/pom.xml
+++ b/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>
diff --git a/api/maven-api-xml/pom.xml b/api/maven-api-xml/pom.xml
index a9fd26280b..f950d4990c 100644
--- a/api/maven-api-xml/pom.xml
+++ b/api/maven-api-xml/pom.xml
@@ -27,8 +27,8 @@
</parent>
<artifactId>maven-api-xml</artifactId>
- <name>Maven 4 API XML</name>
- <description>Maven 4 API immutable XML helper.</description>
+ <name>Maven 4 API :: XML</name>
+ <description>Maven 4 API - Immutable XML.</description>
<dependencies>
<dependency>
diff --git
a/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlNode.java
b/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlNode.java
index e0e3d4b1fa..df6335ee8d 100644
--- a/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlNode.java
+++ b/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/XmlNode.java
@@ -30,6 +30,8 @@ import org.apache.maven.api.annotations.ThreadSafe;
/**
* An immutable xml node.
*
+ * TODO: v4: add support for namespaces
+ *
* @since 4.0.0
*/
@Experimental
diff --git
a/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/package-info.java
b/api/maven-api-xml/src/main/java/org/apache/maven/api/xml/package-info.java
new file mode 100644
index 0000000000..db25d3a153
--- /dev/null
+++ b/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;
