[MNG-7553] Introduce SettingsBuilder and ToolchainsBuilder services

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

@@ -35,7 +35,8 @@ public interface Artifact
 
     /**
      * Returns a unique identifier for this artifact.
-     * The identifier is composed of groupId, artifactId, version, classifier, extension
+     * The identifier is composed of groupId, artifactId, version, classifier, extension.
+     *
      * @return the unique identifier
      */
     default String key()
@@ -50,47 +51,47 @@ default String key()
     /**
      * The groupId of the artifact.
      *
-     * @return The groupId.
+     * @return the groupId
      */
     @Nonnull
     String getGroupId();
 
     /**
      * The artifactId of the artifact.
      *
-     * @return The artifactId.
+     * @return the artifactId
      */
     @Nonnull
     String getArtifactId();
 
     /**
      * The version of the artifact.
      *
-     * @return The version.
+     * @return the version
      */
     @Nonnull
     Version getVersion();
 
     /**
      * The classifier of the artifact.
      *
-     * @return The classifier or an empty string if none, never {@code null}.
+     * @return the classifier or an empty string if none, never {@code null}
      */
     @Nonnull
     String getClassifier();
 
     /**
      * The file extension of the artifact.
      *
-     * @return The extension.
+     * @return the extension
      */
     @Nonnull
     String getExtension();
 
     /**
      * Determines whether this artifact uses a snapshot version.
      *
-     * @return {@code true} if the artifact is a snapshot, {@code false} otherwise.
+     * @return {@code true} if the artifact is a snapshot, {@code false} otherwise
      * @see org.apache.maven.api.Session#isVersionSnapshot(String)
      */
     boolean isSnapshot();

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

@@ -37,39 +37,39 @@ public interface ArtifactCoordinate
     /**
      * The groupId of the artifact.
      *
-     * @return The groupId.
+     * @return the groupId
      */
     @Nonnull
     String getGroupId();
 
     /**
      * The artifactId of the artifact.
      *
-     * @return The artifactId.
+     * @return the artifactId
      */
     @Nonnull
     String getArtifactId();
 
     /**
      * The classifier of the artifact.
      *
-     * @return The classifier or an empty string if none, never {@code null}.
+     * @return the classifier or an empty string if none, never {@code null}
      */
     @Nonnull
     String getClassifier();
 
     /**
      * The version of the artifact.
      *
-     * @return The version.
+     * @return the version
      */
     @Nonnull
     VersionRange getVersion();
 
     /**
      * The extension of the artifact.
      *
-     * @return The extension or an empty string if none, never {@code null}.
+     * @return the extension or an empty string if none, never {@code null}
      */
     @Nonnull
     String getExtension();

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

@@ -27,11 +27,12 @@ public interface Dependency extends Artifact
     /**
      * The artifact type.
      *
-     * @return The artifact type, never {@code null}.
+     * @return the artifact type, never {@code null}
      */
     @Nonnull
     Type getType();
 
+    @Nonnull
     Scope getScope();
 
     boolean isOptional();

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

@@ -37,7 +37,7 @@ public interface DependencyCoordinate extends ArtifactCoordinate
     /**
      * The type of the artifact.
      *
-     * @return The type.
+     * @return the type
      */
     @Nonnull
     Type getType();

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

@@ -38,39 +38,39 @@ public interface Event
     /**
      * Gets the type of the event.
      *
-     * @return The type of the event, never {@code null}.
+     * @return the type of the event, never {@code null}
      */
     @Nonnull
     EventType getType();
 
     /**
      * Gets the session from which this event originates.
      *
-     * @return The current session, never {@code null}.
+     * @return the current session, never {@code null}
      */
     @Nonnull
     Session getSession();
 
     /**
      * Gets the current project (if any).
      *
-     * @return The current project or {@code empty()} if not applicable.
+     * @return the current project or {@code empty()} if not applicable
      */
     @Nonnull
     Optional<Project> getProject();
 
     /**
      * Gets the current mojo execution (if any).
      *
-     * @return The current mojo execution or {@code empty()} if not applicable.
+     * @return the current mojo execution or {@code empty()} if not applicable
      */
     @Nonnull
     Optional<MojoExecution> getMojoExecution();
 
     /**
      * Gets the exception that caused the event (if any).
      *
-     * @return The exception or {@code empty()} if none.
+     * @return the exception or {@code empty()} if none
      */
     Optional<Exception> getException();
 

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

@@ -67,8 +67,8 @@ public interface Node
     /**
      * Traverses this node and potentially its children using the specified visitor.
      *
-     * @param visitor The visitor to call back, must not be {@code null}.
-     * @return {@code true} to visit siblings nodes of this node as well, {@code false} to skip siblings.
+     * @param visitor the visitor to call back, must not be {@code null}
+     * @return {@code true} to visit siblings nodes of this node as well, {@code false} to skip siblings
      */
     boolean accept( @Nonnull NodeVisitor visitor );
 

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

@@ -38,15 +38,15 @@ public interface Repository
     /**
      * Gets the identifier of this repository.
      *
-     * @return The (case-sensitive) identifier, never {@code null}.
+     * @return the (case-sensitive) identifier, never {@code null}
      */
     @Nonnull
     String getId();
 
     /**
      * Gets the type of the repository, for example "default".
      *
-     * @return The (case-sensitive) type of the repository, never {@code null}.
+     * @return the (case-sensitive) type of the repository, never {@code null}
      */
     @Nonnull
     String getType();

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

@@ -56,15 +56,27 @@ public interface Session
     @Nonnull
     SessionData getData();
 
+    /**
+     * Gets the user properties to use for interpolation. The user properties have been configured directly by the user,
+     * e.g. via the {@code -Dkey=value} parameter on the command line.
+     *
+     * @return the user properties, never {@code null}
+     */
     @Nonnull
     Map<String, String> getUserProperties();
 
+    /**
+     * Gets the system properties to use for interpolation. The system properties are collected from the runtime
+     * environment such as {@link System#getProperties()} and environment variables.
+     *
+     * @return the system properties, never {@code null}
+     */
     @Nonnull
     Map<String, String> getSystemProperties();
 
     /**
      * Returns the current maven version
-     * @return the maven version, never {@code null}.
+     * @return the maven version, never {@code null}
      */
     @Nonnull
     String getMavenVersion();

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

@@ -47,18 +47,18 @@ public interface SessionData
     /**
      * Associates the specified session data with the given key.
      * 
-     * @param key The key under which to store the session data, must not be {@code null}.
-     * @param value The data to associate with the key, may be {@code null} to remove the mapping.
+     * @param key the key under which to store the session data, must not be {@code null}
+     * @param value the data to associate with the key, may be {@code null} to remove the mapping
      */
     void set( @Nonnull Object key, @Nullable Object value );
 
     /**
      * Associates the specified session data with the given key if the key is currently mapped to the given value. This
      * method provides an atomic compare-and-update of some key's value.
      * 
-     * @param key The key under which to store the session data, must not be {@code null}.
-     * @param oldValue The expected data currently associated with the key, may be {@code null}.
-     * @param newValue The data to associate with the key, may be {@code null} to remove the mapping.
+     * @param key the key under which to store the session data, must not be {@code null}
+     * @param oldValue the expected data currently associated with the key, may be {@code null}
+     * @param newValue the data to associate with the key, may be {@code null} to remove the mapping
      * @return {@code true} if the key mapping was successfully updated from the old value to the new value,
      *         {@code false} if the current key mapping didn't match the expected value and was not updated.
      */
@@ -67,18 +67,18 @@ public interface SessionData
     /**
      * Gets the session data associated with the specified key.
      * 
-     * @param key The key for which to retrieve the session data, must not be {@code null}.
-     * @return The session data associated with the key or {@code null} if none.
+     * @param key the key for which to retrieve the session data, must not be {@code null}
+     * @return the session data associated with the key or {@code null} if none
      */
     @Nullable
     Object get( @Nonnull Object key );
 
     /**
      * Retrieve of compute the data associated with the specified key.
      *
-     * @param key The key for which to retrieve the session data, must not be {@code null}.
-     * @param supplier The supplier will compute the new value.
-     * @return The session data associated with the key.
+     * @param key the key for which to retrieve the session data, must not be {@code null}
+     * @param supplier the supplier will compute the new value
+     * @return the session data associated with the key
      */
     @Nullable
     Object computeIfAbsent( @Nonnull Object key, @Nonnull Supplier<Object> supplier );

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

@@ -41,7 +41,7 @@ public interface Toolchain
     /**
      * Gets the platform tool executable.
      *
-     * @param toolName the tool platform independent tool name.
+     * @param toolName the tool platform independent tool name
      * @return file representing the tool executable, or null if the tool cannot be found
      */
     String findTool( String toolName );

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

@@ -36,8 +36,8 @@ public interface VersionRange
     /**
      * Determines whether the specified version is contained within this range.
      *
-     * @param version The version to test, must not be {@code null}.
-     * @return {@code true} if this range contains the specified version, {@code false} otherwise.
+     * @param version the version to test, must not be {@code null}
+     * @return {@code true} if this range contains the specified version, {@code false} otherwise
      */
     boolean contains( @Nonnull Version version );
 

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

@@ -39,7 +39,7 @@ public interface Mojo
      * This is the main trigger for the <code>Mojo</code> inside the <code>Maven</code> system, and allows
      * the <code>Mojo</code> to communicate errors.
      *
-     * @throws MojoException if a problem occurs.
+     * @throws MojoException if a problem occurs
      */
     void execute();
 

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

@@ -37,7 +37,7 @@ public class MojoException
     protected String longMessage;
 
     /**
-     * Construct a new <code>MojoExecutionException</code> exception providing the source and a short and long message:
+     * Construct a new <code>MojoException</code> exception providing the source and a short and long message:
      * these messages are used to improve the message written at the end of Maven build.
      */
     public MojoException( Object source, String shortMessage, String longMessage )
@@ -47,15 +47,6 @@ public MojoException( Object source, String shortMessage, String longMessage )
         this.longMessage = longMessage;
     }
 
-    /**
-     * Construct a new <code>MojoExecutionException</code> exception wrapping an underlying <code>Exception</code>
-     * and providing a <code>message</code>.
-     */
-    public MojoException( String message, Exception cause )
-    {
-        super( message, cause );
-    }
-
     /**
      * Construct a new <code>MojoExecutionException</code> exception wrapping an underlying <code>Throwable</code>
      * and providing a <code>message</code>.
@@ -78,7 +69,6 @@ public MojoException( String message )
      *
      * @param cause the cause which is saved for later retrieval by the {@link #getCause()} method.
      *              A {@code null} value is permitted, and indicates that the cause is nonexistent or unknown.
-     * @since 3.8.3
      */
     public MojoException( Throwable cause )
     {

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

@@ -37,7 +37,7 @@ public class ArtifactDeployerException
     private static final long serialVersionUID = 7421964724059077698L;
 
     /**
-     * @param message The message of the error.
+     * @param message the message of the error
      * @param e {@link Exception}
      */
     public ArtifactDeployerException( String message, Exception e )

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

@@ -38,8 +38,8 @@ public interface ArtifactInstaller extends Service
 {
     /**
      * @param request {@link ArtifactInstallerRequest}
-     * @throws ArtifactInstallerException in case of an error.
-     * @throws IllegalArgumentException in case {@code request} is {@code null}.
+     * @throws ArtifactInstallerException in case of an error
+     * @throws IllegalArgumentException in case {@code request} is {@code null}
      */
     void install( ArtifactInstallerRequest request );
 

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

@@ -35,7 +35,7 @@ public class ArtifactInstallerException
     private static final long serialVersionUID = 3652561971360586373L;
 
     /**
-     * @param message The message of the error.
+     * @param message the message of the error
      * @param e {@link Exception}
      */
     public ArtifactInstallerException( String message, Exception e )

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

@@ -38,9 +38,9 @@ public interface ArtifactResolver extends Service
     /**
      * @param request {@link ArtifactResolverRequest}
      * @return {@link ArtifactResolverResult}
-     * @throws ArtifactResolverException in case of an error.
+     * @throws ArtifactResolverException in case of an error
      * @throws IllegalArgumentException in case of parameter {@code buildingRequest} is {@code null} or
-     *             parameter {@code mavenArtifact} is {@code null} or invalid.
+     *             parameter {@code mavenArtifact} is {@code null} or invalid
      */
     ArtifactResolverResult resolve( ArtifactResolverRequest request );
 
@@ -50,7 +50,7 @@ public interface ArtifactResolver extends Service
      * @return {@link ArtifactResolverResult}
      * @throws ArtifactResolverException in case of an error.
      * @throws IllegalArgumentException in case of parameter {@code buildingRequest} is {@code null} or
-     *             parameter {@code coordinate} is {@code null} or invalid.
+     *             parameter {@code coordinate} is {@code null} or invalid
      */
     default ArtifactResolverResult resolve( Session session,
                                             Collection<? extends ArtifactCoordinate> coordinates )