Add support for POM mixins (#1209)

* [MNG-5102] Add support for POM mixins

This commit implements Maven Mixins, a powerful mechanism for sharing
common POM configuration across multiple projects without the limitations
of traditional inheritance.

Key features:
- Compose project configuration from multiple sources
- Overcome single inheritance limitation
- Reduce configuration duplication
- Enable better separation of concerns

Changes include:
- New model version 4.2.0 support for mixins
- Mixin and mixinManagement elements in POM model
- Mixin resolution and composition logic
- Integration with existing inheritance system
- Comprehensive documentation and examples
- Maven 3 compatibility fixes for maven.config

The implementation allows projects to declare mixins that are resolved
and merged in order, with later mixins overriding earlier ones, and
the current POM having final precedence.

Author: gnodet

api/maven-api-model/src/main/mdo/maven.mdo

@@ -111,6 +111,20 @@
           </association>
         </field>
 
+        <!-- ====================================================================== -->
+        <!-- Mixins                                                                 -->
+        <!-- ====================================================================== -->
+
+        <field xdoc.separator="blank">
+          <name>mixins</name>
+          <version>4.2.0+</version>
+          <description>Mixins...</description>
+          <association>
+            <type>Mixin</type>
+            <multiplicity>*</multiplicity>
+          </association>
+        </field>
+
         <!-- ====================================================================== -->
         <!-- groupId/artifactId/Version/Packaging                                   -->
         <!-- ====================================================================== -->
@@ -1836,6 +1850,23 @@
       </codeSegments>
 
     </class>
+    <class>
+        <name>Mixin</name>
+        <version>4.1.0+</version>
+        <superClass>Parent</superClass>
+        <fields>
+            <field>
+                <name>classifier</name>
+                <version>4.1.0+</version>
+                <type>String</type>
+            </field>
+            <field>
+                <name>extension</name>
+                <version>4.1.0+</version>
+                <type>String</type>
+            </field>
+        </fields>
+    </class>
     <class>
       <name>Scm</name>
       <version>4.0.0+</version>

compat/maven-model-builder/src/main/java/org/apache/maven/model/building/FileToRawModelMerger.java

@@ -138,6 +138,12 @@ protected void mergeModel_Profiles(
                 .collect(Collectors.toList()));
     }
 
+    @Override
+    protected void mergeModel_Mixins(
+            Model.Builder builder, Model target, Model source, boolean sourceDominant, Map<Object, Object> context) {
+        // don't merge
+    }
+
     @Override
     protected void mergeModelBase_Dependencies(
             ModelBase.Builder builder,

impl/maven-core/src/main/java/org/apache/maven/internal/transformation/impl/DefaultConsumerPomBuilder.java

@@ -209,6 +209,7 @@ static Model transformNonPom(Model model, MavenProject project) {
                                 .preserveModelVersion(false)
                                 .root(false)
                                 .parent(null)
+                                .mixins(null)
                                 .build(null),
                         model)
                 .mailingLists(null)

impl/maven-impl/src/main/java/org/apache/maven/api/services/model/ModelResolver.java

@@ -85,8 +85,16 @@ record ModelResolverRequest(
             @Nonnull String groupId,
             @Nonnull String artifactId,
             @Nonnull String version,
-            @Nullable String classifier)
+            @Nullable String classifier,
+            @Nullable String extension)
             implements Request<Session> {
+        public ModelResolverRequest {
+            Objects.requireNonNull(session, "session cannot be null");
+            Objects.requireNonNull(groupId, "groupId cannot be null");
+            Objects.requireNonNull(artifactId, "artifactId cannot be null");
+            Objects.requireNonNull(version, "version cannot be null");
+        }
+
         @Nonnull
         @Override
         public Session getSession() {
@@ -106,12 +114,13 @@ public boolean equals(Object o) {
                     && Objects.equals(groupId, that.groupId)
                     && Objects.equals(artifactId, that.artifactId)
                     && Objects.equals(version, that.version)
-                    && Objects.equals(classifier, that.classifier);
+                    && Objects.equals(classifier, that.classifier)
+                    && Objects.equals(extension, that.extension);
         }
 
         @Override
         public int hashCode() {
-            return Objects.hash(repositories, groupId, artifactId, version, classifier);
+            return Objects.hash(repositories, groupId, artifactId, version, classifier, extension);
         }
 
         @Override
@@ -123,6 +132,7 @@ public String toString() {
                     + ", artifactId=" + artifactId
                     + ", version=" + version
                     + ", classifier=" + classifier
+                    + ", extension=" + extension
                     + ']';
         }
     }

impl/maven-impl/src/main/java/org/apache/maven/impl/model/DefaultInheritanceAssembler.java

@@ -194,6 +194,16 @@ private void concatPath(StringBuilder url, String path) {
             }
         }
 
+        @Override
+        protected void mergeModel_Mixins(
+                Model.Builder builder,
+                Model target,
+                Model source,
+                boolean sourceDominant,
+                Map<Object, Object> context) {
+            // do not merge
+        }
+
         @Override
         protected void mergeModelBase_Properties(
                 ModelBase.Builder builder,

impl/maven-impl/src/main/java/org/apache/maven/impl/model/DefaultModelBuilder.java

@@ -66,6 +66,7 @@
 import org.apache.maven.api.model.Exclusion;
 import org.apache.maven.api.model.InputLocation;
 import org.apache.maven.api.model.InputSource;
+import org.apache.maven.api.model.Mixin;
 import org.apache.maven.api.model.Model;
 import org.apache.maven.api.model.Parent;
 import org.apache.maven.api.model.Profile;
@@ -838,12 +839,11 @@ void buildEffectiveModel(Collection<String> importIds) throws ModelBuilderExcept
             }
         }
 
-        Model readParent(Model childModel, DefaultProfileActivationContext profileActivationContext) {
+        Model readParent(Model childModel, Parent parent, DefaultProfileActivationContext profileActivationContext) {
             Model parentModel;
 
-            Parent parent = childModel.getParent();
             if (parent != null) {
-                parentModel = resolveParent(childModel, profileActivationContext);
+                parentModel = resolveParent(childModel, parent, profileActivationContext);
 
                 if (!"pom".equals(parentModel.getPackaging())) {
                     add(
@@ -868,23 +868,26 @@ Model readParent(Model childModel, DefaultProfileActivationContext profileActiva
             return parentModel;
         }
 
-        private Model resolveParent(Model childModel, DefaultProfileActivationContext profileActivationContext)
+        private Model resolveParent(
+                Model childModel, Parent parent, DefaultProfileActivationContext profileActivationContext)
                 throws ModelBuilderException {
             Model parentModel = null;
             if (isBuildRequest()) {
-                parentModel = readParentLocally(childModel, profileActivationContext);
+                parentModel = readParentLocally(childModel, parent, profileActivationContext);
             }
             if (parentModel == null) {
-                parentModel = resolveAndReadParentExternally(childModel, profileActivationContext);
+                parentModel = resolveAndReadParentExternally(childModel, parent, profileActivationContext);
             }
             return parentModel;
         }
 
-        private Model readParentLocally(Model childModel, DefaultProfileActivationContext profileActivationContext)
+        private Model readParentLocally(
+                Model childModel, Parent parent, DefaultProfileActivationContext profileActivationContext)
                 throws ModelBuilderException {
             ModelSource candidateSource;
 
-            Parent parent = childModel.getParent();
+            boolean isParentOrSimpleMixin = !(parent instanceof Mixin)
+                    || (((Mixin) parent).getClassifier() == null && ((Mixin) parent).getExtension() == null);
             String parentPath = parent.getRelativePath();
             if (request.getRequestType() == ModelBuilderRequest.RequestType.BUILD_PROJECT) {
                 if (parentPath != null && !parentPath.isEmpty()) {
@@ -893,14 +896,16 @@ private Model readParentLocally(Model childModel, DefaultProfileActivationContex
                         wrongParentRelativePath(childModel);
                         return null;
                     }
-                } else {
+                } else if (isParentOrSimpleMixin) {
                     candidateSource =
                             resolveReactorModel(parent.getGroupId(), parent.getArtifactId(), parent.getVersion());
                     if (candidateSource == null && parentPath == null) {
                         candidateSource = request.getSource().resolve(modelProcessor::locateExistingPom, "..");
                     }
+                } else {
+                    candidateSource = null;
                 }
-            } else {
+            } else if (isParentOrSimpleMixin) {
                 candidateSource = resolveReactorModel(parent.getGroupId(), parent.getArtifactId(), parent.getVersion());
                 if (candidateSource == null) {
                     if (parentPath == null) {
@@ -910,6 +915,8 @@ private Model readParentLocally(Model childModel, DefaultProfileActivationContex
                         candidateSource = request.getSource().resolve(modelProcessor::locateExistingPom, parentPath);
                     }
                 }
+            } else {
+                candidateSource = null;
             }
 
             if (candidateSource == null) {
@@ -925,11 +932,10 @@ private Model readParentLocally(Model childModel, DefaultProfileActivationContex
             String version = getVersion(candidateModel);
 
             // Ensure that relative path and GA match, if both are provided
-            if (groupId == null
-                    || !groupId.equals(parent.getGroupId())
-                    || artifactId == null
-                    || !artifactId.equals(parent.getArtifactId())) {
-                mismatchRelativePathAndGA(childModel, groupId, artifactId);
+            if (parent.getGroupId() != null && (groupId == null || !groupId.equals(parent.getGroupId()))
+                    || parent.getArtifactId() != null
+                            && (artifactId == null || !artifactId.equals(parent.getArtifactId()))) {
+                mismatchRelativePathAndGA(childModel, parent, groupId, artifactId);
                 return null;
             }
 
@@ -968,8 +974,7 @@ private Model readParentLocally(Model childModel, DefaultProfileActivationContex
             return candidateModel;
         }
 
-        private void mismatchRelativePathAndGA(Model childModel, String groupId, String artifactId) {
-            Parent parent = childModel.getParent();
+        private void mismatchRelativePathAndGA(Model childModel, Parent parent, String groupId, String artifactId) {
             StringBuilder buffer = new StringBuilder(256);
             buffer.append("'parent.relativePath'");
             if (childModel != getRootModel()) {
@@ -1000,16 +1005,17 @@ private void wrongParentRelativePath(Model childModel) {
             add(Severity.FATAL, Version.BASE, buffer.toString(), parent.getLocation(""));
         }
 
-        Model resolveAndReadParentExternally(Model childModel, DefaultProfileActivationContext profileActivationContext)
+        Model resolveAndReadParentExternally(
+                Model childModel, Parent parent, DefaultProfileActivationContext profileActivationContext)
                 throws ModelBuilderException {
             ModelBuilderRequest request = this.request;
             setSource(childModel);
 
-            Parent parent = childModel.getParent();
-
             String groupId = parent.getGroupId();
             String artifactId = parent.getArtifactId();
             String version = parent.getVersion();
+            String classifier = parent instanceof Mixin ? ((Mixin) parent).getClassifier() : null;
+            String extension = parent instanceof Mixin ? ((Mixin) parent).getExtension() : null;
 
             // add repositories specified by the current model so that we can resolve the parent
             if (!childModel.getRepositories().isEmpty()) {
@@ -1027,12 +1033,23 @@ Model resolveAndReadParentExternally(Model childModel, DefaultProfileActivationC
 
             ModelSource modelSource;
             try {
-                modelSource = resolveReactorModel(parent.getGroupId(), parent.getArtifactId(), parent.getVersion());
+                modelSource = classifier == null && extension == null
+                        ? resolveReactorModel(groupId, artifactId, version)
+                        : null;
                 if (modelSource == null) {
-                    AtomicReference<Parent> modified = new AtomicReference<>();
-                    modelSource = modelResolver.resolveModel(request.getSession(), repositories, parent, modified);
-                    if (modified.get() != null) {
-                        parent = modified.get();
+                    ModelResolver.ModelResolverRequest req = new ModelResolver.ModelResolverRequest(
+                            request.getSession(),
+                            null,
+                            repositories,
+                            groupId,
+                            artifactId,
+                            version,
+                            classifier,
+                            extension != null ? extension : "pom");
+                    ModelResolver.ModelResolverResult result = modelResolver.resolveModel(req);
+                    modelSource = result.source();
+                    if (result.version() != null) {
+                        parent = parent.withVersion(result.version());
                     }
                 }
             } catch (ModelResolverException e) {
@@ -1148,7 +1165,8 @@ private Model readEffectiveModel() throws ModelBuilderException {
                 profileActivationContext.setUserProperties(profileProps);
             }
 
-            Model parentModel = readParent(activatedFileModel, profileActivationContext);
+            Model parentModel =
+                    readParent(activatedFileModel, activatedFileModel.getParent(), profileActivationContext);
 
             // Now that we have read the parent, we can set the relative
             // path correctly if it was not set in the input model
@@ -1170,6 +1188,15 @@ private Model readEffectiveModel() throws ModelBuilderException {
 
             Model model = inheritanceAssembler.assembleModelInheritance(inputModel, parentModel, request, this);
 
+            // Mixins
+            for (Mixin mixin : model.getMixins()) {
+                Model parent = resolveParent(model, mixin, profileActivationContext);
+                model = inheritanceAssembler.assembleModelInheritance(model, parent, request, this);
+            }
+
+            // model normalization
+            model = modelNormalizer.mergeDuplicates(model, request, this);
+
             // profile activation
             profileActivationContext.setModel(model);
 
@@ -1354,7 +1381,7 @@ Model doReadFileModel() throws ModelBuilderException {
                                         .version(parentVersion)
                                         .build());
                             } else {
-                                mismatchRelativePathAndGA(model, parentGroupId, parentArtifactId);
+                                mismatchRelativePathAndGA(model, parent, parentGroupId, parentArtifactId);
                             }
                         } else {
                             if (!MODEL_VERSION_4_0_0.equals(model.getModelVersion()) && path != null) {
@@ -1575,8 +1602,9 @@ Model readAsParentModel(DefaultProfileActivationContext profileActivationContext
         private ParentModelWithProfiles doReadAsParentModel(
                 DefaultProfileActivationContext childProfileActivationContext) throws ModelBuilderException {
             Model raw = readRawModel();
-            Model parentData = readParent(raw, childProfileActivationContext);
-            Model parent = new DefaultInheritanceAssembler(new DefaultInheritanceAssembler.InheritanceModelMerger() {
+            Model parentData = readParent(raw, raw.getParent(), childProfileActivationContext);
+            DefaultInheritanceAssembler defaultInheritanceAssembler =
+                    new DefaultInheritanceAssembler(new DefaultInheritanceAssembler.InheritanceModelMerger() {
                         @Override
                         protected void mergeModel_Modules(
                                 Model.Builder builder,
@@ -1592,8 +1620,12 @@ protected void mergeModel_Subprojects(
                                 Model source,
                                 boolean sourceDominant,
                                 Map<Object, Object> context) {}
-                    })
-                    .assembleModelInheritance(raw, parentData, request, this);
+                    });
+            Model parent = defaultInheritanceAssembler.assembleModelInheritance(raw, parentData, request, this);
+            for (Mixin mixin : parent.getMixins()) {
+                Model parentModel = resolveParent(parent, mixin, childProfileActivationContext);
+                parent = defaultInheritanceAssembler.assembleModelInheritance(parent, parentModel, request, this);
+            }
 
             // Profile injection SHOULD be performed on parent models to ensure
             // that profile content becomes part of the parent model before inheritance.

impl/maven-impl/src/main/java/org/apache/maven/impl/model/DefaultModelValidator.java

@@ -355,6 +355,43 @@ && equals(parent.getArtifactId(), model.getArtifactId())) {
             }
         }
 
+        // Validate mixins
+        if (!model.getMixins().isEmpty()) {
+            // Ensure model version is at least 4.2.0 when using mixins
+            if (compareModelVersions("4.2.0", model.getModelVersion()) < 0) {
+                addViolation(
+                        problems,
+                        Severity.ERROR,
+                        Version.V40,
+                        "mixins",
+                        null,
+                        "Mixins are only supported in modelVersion 4.2.0 or higher, but found '"
+                                + model.getModelVersion() + "'.",
+                        model);
+            }
+
+            // Validate each mixin
+            for (Parent mixin : model.getMixins()) {
+                if (mixin.getRelativePath() != null
+                        && !mixin.getRelativePath().isEmpty()
+                        && (mixin.getGroupId() != null && !mixin.getGroupId().isEmpty()
+                                || mixin.getArtifactId() != null
+                                        && !mixin.getArtifactId().isEmpty())
+                        && validationLevel >= ModelValidator.VALIDATION_LEVEL_MAVEN_4_0
+                        && ModelBuilder.KNOWN_MODEL_VERSIONS.contains(model.getModelVersion())
+                        && !Objects.equals(model.getModelVersion(), ModelBuilder.MODEL_VERSION_4_0_0)) {
+                    addViolation(
+                            problems,
+                            Severity.WARNING,
+                            Version.BASE,
+                            "mixins.mixin.relativePath",
+                            null,
+                            "only specify relativePath or groupId/artifactId for mixin",
+                            mixin);
+                }
+            }
+        }
+
         if (validationLevel == ModelValidator.VALIDATION_LEVEL_MINIMAL) {
             // profiles: they are essential for proper model building (may contribute profiles, dependencies...)
             HashSet<String> minProfileIds = new HashSet<>();