feat: introduce ChangeDetection strategy for file copy

[gnodet]

Summary

Port of the ChangeDetection strategy from the maven-filtering-3.x branch (commit d9bc10a) to the master branch (Maven 4 / Path-based API).

Instead of jumping between ways to perform change detection — deciding whether an existing target file needs to be overwritten — make it a configurable strategy. Before 3.4.0 it was timestamp-based, post 3.4.0 it switched to content-based via CachingOutputStream, but in any case users were left with no control.

Changes

New ChangeDetection enum

Five strategies:

Strategy	Behaviour
TIMESTAMP	Overwrite only when source is newer (pre-3.4.0 default)
CONTENT	Overwrite only when content differs — via CachingOutputStream/CachingWriter (current default)
TIMESTAMP_AND_CONTENT	Check timestamp first, then content if needed
ALWAYS	Always overwrite (replaces overwrite=true)
NEVER	Never overwrite an existing file

API changes

• AbstractMavenFilteringRequest — new changeDetection field (default CONTENT) with getter/setter
• FilteringUtils — new copyFile(Path, Path, String, FilterWrapper[], ChangeDetection) overload returning boolean (true=written, false=skipped); old boolean overwrite signature deprecated
• MavenFileFilter — new copyFile(…, ChangeDetection) and copyFileWithResult(…, ChangeDetection) methods; old signature deprecated
• DefaultMavenFileFilter — implements new interface methods, returns boolean indicating whether the destination was written
• DefaultMavenResourcesFiltering — uses getChangeDetection() from the request instead of isOverwrite(); per-resource override takes precedence over request-level setting; emits "Copying file X" or "Skipping file X (up to date)" based on the actual copy outcome
• MavenResourcesExecution — isOverwrite() / setOverwrite() deprecated, now delegate through ChangeDetection
• Resource — new changeDetection field so individual <resource> elements can declare their own strategy, overriding the request-level default

Implementation details

• CONTENT / TIMESTAMP_AND_CONTENT use CachingOutputStream / CachingWriter (existing behaviour)
• ALWAYS / TIMESTAMP / NEVER bypass caching and write unconditionally via Files.newOutputStream / Files.newBufferedWriter
• TIMESTAMP uses Files.getLastModifiedTime(path).toMillis() for Path-based comparison
• Per-resource changeDetection wins when set; falls back to the request-level value otherwise
• buildContext.refresh() is always called for processed outputs so incremental build contexts (m2e / Eclipse) correctly track them regardless of whether the file was skipped

Fixes

• Destination file overwritten even with overwrite false in 3.4.0 maven-resources-plugin#453
• [MRESOURCES-274] set overwrite per resource maven-resources-plugin#286 (per-resource changeDetection on Resource)
• [MRESOURCES-313] Debug says 'copy' but does not do that when overwrite = false maven-resources-plugin#316 — debug log said "Copying file" even when the file was skipped by change-detection (fixed: log is now emitted after the copy, showing "Copying" or "Skipping (up to date)" based on the actual outcome)

Related

Plugin-side companion PR: apache/maven-resources-plugin#527

Origin

Ported from maven-filtering-3.x commit d9bc10a by Tamas Cservenak.

[gnodet-bot]

Well-structured refactor — the ChangeDetection enum is a clean replacement for the boolean overwrite flag, and the split into copyUnconditionally / copyIfContentsChanged makes the intent clear. The gracefulBinaryHandling migration from DefaultMavenFileFilter to DefaultMavenResourcesFiltering is correct (no double-handling). A few items below.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

[gnodet-bot]

Re-review after 4fcc417 — both previous findings are addressed:

1. FilteringUtils.java @param overwrite — Javadoc now accurately documents the mapping (true → ALWAYS, false → CONTENT). ✅
2. MavenResourcesExecution.java dead overwrite field — removed entirely; isOverwrite()/setOverwrite() now delegate through ChangeDetection. ✅

Full re-review of the current diff found no new issues. The switch-based dispatch in FilteringUtils.copyFile handles all five strategies correctly with a defensive default branch. The gracefulBinaryHandling migration from DefaultMavenFileFilter to DefaultMavenResourcesFiltering is clean — the caller catches MavenFilteringException wrapping MalformedInputException and falls back to unfiltered copy with the same ChangeDetection mode. API backward compat is preserved via deprecated method delegation.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

[gnodet-bot]

Re-review after 9a3e681 (per-resource changeDetection override).

Previous findings (from first review): both addressed in 4fcc417 ✅

1. FilteringUtils.java — inaccurate @param overwrite Javadoc → fixed, now documents the true→ALWAYS / false→CONTENT mapping.
2. MavenResourcesExecution.java — dead overwrite field → removed entirely, getters/setters delegate through ChangeDetection.

New commit 9a3e681: Clean. The per-resource changeDetection override in Resource.java is nullable (null = inherit from request-level), and DefaultMavenResourcesFiltering resolves it correctly across all three call sites (flatten check, primary copy, binary-fallback copy). Field visibility is package-private, consistent with other Resource fields. Javadoc is accurate with @since 4.0.0-beta-2.

No new issues found.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

[gnodet-bot]

Re-review after a25457e (accurate copy/skip debug logging).

Previous findings (from first two reviews): all addressed ✅

1. FilteringUtils.java — inaccurate @param overwrite Javadoc → fixed in 4fcc417.
2. MavenResourcesExecution.java — dead overwrite field → removed in 4fcc417.

New commit a25457e: adds copyFileWithResult() to MavenFileFilter (returns boolean), refactors DefaultMavenFileFilter.doCopyFile() to propagate the result, and updates DefaultMavenResourcesFiltering to log "Copying file X" vs "Skipping file X (up to date)" based on the actual copy outcome — fixing the pre-existing issue where the debug log always said "Copying" even when the file was skipped by change detection.

The gracefulBinaryHandling catch is correctly moved up to DefaultMavenResourcesFiltering for the copyFileWithResult path (retries with filtering=false), while the old doCopyFile path still handles it for backward-compatible callers via copyFile(MavenFileFilterRequest). No double-handling.

No new issues found.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

[gnodet-bot]

Re-review after rebase/squash (dec4590). Tree SHA is identical to previously approved a25457e — code unchanged, all prior findings remain addressed. Clean rebase onto updated master.

This review was generated by an AI agent, Hermès on behalf of @gnodet.