Restore "first <resource> entry wins" for overlapping declarations

When two <resource> entries cover the same source directory, the file
written by the first entry must not be silently replaced by the second.
3.3.1 produced this behaviour as a side effect of the timestamp-based
overwrite gate in FilteringUtils.copyFile, which MSHARED-1216 (commit
1371dcf, "Use a caching output stream when filtering resources") removed
when it switched to CachingOutputStream / CachingWriter — every write
now goes through unconditionally if the bytes differ, so an unfiltered
second entry clobbers the filtered first entry.

DefaultMavenResourcesFiltering now tracks destination paths already
written within a single filterResources(...) call and skips subsequent
writes that would land on the same path. Explicit opt-in
(MavenResourcesExecution.setOverwrite(true), i.e. ChangeDetection.ALWAYS)
keeps the previous "second entry clobbers" behaviour for callers that
relied on it. The existing flatten-collision policy is left untouched —
a duplicate flattened name still triggers the warn-or-throw path, since
that case is conceptually distinct.

Adds a unit test in DefaultMavenResourcesFilteringTest covering the
explicit-overwrite escape hatch. The OverlappingResourcesFilteringTest
introduced in the previous commit now passes against this code.

Author: rzo1

src/main/java/org/apache/maven/shared/filtering/DefaultMavenResourcesFiltering.java

@@ -32,9 +32,11 @@
 import java.nio.file.Paths;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.HashSet;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Locale;
+import java.util.Set;
 
 import org.apache.maven.model.Resource;
 import org.codehaus.plexus.util.DirectoryScanner;
@@ -144,6 +146,13 @@ public void filterResources(MavenResourcesExecution mavenResourcesExecution) thr
         boolean isFilteringUsed = false;
         List<File> propertiesFiles = new ArrayList<>();
 
+        // Destinations already written by a previous <resource> entry in this call.
+        // Used to preserve "first <resource> entry wins" semantics for overlapping
+        // declarations — the behaviour 3.3.1 produced as a side effect of the
+        // timestamp-based overwrite gate in FilteringUtils.copyFile, lost in
+        // MSHARED-1216 / GH-333.
+        Set<Path> alreadyCopied = new HashSet<>();
+
         for (Resource resource : mavenResourcesExecution.getResources()) {
 
             if (LOGGER.isDebugEnabled()) {
@@ -281,6 +290,20 @@ private File getTargetFile(File file) throws MavenFilteringException {
 
                 File destinationFile = getDestinationFile(outputDirectory, targetPath, name, mavenResourcesExecution);
 
+                // Track destinations already written by a previous <resource> entry so we
+                // can preserve "first <resource> entry wins" semantics for overlapping
+                // declarations. The flatten case has its own collision policy below
+                // (warn-or-throw based on overwrite), so we deliberately do not suppress
+                // it here.
+                Path destinationPath = destinationFile.getAbsoluteFile().toPath();
+                boolean firstOccurrence = alreadyCopied.add(destinationPath);
+                if (!firstOccurrence
+                        && !mavenResourcesExecution.isFlatten()
+                        && mavenResourcesExecution.getChangeDetection() != ChangeDetection.ALWAYS) {
+                    LOGGER.debug("skipping {} — destination already written by a previous <resource> entry", name);
+                    continue;
+                }
+
                 if (mavenResourcesExecution.isFlatten() && destinationFile.exists()) {
                     if (mavenResourcesExecution.getChangeDetection() == ChangeDetection.ALWAYS) {
                         LOGGER.warn("existing file " + destinationFile.getName() + " will be overwritten by " + name);

src/test/java/org/apache/maven/shared/filtering/DefaultMavenResourcesFilteringTest.java

@@ -1112,4 +1112,50 @@ void isPropertiesFile() {
         assertFalse(DefaultMavenResourcesFiltering.isPropertiesFile(new File("file.xml")));
         assertFalse(DefaultMavenResourcesFiltering.isPropertiesFile(new File("some/parent/path", "file.xml")));
     }
+
+    /**
+     * Regression guard for the maven-resources-plugin issue 471 / GH-333 scenario: when the same
+     * destination is reached by a later <resource> entry while overwrite is explicitly enabled,
+     * the later entry must still be allowed to replace the earlier one — the "first entry wins"
+     * skip introduced for the default case must not apply here.
+     */
+    @Test
+    void overlappingEntriesWithExplicitOverwriteStillReplace() throws Exception {
+        Properties projectProperties = new Properties();
+        projectProperties.put("repro.value", "REPLACED_BY_FILTERING");
+        mavenProject.setProperties(projectProperties);
+
+        String unitFilesDir = getBasedir() + "/src/test/units-files/MRP-471";
+
+        Resource filtered = new Resource();
+        filtered.setDirectory(unitFilesDir);
+        filtered.setFiltering(true);
+        filtered.addInclude("config/filtered.xml");
+
+        Resource unfiltered = new Resource();
+        unfiltered.setDirectory(unitFilesDir);
+        unfiltered.setFiltering(false);
+        unfiltered.addInclude("**");
+
+        MavenResourcesExecution execution = new MavenResourcesExecution(
+                Arrays.asList(filtered, unfiltered),
+                outputDirectory,
+                mavenProject,
+                "UTF-8",
+                Collections.emptyList(),
+                Collections.emptyList(),
+                new StubMavenSession());
+        execution.setUseDefaultFilterWrappers(true);
+        execution.setOverwrite(true);
+
+        mavenResourcesFiltering.filterResources(execution);
+
+        File filteredOut = new File(outputDirectory, "config/filtered.xml");
+        String content = new String(java.nio.file.Files.readAllBytes(filteredOut.toPath()), "UTF-8");
+        // With overwrite=true the unfiltered second pass still wins — preserve the historical
+        // 3.3.1 behaviour for callers that opt in to ChangeDetection.ALWAYS.
+        assertTrue(
+                content.contains("${repro.value}"),
+                "with overwrite=true the second <resource> entry must still clobber; got:\n" + content);
+    }
 }

src/test/java/org/apache/maven/shared/filtering/OverlappingResourcesFilteringTest.java

@@ -142,7 +142,7 @@ void overlappingResourceEntriesShouldStillFilter() throws Exception {
         // this guards against a fix that just turns filtering on for everything.
         assertTrue(
                 unfilteredContent.contains("${repro.value}"),
-                "static/keep-as-is.txt is matched by filtering=false and must keep the literal "
-                        + "placeholder; got:\n" + unfilteredContent);
+                "static/keep-as-is.txt is matched by filtering=false and must keep the literal " + "placeholder; got:\n"
+                        + unfilteredContent);
     }
 }