[Maven 4] Maven resources plugin - relative targetPath is not the same as in Maven 3.9.x

[philippe-granet]

Affected version

Apache Maven 4.0.0-SNAPSHOT (b7f9178)

Bug description

With Maven 3.9.x and this configuration:

    <build>
        <resources>
            <resource>
                <directory>${project.basedir}/rest</directory>
                <targetPath>target-dir</targetPath>
                <includes>
                    <include>**/*.yml</include>
                </includes>
            </resource>
        </resources>
    </build>

all files rest/**/*.yml are copied to target/classes/target-dir:

[INFO] --- resources:3.3.1:resources (default-resources) @ project1 ---
[INFO] Copying 36 resources from rest to target/classes/target-dir

But with Maven 4, with same version of Maven resources plugin, all files rest/**/*.yml are copied to root dir target-dir:

[INFO] --- resources:3.3.1:resources (default-resources) @ project1---
[INFO] Copying 36 resources from rest to target-dir
[INFO] ---------------------------------------------

It seams that relative targetPath is not the same as in Maven 3.9.x

A workaround is to prefix targetPath with ${project.build.outputDirectory}/, it works both on Maven 3 and 4:

    <build>
        <resources>
            <resource>
                <directory>${project.basedir}/rest</directory>
                <targetPath>${project.build.outputDirectory}/target-dir</targetPath>
                <includes>
                    <include>**/*.yml</include>
                </includes>
            </resource>
        </resources>
    </build>

[gnodet]

Javadoc Improvements

I've also enhanced the javadoc for SourceRoot to make the intended behavior more explicit and prevent future regressions.

Enhanced targetPath() javadoc:

/**
 * {@return an explicit target path, overriding the default value}
 * <p>
 * The returned path is typically <strong>relative to the output directory</strong>
 * (e.g., {@code "custom-dir"} or {@code "META-INF/resources"}), but may be absolute
 * if explicitly specified as such in the project configuration.
 * </p>
 * ...
 * <p>
 * To obtain the fully resolved absolute path, use {@link #targetPath(Project)} instead.
 * </p>
 */

Key clarifications:

• Explicitly states the path is "typically relative to the output directory"
• Provides concrete examples: "custom-dir" or "META-INF/resources"
• Notes that absolute paths are possible but must be explicitly specified
• Cross-references targetPath(Project) for obtaining the resolved absolute path

Enhanced targetPath(Project) javadoc:

/**
 * {@return the fully resolved absolute target path}
 * <p>
 * This method returns the absolute path where files from {@link #directory()} should be copied.
 * ...
 * </p>
 * <p>
 * If {@link #targetPath()} returns:
 * </p>
 * <ul>
 *   <li>An empty {@code Optional}: returns the default output directory
 *       (e.g., {@code /path/to/project/target/classes})</li>
 *   <li>A relative path (e.g., {@code "custom-dir"}): returns the path resolved against
 *       the output directory (e.g., {@code /path/to/project/target/classes/custom-dir})</li>
 *   <li>An absolute path: returns that absolute path unchanged</li>
 * </ul>
 */

Key clarifications:

• Clearly states this returns "the fully resolved absolute target path"
• Provides a bulleted list with concrete examples for all three cases
• Shows the relationship between targetPath() and targetPath(Project)

These improvements make the API contract crystal clear and should help prevent similar issues in the future.

[gnodet]

Implementation Explanation: Resource targetPath Fix

This fix addresses the regression in Maven 4 where resource targetPath was being resolved relative to the project base directory instead of the output directory, breaking compatibility with Maven 3.x behavior.

Problem Analysis

In Maven 3.x, when a resource has a relative targetPath, it's resolved relative to the output directory (target/classes or target/test-classes). However, in Maven 4, the DefaultSourceRoot constructor that takes a Resource parameter was incorrectly resolving the targetPath as:

nonBlank(resource.getTargetPath()).map(baseDir::resolve).orElse(null)

This resolved the targetPath relative to the base directory, not the output directory.

Solution Design

The fix was implemented with careful consideration for both Maven 4 API conformance and Maven 3 compatibility:

1. API-First Approach

The solution leverages Maven 4's new SourceRoot API which represents a more structured approach to handling source and resource directories. The SourceRoot.targetPath() method returns an Optional<Path> that should contain a path relative to the output directory.

2. Backward Compatibility Strategy

To maintain compatibility with existing Maven 3 code that uses the Resource API:

• Preserved existing constructor: The original DefaultSourceRoot(Path baseDir, ProjectScope scope, Resource resource) constructor was kept unchanged to avoid breaking existing code
• Correct targetPath handling: The constructor now properly stores the targetPath as a relative path (using Path.of()) instead of resolving it against the base directory
• ConnectedResource wrapper: This class bridges between the Maven 4 SourceRoot API and the Maven 3 Resource API, ensuring that when Maven 3 code calls Resource.getTargetPath(), it receives the correct relative path

3. Implementation Details

DefaultSourceRoot Constructor (lines 157-171):

public DefaultSourceRoot(final Path baseDir, ProjectScope scope, Resource resource) {
    this(
            scope,
            Language.RESOURCES,
            null,
            null,
            baseDir.resolve(nonBlank(resource.getDirectory())
                    .orElseThrow(() -> new IllegalArgumentException("Source declaration without directory value."))),
            resource.getIncludes(),
            resource.getExcludes(),
            Boolean.parseBoolean(resource.getFiltering()),
            nonBlank(resource.getTargetPath()).map(Path::of).orElse(null), // Key fix: Path.of() instead of baseDir.resolve()
            true);
}

ConnectedResource Bridge (lines 52-60):

private static String computeRelativeTargetPath(SourceRoot sourceRoot, ProjectScope scope, MavenProject project) {
    return sourceRoot.targetPath().map(Path::toString).orElse(null);
}

Maven 4 API Conformance

1. Consistent Path Semantics

The fix ensures that SourceRoot.targetPath() always returns a relative path, which is the expected behavior in Maven 4's API design. This provides a clear contract: targetPath is always relative to the output directory.

2. Type Safety

By using Path.of() instead of string manipulation, the implementation leverages Java's type-safe path handling, reducing the risk of path-related bugs.

3. Optional Usage

The implementation properly uses Optional<Path> for targetPath, following Maven 4's API patterns for nullable values.

Compatibility Preservation

1. Maven 3 Resource API

Existing Maven 3 code that uses Resource.getTargetPath() continues to work unchanged. The ConnectedResource class ensures that the returned string represents a path relative to the output directory, maintaining the expected Maven 3 behavior.

2. Plugin Compatibility

Maven plugins that rely on the Resource API (like the maven-resources-plugin) continue to work without modification, as they receive the correct relative paths through the ConnectedResource wrapper.

3. Build Tool Integration

IDEs and other build tools that inspect Maven project models will see consistent behavior between Maven 3 and Maven 4.

Testing Strategy

The fix includes comprehensive testing at multiple levels:

1. Unit Tests (DefaultSourceRootTest.java)

• Tests for Resource constructor with various targetPath scenarios
• Verification that relative paths are preserved correctly
• Edge case handling (null, empty targetPath)

2. Integration Test (MavenITgh11381ResourceTargetPathTest.java)

• End-to-end verification that resources are copied to the correct location
• Validates that target/classes/target-dir/ is used instead of target-dir/
• Ensures the fix works in real Maven builds

Why This Approach?

This implementation was chosen because it:

1. Minimizes Breaking Changes: Existing code continues to work without modification
2. Follows Maven 4 Patterns: Uses the new SourceRoot API as the primary abstraction
3. Maintains Clear Separation: The SourceRoot API handles the "truth" while ConnectedResource provides compatibility
4. Enables Future Evolution: The SourceRoot API can be extended without affecting the Resource compatibility layer
5. Provides Type Safety: Uses Path objects internally while maintaining string compatibility externally

This solution successfully bridges the gap between Maven 3's Resource-centric approach and Maven 4's SourceRoot-centric design, ensuring that both APIs work correctly while maintaining the expected behavior for resource targetPath resolution.

[gnodet]

Implementation Approach: Maven 4 API Conformance with Maven 3 Compatibility

I've enhanced the javadoc to clarify how targetPath handling works in the Maven 4 API while preserving full backward compatibility with Maven 3. Here's the design rationale:

Core Design Principle

The implementation follows a separation of concerns pattern:

1. Storage Layer (SourceRoot.targetPath()): Stores the path as-is from the configuration (relative or absolute)
2. Resolution Layer (SourceRoot.targetPath(Project)): Resolves relative paths against the output directory to produce absolute paths

Maven 4 API Conformance

SourceRoot.targetPath() - The Storage Method

This method returns the targetPath exactly as specified in the configuration:

• Relative paths (e.g., "META-INF/resources") are stored as relative paths
• Absolute paths (e.g., "/tmp/custom") are stored as absolute paths
• Empty/null means no explicit target path was specified

The javadoc now explicitly documents:

/**
 * <strong>Path Resolution Semantics:</strong>
 * <ul>
 *   <li><strong>Relative paths</strong> are resolved relative to the output directory
 *       for the given scope (target/classes for MAIN, target/test-classes for TEST)</li>
 *   <li><strong>Absolute paths</strong> are used as-is without any resolution</li>
 *   <li><strong>Empty/null</strong> means files are copied to the output directory root</li>
 * </ul>
 */

SourceRoot.targetPath(Project) - The Resolution Method

This method performs the actual path resolution:

default Path targetPath(@Nonnull Project project) {
    Optional<Path> targetPath = targetPath();
    return targetPath.filter(Path::isAbsolute).orElseGet(() -> {
        Path base = project.getOutputDirectory(scope());
        return targetPath.map(base::resolve).orElse(base);
    });
}

Resolution Algorithm:

1. Get the output directory for the source root's scope from the project
2. If targetPath() is empty → return the output directory
3. If targetPath() is absolute → return it unchanged
4. If targetPath() is relative → resolve it against the output directory

Project.getOutputDirectory(ProjectScope) - The Base Directory Provider

This method returns the scope-specific output directory:

• ProjectScope.MAIN → target/classes (for compiled classes AND resources)
• ProjectScope.TEST → target/test-classes (for test classes AND resources)
• Other/null → target (the build directory)

The javadoc now explicitly states its role in path resolution and Maven 3 compatibility.

Maven 3 Backward Compatibility

How It Preserves Maven 3 Behavior

In Maven 3, the maven-resources-plugin receives the targetPath as a relative path and resolves it against project.build.outputDirectory or project.build.testOutputDirectory.

Our implementation maintains this by:

1. DefaultSourceRoot stores targetPath as-is (relative):

   nonBlank(resource.getTargetPath()).map(Path::of).orElse(null)

2. ConnectedResource extracts targetPath as a string (still relative):

   sourceRoot.targetPath().map(Path::toString).orElse(null)

3. maven-resources-plugin receives the relative path and resolves it against the output directory (exactly as in Maven 3)

Why This Works

The key insight is that we don't resolve the path at storage time. Instead:

• The targetPath is stored as a relative path (e.g., "target-dir")
• When maven-resources-plugin reads it via resource.getTargetPath(), it gets "target-dir" (a relative path string)
• The plugin then resolves it: outputDirectory.resolve("target-dir") → target/classes/target-dir

This is identical to Maven 3 behavior!

Implementation Details

DefaultSourceRoot Constructor from Resource

public DefaultSourceRoot(final Path baseDir, ProjectScope scope, Resource resource) {
    this(
        scope,
        Language.RESOURCES,
        null,
        null,
        baseDir.resolve(resource.getDirectory()),  // ← directory IS resolved against baseDir
        resource.getIncludes(),
        resource.getExcludes(),
        Boolean.parseBoolean(resource.getFiltering()),
        nonBlank(resource.getTargetPath()).map(Path::of).orElse(null),  // ← targetPath is NOT resolved
        true);
}

Important distinction:

• directory is resolved against baseDir because it's a source location (needs to be absolute for file system access)
• targetPath is NOT resolved because it's a destination specification (resolution happens later based on scope)

The javadoc now explicitly documents this:

/**
 * @param baseDir the base directory for resolving relative paths (used only for the source directory)
 */

ConnectedResource Wrapper

This class bridges the Maven 4 API (SourceRoot) with the Maven 3 API (Resource):

ConnectedResource(SourceRoot sourceRoot, ProjectScope scope, MavenProject project) {
    super(org.apache.maven.api.model.Resource.newBuilder()
            .directory(sourceRoot.directory().toString())
            .targetPath(sourceRoot.targetPath().map(Path::toString).orElse(null))  // ← relative path
            .build());
}

The targetPath is extracted as a string representation of the relative path, which is exactly what maven-resources-plugin expects.

Examples

Given this configuration:

<resource>
  <directory>${project.basedir}/rest</directory>
  <targetPath>target-dir</targetPath>
</resource>

Storage:

• sourceRoot.directory() → /home/user/myproject/rest (absolute)
• sourceRoot.targetPath() → Optional.of(Path.of("target-dir")) (relative)

Resolution (Maven 4 API):

• sourceRoot.targetPath(project) → /home/user/myproject/target/classes/target-dir (absolute)

Legacy API (Maven 3 compatibility):

• resource.getDirectory() → /home/user/myproject/rest (absolute path as string)
• resource.getTargetPath() → "target-dir" (relative path as string)
• maven-resources-plugin resolves: target/classes + target-dir → target/classes/target-dir ✅

Summary

This implementation:

✅ Conforms to Maven 4 API - Clear separation between storage (targetPath()) and resolution (targetPath(Project))

✅ Preserves Maven 3 compatibility - Relative paths are stored as-is and resolved by plugins against output directory

✅ Well-documented - Comprehensive javadoc explains semantics, resolution algorithm, and compatibility guarantees

✅ Consistent - All three methods (SourceRoot.targetPath(), SourceRoot.targetPath(Project), Project.getOutputDirectory()) have coherent documentation with cross-references

The key to maintaining compatibility was recognizing that Maven 3's behavior of resolving targetPath relative to the output directory should be preserved by not resolving it at storage time, but instead letting the resolution happen either:

1. Via SourceRoot.targetPath(Project) in Maven 4 API consumers
2. Via maven-resources-plugin's own resolution logic in Maven 3 compatibility mode