Fix #375: Capture plugin properties at validation time to eliminate timing mismatch

[cowwoc]

Problem

Maven 4 automatically injects --module-version ${project.version} into compiler arguments during execution, but the build cache validates properties before execution. This creates a timing mismatch that causes cache invalidation:

• First build: No cache exists → properties captured during/after execution (WITH Maven 4 injection)
• Second build: Cache exists → properties captured during validation (WITHOUT injection yet) → mismatch → cache invalidated

Root Cause Analysis

The cache extension currently reads plugin properties at different lifecycle points for different builds:

First Build Timeline:
  1. findCachedBuild() → no cache found
  2. Mojos execute → Maven 4 injects --module-version
  3. beforeMojoExecution() fires → captures properties WITH injection
  4. save() stores properties from execution events

Second Build Timeline:
  1. findCachedBuild() → cache found
  2. verifyCacheConsistency() → creates mojo via getConfiguredMojo()
  3. Reads properties → WITHOUT injection (too early in lifecycle)
  4. Compares to first build's stored values (WITH injection)
  5. MISMATCH → cache invalidated!

The problem: validation reads BEFORE injection, storage reads AFTER injection.

Solution

Capture properties at validation time for ALL builds (even when no cache exists). Store ONLY validation-time values in the cache. This ensures both validation and storage read at the same lifecycle point.

Implementation

1. Modified CacheResult to store validation-time mojo events
2. Modified BuildCacheMojosExecutionStrategy to capture properties immediately after findCachedBuild()
3. Modified save() to store ONLY validation-time events (fails with AssertionError if missing)

Key Code Changes

// In BuildCacheMojosExecutionStrategy.execute():
result = cacheController.findCachedBuild(session, project, mojoExecutions, skipCache);

// NEW: Always capture validation-time properties when cache is enabled
if (cacheState == INITIALIZED) {
    Map<String, MojoExecutionEvent> validationTimeEvents =
        captureValidationTimeProperties(session, project, mojoExecutions);
    result = CacheResult.rebuilded(result, validationTimeEvents);
}

// In save():
// Validation-time events MUST exist - no fallback to execution-time
if (result.getValidationTimeEvents() == null || result.getValidationTimeEvents().isEmpty()) {
    throw new AssertionError("Validation-time properties not captured - this is a bug");
}
cacheController.save(result, mojoExecutions, result.getValidationTimeEvents());

Note: Execution-time values are still captured by MojoParametersListener for logging/debugging during the build, but are NOT stored in the cache.

New Timeline (Both Builds)

First Build:
  1. findCachedBuild() → no cache
  2. captureValidationTimeProperties() → reads WITHOUT injection
  3. Mojos execute → Maven 4 injects (logged but not stored)
  4. save() stores ONLY validation-time properties → WITHOUT injection

Second Build:
  1. findCachedBuild() → cache found
  2. verifyCacheConsistency() → reads WITHOUT injection
  3. captureValidationTimeProperties() → reads WITHOUT injection
  4. Compares to first build → BOTH without injection → MATCH!

What Gets Stored vs. Logged

Data	Stored in Cache	Available in Logs
Validation-time properties (no injection)	✅ Yes	✅ Yes
Execution-time properties (with injection)	❌ No	✅ Yes

This approach ensures cache consistency while preserving debugging information in build logs.

Benefits Over PR #391

Aspect	PR #391 (ignorePattern)	This PR (Validation-Time Capture)
Approach	Workaround: Filter mismatched values	Fix: Eliminate timing mismatch
Configuration	Required	None needed
Flexibility	Pattern must match version format	Format-agnostic
Maintenance	Patterns need updates	No maintenance
Scope	Only fixes known patterns	Fixes ALL auto-injected properties

Testing

Created comprehensive integration tests:

1. Maven4JpmsModuleTest - JPMS module with Maven 4 auto-injection of --module-version
2. ExplicitModuleVersionTest - JPMS module with explicit moduleVersion configuration
3. NonJpmsProjectTest - Regular Java project without JPMS (ensures no regression)
4. MultiModuleJpmsTest - Multi-module project with mixed JPMS and non-JPMS modules

All tests verify:

• ✅ First build creates cache
• ✅ Second build restores from cache (NO cache invalidation)
• ✅ NO ignorePattern configuration required

Backward Compatibility

• Fully backward compatible
• Existing caches remain valid
• No configuration changes required
• ignorePattern still works but is no longer necessary for Maven 4 injection

Alternative Approaches Considered

1. Delay validation until execution ❌ - Would lose early cache-miss detection performance benefit
2. Pattern-based filtering (PR Add ignorePattern attribute to TrackedProperty for array filtering #391) ❌ - Treats symptom (value mismatch) instead of root cause (timing mismatch)
3. Maven core changes ❌ - Outside our control, would take years to deploy
4. Store both validation-time and execution-time ❌ - Unnecessary complexity, doesn't solve the consistency problem
5. Validation-time capture + storage (this PR) ✅ - Fixes root cause, no configuration needed, preserves logging for debugging

Related Issues

• Fixes Maven Build Cache Extension incorrectly handles --module-version compiler arguments for Java modules, causing cache invalidation on every build despite no source code changes #375
• Alternative to Add ignorePattern attribute to TrackedProperty for array filtering #391
• Related to Maven 4 JPMS module compilation

Migration

No migration needed. This change is transparent to users. Existing projects will benefit automatically.

[elharo]

need to run mvn spotless:apply

[cowwoc]

@elharo Done. Try now.

[cowwoc]

@elharo I've pushed a commit that should fix the latest build failures. Try now.

[cowwoc]

It looks like the latest build errors are not related to this PR. Can it be merged? Do you need to do something else to fix the build?

[elharo]

Absolutely nothing should be merged on a failing build. A failing build blocks everything.

[Copilot]

Pull request overview

This PR addresses #375 by eliminating a lifecycle timing mismatch in Maven 4 where --module-version ${project.version} is injected during execution, but cache validation reads plugin parameters earlier. The proposed approach captures and stores plugin properties consistently at validation time so that subsequent cache validations compare like-for-like values.

Changes:

• Extend CacheResult to carry validation-time MojoExecutionEvents.
• Capture validation-time configured mojo instances in BuildCacheMojosExecutionStrategy and use them for cache storage.
• Add new integration-test projects and ITS coverage for Maven 4 JPMS, explicit module version, non-JPMS, and multi-module mixed JPMS/non-JPMS scenarios.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/main/java/org/apache/maven/buildcache/BuildCacheMojosExecutionStrategy.java	Captures validation-time mojo configuration and uses it during cache save to avoid Maven 4 execution-time injection mismatches.
src/main/java/org/apache/maven/buildcache/CacheResult.java	Adds storage for validation-time events so save can use consistent lifecycle-point data.
src/test/java/org/apache/maven/buildcache/its/Maven4JpmsModuleTest.java	ITS coverage for Maven 4 JPMS module auto-injection scenario (regression for #375).
src/test/java/org/apache/maven/buildcache/its/ExplicitModuleVersionTest.java	ITS coverage for explicit --module-version configuration present at validation time.
src/test/java/org/apache/maven/buildcache/its/NonJpmsProjectTest.java	ITS coverage ensuring no regression for regular (non-JPMS) Java projects.
src/test/java/org/apache/maven/buildcache/its/MultiModuleJpmsTest.java	ITS coverage for mixed JPMS/non-JPMS multi-module reactor builds.
src/test/projects/maven4-jpms-module/pom.xml	Maven 4 JPMS sample project used by ITS.
src/test/projects/maven4-jpms-module/src/main/java/org/apache/maven/caching/test/maven4/HelloMaven4.java	Sample source for Maven 4 JPMS project.
src/test/projects/maven4-jpms-module/src/main/java/module-info.java	JPMS descriptor to trigger module compilation behavior.
src/test/projects/maven4-jpms-module/.mvn/extensions.xml	Enables build cache extension for the Maven 4 JPMS test project.
src/test/projects/maven4-jpms-module/.mvn/maven-build-cache-config.xml	Enables cache in the Maven 4 JPMS test project.
src/test/projects/explicit-module-version/pom.xml	Sample project explicitly configuring --module-version.
src/test/projects/explicit-module-version/src/main/java/org/apache/maven/caching/test/explicit/ExplicitVersionModule.java	Sample source for explicit-module-version project.
src/test/projects/explicit-module-version/src/main/java/module-info.java	JPMS descriptor for explicit-module-version project.
src/test/projects/explicit-module-version/.mvn/extensions.xml	Enables build cache extension for explicit-module-version project.
src/test/projects/explicit-module-version/.mvn/maven-build-cache-config.xml	Enables cache in explicit-module-version project.
src/test/projects/non-jpms-project/pom.xml	Regular Java (non-JPMS) sample project for regression coverage.
src/test/projects/non-jpms-project/src/main/java/org/apache/maven/caching/test/nonjpms/RegularJavaClass.java	Sample source for non-JPMS regression project.
src/test/projects/non-jpms-project/.mvn/extensions.xml	Enables build cache extension for non-JPMS regression project.
src/test/projects/non-jpms-project/.mvn/maven-build-cache-config.xml	Enables cache in non-JPMS regression project.
src/test/projects/multi-module-jpms/pom.xml	Parent POM for mixed JPMS/non-JPMS multi-module test project.
src/test/projects/multi-module-jpms/module-a/pom.xml	JPMS module POM in mixed multi-module test.
src/test/projects/multi-module-jpms/module-a/src/main/java/org/apache/maven/caching/test/multi/modulea/ModuleA.java	Sample JPMS module source.
src/test/projects/multi-module-jpms/module-a/src/main/java/module-info.java	JPMS descriptor for module-a.
src/test/projects/multi-module-jpms/module-b/pom.xml	Non-JPMS module POM in mixed multi-module test.
src/test/projects/multi-module-jpms/module-b/src/main/java/org/apache/maven/caching/test/multi/moduleb/ModuleB.java	Sample non-JPMS module source.
src/test/projects/multi-module-jpms/.mvn/extensions.xml	Enables build cache extension for multi-module test project.
src/test/projects/multi-module-jpms/.mvn/maven-build-cache-config.xml	Enables cache in multi-module test project.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cowwoc]

@cstamas Comment addressed. Please re-run the check.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 4 comments.

[cowwoc]

@cstamas Round 2 complete :) Please re-check.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 2 comments.

[cowwoc]

@cstamas Please trigger another review.

[cowwoc]

@cstamas The failure seems to be a transient network issue. Can you please trigger another build?

[cstamas]

Please rebase against latest master.

[cowwoc]

@cstamas Done. Try now.