[MNG-8120] Refactor ModelBuilder and ProjectBuilder

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

@@ -39,7 +39,7 @@
 @Immutable
 public interface Artifact {
     /**
-     * {@return a unique identifier for this artifact}.
+     * {@return a unique identifier for this artifact}
      * The identifier is composed of groupId, artifactId, extension, classifier, and version.
      *
      * @see ArtifactCoordinates#getId()
@@ -58,23 +58,24 @@ default String key() {
     }
 
     /**
-     * {@return the group identifier of the artifact}.
+     * {@return the group identifier of the artifact}
      *
      * @see ArtifactCoordinates#getGroupId()
      */
     @Nonnull
     String getGroupId();
 
     /**
-     * {@return the identifier of the artifact}.
+     * {@return the identifier of the artifact}
      *
      * @see ArtifactCoordinates#getArtifactId()
      */
     @Nonnull
     String getArtifactId();
 
     /**
-     * {@return the version of the artifact}. Contrarily to {@link ArtifactCoordinates},
+     * {@return the version of the artifact}
+     * Contrarily to {@link ArtifactCoordinates},
      * each {@code Artifact} is associated to a specific version instead of a range of versions.
      * If the {@linkplain #getBaseVersion() base version} contains a meta-version such as {@code SNAPSHOT},
      * those keywords are replaced by, for example, the actual timestamp.
@@ -85,7 +86,7 @@ default String key() {
     Version getVersion();
 
     /**
-     * {@return the version or meta-version of the artifact}.
+     * {@return the version or meta-version of the artifact}
      * A meta-version is a version suffixed with the {@code SNAPSHOT} keyword.
      * Meta-versions are represented in a base version by their symbols (e.g., {@code SNAPSHOT}),
      * while they are replaced by, for example, the actual timestamp in the {@linkplain #getVersion() version}.
@@ -121,7 +122,7 @@ default String key() {
     boolean isSnapshot();
 
     /**
-     * {@return coordinates with the same identifiers as this artifact}.
+     * {@return coordinates with the same identifiers as this artifact}
      * This is a shortcut for {@code session.createArtifactCoordinates(artifact)}.
      *
      * @see org.apache.maven.api.Session#createArtifactCoordinates(Artifact)

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

@@ -33,13 +33,13 @@
 @Immutable
 public interface ArtifactCoordinates {
     /**
-     * {@return the group identifier of the artifact}.
+     * {@return the group identifier of the artifact}
      */
     @Nonnull
     String getGroupId();
 
     /**
-     * {@return the identifier of the artifact}.
+     * {@return the identifier of the artifact}
      */
     @Nonnull
     String getArtifactId();
@@ -53,7 +53,7 @@ public interface ArtifactCoordinates {
     String getClassifier();
 
     /**
-     * {@return the specific version, range of versions or meta-version of the artifact}.
+     * {@return the specific version, range of versions or meta-version of the artifact}
      * A meta-version is a version suffixed with the {@code SNAPSHOT} keyword.
      */
     @Nonnull

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

@@ -271,7 +271,7 @@ public final class Constants {
      * @since 4.0.0
      */
     @Config(type = "java.lang.Integer", defaultValue = "cores/2 + 1")
-    public static final String MAVEN_PROJECT_BUILDER_PARALLELISM = "maven.projectBuilder.parallelism";
+    public static final String MAVEN_MODEL_BUILDER_PARALLELISM = "maven.modelBuilder.parallelism";
 
     /**
      * User property for enabling/disabling the consumer POM feature.

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

@@ -36,7 +36,8 @@
 @Immutable
 public interface Dependency extends Artifact {
     /**
-     * {@return the type of the dependency}. A dependency can be a <abbr>JAR</abbr> file,
+     * {@return the type of the dependency}
+     * A dependency can be a <abbr>JAR</abbr> file,
      * a modular-<abbr>JAR</abbr> if it is intended to be placed on the module-path,
      * a <abbr>JAR</abbr> containing test classes, <i>etc.</i>
      *
@@ -46,7 +47,7 @@ public interface Dependency extends Artifact {
     Type getType();
 
     /**
-     * {@return the time at which the dependency will be used}.
+     * {@return the time at which the dependency will be used}
      * If may be, for example, at compile time only, at run time or at test time.
      *
      * @see DependencyCoordinates#getScope()

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

@@ -39,15 +39,16 @@
 @Immutable
 public interface DependencyCoordinates extends ArtifactCoordinates {
     /**
-     * {@return the type of the dependency}. A dependency can be a <abbr>JAR</abbr> file,
+     * {@return the type of the dependency}
+     * A dependency can be a <abbr>JAR</abbr> file,
      * a modular-<abbr>JAR</abbr> if it is intended to be placed on the module-path,
      * a <abbr>JAR</abbr> containing test classes, <i>etc.</i>
      */
     @Nonnull
     Type getType();
 
     /**
-     * {@return the time at which the dependency will be used}.
+     * {@return the time at which the dependency will be used}
      * If may be, for example, at compile time only, at run time or at test time.
      */
     @Nonnull
@@ -62,7 +63,7 @@ public interface DependencyCoordinates extends ArtifactCoordinates {
     Boolean getOptional();
 
     /**
-     * {@return transitive dependencies to exclude}.
+     * {@return transitive dependencies to exclude}
      */
     @Nonnull
     Collection<Exclusion> getExclusions();

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

@@ -123,7 +123,7 @@ public String[] option(Iterable<? extends Path> paths) {
     String name();
 
     /**
-     * {@return a string representation for this extensible enum describing a path type}.
+     * {@return a string representation for this extensible enum describing a path type}
      * For example {@code "PathType[PATCH_MODULE:foo.bar]"}.
      */
     @Nonnull

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

@@ -224,6 +224,13 @@ default String getId() {
 
     /**
      * Returns project parent project, if any.
+     * <p>
+     * Note that the model may have a parent defined, but an empty parent
+     * project may be returned if the parent comes from a remote repository,
+     * as a {@code Project} must refer to a buildable project.
+     *
+     * @return an optional containing the parent project
+     * @see Model#getParent()
      */
     @Nonnull
     Optional<Project> getParent();

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

@@ -37,7 +37,7 @@
 @Provider
 public interface Log {
     /**
-     * {@return true if the <b>debug</b> error level is enabled}.
+     * {@return true if the <b>debug</b> error level is enabled}
      */
     boolean isDebugEnabled();
 
@@ -70,7 +70,7 @@ public interface Log {
     void debug(Supplier<String> content, Throwable error);
 
     /**
-     * {@return true if the <b>info</b> error level is enabled}.
+     * {@return true if the <b>info</b> error level is enabled}
      */
     boolean isInfoEnabled();
 
@@ -103,7 +103,7 @@ public interface Log {
     void info(Supplier<String> content, Throwable error);
 
     /**
-     * {@return true if the <b>warn</b> error level is enabled}.
+     * {@return true if the <b>warn</b> error level is enabled}
      */
     boolean isWarnEnabled();
 
@@ -136,7 +136,7 @@ public interface Log {
     void warn(Supplier<String> content, Throwable error);
 
     /**
-     * {@return true if the <b>error</b> error level is enabled}.
+     * {@return true if the <b>error</b> error level is enabled}
      */
     boolean isErrorEnabled();
 

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

@@ -97,7 +97,7 @@ public interface DependencyResolverResult {
     Map<PathType, List<Path>> getDispatchedPaths();
 
     /**
-     * {@return all dependencies associated to their paths}.
+     * {@return all dependencies associated to their paths}
      * Some dependencies may be associated to a null value if there is no path available.
      */
     @Nonnull

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

@@ -31,9 +31,12 @@ public interface ModelBuilder extends Service {
 
     List<String> VALID_MODEL_VERSIONS = List.of(MODEL_VERSION_4_0_0, MODEL_VERSION_4_1_0);
 
-    ModelBuilderResult build(ModelBuilderRequest request) throws ModelBuilderException;
+    ModelBuilderSession newSession();
 
-    ModelTransformerContextBuilder newTransformerContextBuilder();
+    interface ModelBuilderSession {
+
+        ModelBuilderResult build(ModelBuilderRequest request) throws ModelBuilderException;
+    }
 
     Model buildRawModel(ModelBuilderRequest request);
 }

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

@@ -60,10 +60,17 @@ public ModelBuilderResult getResult() {
      * @return The identifier of the POM or an empty string if not known, never {@code null}.
      */
     public String getModelId() {
-        if (result == null || result.getModelIds().isEmpty()) {
+        if (result == null) {
+            return "";
+        } else if (result.getEffectiveModel() != null) {
+            return result.getEffectiveModel().getId();
+        } else if (result.getRawModel() != null) {
+            return result.getRawModel().getId();
+        } else if (result.getFileModel() != null) {
+            return result.getFileModel().getId();
+        } else {
             return "";
         }
-        return result.getModelIds().get(0);
     }
 
     /**