[MNG-7580] Introduce new SettingsBuilder and ToolchainsBuilder services

api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilderProblem.java → api/maven-api-core/src/main/java/org/apache/maven/api/services/BuilderProblem.java

@@ -20,6 +20,9 @@
  */
 
 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.Nullable;
 
 /**
  * Describes a problem that was encountered during project building. A problem can either be an exception that was
@@ -28,7 +31,8 @@
  * @since 4.0
  */
 @Experimental
-public interface ProjectBuilderProblem
+@Immutable
+public interface BuilderProblem
 {
 
     /**
@@ -37,23 +41,24 @@ public interface ProjectBuilderProblem
      * track the problem back to its origin. A concrete example for such a source hint can be the file path or URL from
      * which the settings were read.
      *
-     * @return The hint about the source of the problem or an empty string if unknown, never {@code null}.
+     * @return the hint about the source of the problem or an empty string if unknown, never {@code null}
      */
+    @Nonnull
     String getSource();
 
     /**
      * Gets the one-based index of the line containing the problem. The line number should refer to some text file that
      * is given by {@link #getSource()}.
      *
-     * @return The one-based index of the line containing the problem or a non-positive value if unknown.
+     * @return the one-based index of the line containing the problem or a non-positive value if unknown
      */
     int getLineNumber();
 
     /**
      * Gets the one-based index of the column containing the problem. The column number should refer to some text file
      * that is given by {@link #getSource()}.
      *
-     * @return The one-based index of the column containing the problem or non-positive value if unknown.
+     * @return the one-based index of the column containing the problem or non-positive value if unknown
      */
     int getColumnNumber();
 
@@ -62,29 +67,47 @@ public interface ProjectBuilderProblem
      * {@link #getSource()}, {@link #getLineNumber()} and {@link #getColumnNumber()}. The exact syntax of the returned
      * value is undefined.
      *
-     * @return The location of the problem, never {@code null}.
+     * @return the location of the problem, never {@code null}
      */
+    @Nonnull
     String getLocation();
 
     /**
      * Gets the exception that caused this problem (if any).
      *
-     * @return The exception that caused this problem or {@code null} if not applicable.
+     * @return the exception that caused this problem or {@code null} if not applicable
      */
+    @Nullable
     Exception getException();
 
     /**
      * Gets the message that describes this problem.
      *
-     * @return The message describing this problem, never {@code null}.
+     * @return the message describing this problem, never {@code null}
      */
+    @Nonnull
     String getMessage();
 
     /**
      * Gets the severity level of this problem.
      *
-     * @return The severity level of this problem, never {@code null}.
+     * @return the severity level of this problem, never {@code null}
      */
-    ProjectBuilderProblemSeverity getSeverity();
+    @Nonnull
+    Severity getSeverity();
 
+    /**
+     * The different severity levels for a problem, in decreasing order.
+     *
+     * @since 4.0
+     */
+    @Experimental
+    enum Severity
+    {
+
+        FATAL, //
+        ERROR, //
+        WARNING //
+
+    }
 }

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

@@ -51,13 +51,13 @@ public interface ProjectBuilder extends Service
      * Creates a {@link org.apache.maven.api.Project} from a POM file.
      *
      * @param session the {@link Session}, must not be {@code null}
-     * @param source the {@link ProjectBuilderSource}, must not be {@code null}
+     * @param source The {@link Source}, must not be {@code null}
      * @throws ProjectBuilderException if the project cannot be created
      * @throws IllegalArgumentException if an argument is {@code null} or invalid
      * @see #build(ProjectBuilderRequest)
      */
     @Nonnull
-    default ProjectBuilderResult build( @Nonnull Session session, @Nonnull ProjectBuilderSource source )
+    default ProjectBuilderResult build( @Nonnull Session session, @Nonnull Source source )
     {
         return build( ProjectBuilderRequest.build( session, source ) );
     }

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

@@ -52,7 +52,7 @@ public interface ProjectBuilderRequest
     Optional<Path> getPath();
 
     @Nonnull
-    Optional<ProjectBuilderSource> getSource();
+    Optional<Source> getSource();
 
     @Nonnull
     Optional<Artifact> getArtifact();
@@ -69,7 +69,7 @@ public interface ProjectBuilderRequest
     boolean isResolveDependencies();
 
     @Nonnull
-    static ProjectBuilderRequest build( @Nonnull Session session, @Nonnull ProjectBuilderSource source )
+    static ProjectBuilderRequest build( @Nonnull Session session, @Nonnull Source source )
     {
         return builder()
                 .session( nonNull( session, "session cannot be null" ) )
@@ -115,7 +115,7 @@ class ProjectBuilderRequestBuilder
     {
         Session session;
         Path path;
-        ProjectBuilderSource source;
+        Source source;
         Artifact artifact;
         ArtifactCoordinate coordinate;
         boolean allowStubModel;
@@ -139,7 +139,7 @@ public ProjectBuilderRequestBuilder path( Path path )
             return this;
         }
 
-        public ProjectBuilderRequestBuilder source( ProjectBuilderSource source )
+        public ProjectBuilderRequestBuilder source( Source source )
         {
             this.source = source;
             return this;
@@ -179,7 +179,7 @@ private static class DefaultProjectBuilderRequest extends BaseRequest
             implements ProjectBuilderRequest
         {
             private final Path path;
-            private final ProjectBuilderSource source;
+            private final Source source;
             private final Artifact artifact;
             private final ArtifactCoordinate coordinate;
             private final boolean allowStubModel;
@@ -190,7 +190,7 @@ private static class DefaultProjectBuilderRequest extends BaseRequest
             @SuppressWarnings( "checkstyle:ParameterNumber" )
             DefaultProjectBuilderRequest( @Nonnull Session session,
                                           @Nullable Path path,
-                                          @Nullable ProjectBuilderSource source,
+                                          @Nullable Source source,
                                           @Nullable Artifact artifact,
                                           @Nullable ArtifactCoordinate coordinate,
                                           boolean allowStubModel,
@@ -218,7 +218,7 @@ public Optional<Path> getPath()
 
             @Nonnull
             @Override
-            public Optional<ProjectBuilderSource> getSource()
+            public Optional<Source> getSource()
             {
                 return Optional.ofNullable( source );
             }

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

@@ -70,7 +70,7 @@ public interface ProjectBuilderResult
      * @return the problems that were encountered during the project building, can be empty but never {@code null}
      */
     @Nonnull
-    Collection<ProjectBuilderProblem> getProblems();
+    Collection<BuilderProblem> getProblems();
 
     /**
      * Gets the result of the dependency resolution for the project.

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

@@ -0,0 +1,71 @@
+package org.apache.maven.api.services;
+
+/*
+ * 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.
+ */
+
+import java.nio.file.Path;
+
+import org.apache.maven.api.Service;
+import org.apache.maven.api.Session;
+import org.apache.maven.api.annotations.Nonnull;
+
+/**
+ * Builds the effective settings from a user settings file and/or a global settings file.
+ */
+public interface SettingsBuilder extends Service
+{
+
+    /**
+     * Builds the effective settings of the specified settings files.
+     *
+     * @param request the settings building request that holds the parameters, must not be {@code null}
+     * @return the result of the settings building, never {@code null}
+     * @throws SettingsBuilderException if the effective settings could not be built
+     */
+    @Nonnull
+    SettingsBuilderResult build( @Nonnull SettingsBuilderRequest request );
+
+    /**
+     * Builds the effective settings of the specified settings sources.
+     *
+     * @return the result of the settings building, never {@code null}
+     * @throws SettingsBuilderException if the effective settings could not be built
+     */
+    @Nonnull
+    default SettingsBuilderResult build( @Nonnull Session session,
+                                         @Nonnull Source globalSettingsSource,
+                                         @Nonnull Source userSettingsSource )
+    {
+        return build( SettingsBuilderRequest.build( session, globalSettingsSource, userSettingsSource ) );
+    }
+
+    /**
+     * Builds the effective settings of the specified settings paths.
+     *
+     * @return the result of the settings building, never {@code null}
+     * @throws SettingsBuilderException if the effective settings could not be built
+     */
+    @Nonnull
+    default SettingsBuilderResult build( @Nonnull Session session,
+                                         @Nonnull Path globalSettingsPath,
+                                         @Nonnull Path userSettingsPath )
+    {
+        return build( SettingsBuilderRequest.build( session, globalSettingsPath, userSettingsPath ) );
+    }
+}

api/maven-api-core/src/main/java/org/apache/maven/api/services/ProjectBuilderProblemSeverity.java → api/maven-api-core/src/main/java/org/apache/maven/api/services/SettingsBuilderException.java

@@ -9,7 +9,7 @@
  * "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
+ *  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
@@ -22,16 +22,22 @@
 import org.apache.maven.api.annotations.Experimental;
 
 /**
- * The different severity levels for a problem, in decreasing order.
+ * The Exception class throw by the {@link SettingsBuilder}.
  *
  * @since 4.0
  */
 @Experimental
-public enum ProjectBuilderProblemSeverity
+public class SettingsBuilderException
+    extends MavenException
 {
+    /**
+     * @param message the message to give
+     * @param e the {@link Exception}
+     */
+    public SettingsBuilderException( String message, Exception e )
+    {
+        super( message, e );
+    }
 
-    FATAL, //
-    ERROR, //
-    WARNING //
-
+    // TODO: add SettingsBuilderResult
 }