Package org.apache.maven.api

Interface SourceRoot

All Known Implementing Classes:
DefaultSourceRoot
public interface SourceRoot
A root directory of source files. The sources may be Java main classes, test classes, resources or anything else identified by the scope.

Default values

The properties in this interface are defined in the <Source> element of the Maven project descriptor. For each property, the default value is either empty or documented in the project descriptor.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Path
    directory()
    Returns the root directory where the sources are stored.
    default boolean
    enabled()
    Returns whether the directory described by this source element should be included in the build.
    default List<String>
    excludes()
    Returns the list of patterns for the files to exclude.
    default List<String>
    includes()
    Returns the list of patterns for the files to include.
    default Language
    language()
    Returns the language of the source files.
    PathMatcher
    matcher(Collection<String> defaultIncludes, boolean useDefaultExcludes)
    Returns a matcher combining the include and exclude patterns.
    default Optional<String>
    module()
    Returns the name of the Java module (or other language-specific module) which is built by the sources.
    default ProjectScope
    scope()
    Returns in which context the source files will be used.
    default boolean
    stringFiltering()
    Returns whether resources are filtered to replace tokens with parameterized values.
    default Optional<Path>
    targetPath()
    Returns an explicit target path, overriding the default value.
    default Path
    targetPath(Project project)
    Returns the fully resolved absolute target path where files should be copied.
    default Optional<Version>
    targetVersion()
    Returns the version of the platform where the code will be executed.

  • Method Details

    • directory

      default Path directory()
      Returns the root directory where the sources are stored. The path is relative to the POM file.

      Default implementation

      The default value depends on whether a module name is specified in this source root: The default value is relative. Implementation may override with absolute path instead.
      Returns:
      the root directory where the sources are stored

    • includes

      default List<String> includes()
      Returns the list of patterns for the files to include. The path separator is / on all platforms, including Windows. The prefix before the : character, if present and longer than 1 character, is the syntax. If no syntax is specified, or if its length is 1 character (interpreted as a Windows drive), the default is a Maven-specific variation of the "glob" pattern.

      The default implementation returns an empty list, which means to apply a language-dependent pattern. For example, for the Java language, the pattern includes all files with the .java suffix.

      Returns:
      the list of patterns for the files to include
      See Also:

    • excludes

      default List<String> excludes()
      Returns the list of patterns for the files to exclude. The exclusions are applied after the inclusions. The default implementation returns an empty list.
      Returns:
      the list of patterns for the files to exclude

    • matcher

      PathMatcher matcher(Collection<String> defaultIncludes, boolean useDefaultExcludes)
      Returns a matcher combining the include and exclude patterns. If the user did not specify any includes, the given defaultIncludes are used. These defaults depend on the plugin. For example, the default include of the Java compiler plugin is "**/*.java".

      If the user did not specify any excludes, the default is often files generated by Source Code Management (SCM) software or by the operating system. Examples: "**/.gitignore", "**/.DS_Store".

      Parameters:
      defaultIncludes - the default includes if unspecified by the user
      useDefaultExcludes - whether to add the default set of patterns to exclude, mostly Source Code Management (SCM) files
      Returns:
      a matcher combining the include and exclude patterns

    • scope

      default ProjectScope scope()
      Returns in which context the source files will be used. Not to be confused with dependency scope. The default value is "main".
      Returns:
      in which context the source files will be used
      See Also:

    • language

      default Language language()
      Returns the language of the source files. The default value is "java".
      Returns:
      the language of the source files
      See Also:

    • module

      default Optional<String> module()
      Returns the name of the Java module (or other language-specific module) which is built by the sources. The default value is empty.
      Returns:
      the name of the Java module (or other language-specific module) which is built by the sources

    • targetVersion

      default Optional<Version> targetVersion()
      Returns the version of the platform where the code will be executed. In a Java environment, this is the value of the --release compiler option. The default value is empty.
      Returns:
      the version of the platform where the code will be executed

    • targetPath

      default Optional<Path> targetPath()
      Returns an explicit target path, overriding the default value.

      Important: This method returns the target path as specified in the configuration, which may be relative or absolute. It does not perform any path resolution. For the fully resolved absolute path, use targetPath(Project) instead.

      Return Value Semantics:

      • Empty Optional - No explicit target path was specified. Files should be copied to the root of the output directory (see Project.getOutputDirectory(ProjectScope)).
      • Relative Path (e.g., Path.of("META-INF/resources")) - The path is intended to be resolved relative to the output directory for this source root's scope(). The actual resolution is performed by targetPath(Project).
      • Absolute Path (e.g., Path.of("/tmp/custom")) - The path is used as-is without any resolution. Files will be copied to this exact location.

      Maven 3 Compatibility: This behavior maintains compatibility with Maven 3.x, where resource targetPath elements were always interpreted as relative to the output directory (project.build.outputDirectory or project.build.testOutputDirectory), not the project base directory. Maven 3 plugins (like maven-resources-plugin) expect to receive the relative path and perform the resolution themselves.

      Effect on Module and Target Version: When a target path is explicitly specified, the values of module() and targetVersion() are not used for inferring the output path (they are still used as compiler options however). This means that for scripts and resources, the files below the path specified by directory() are copied to the path specified by targetPath() with the exact same directory structure.

      Usage Guidance:

      • For Maven 4 API consumers: Use targetPath(Project) to get the fully resolved absolute path where files should be copied.
      • For Maven 3 compatibility layer: Use this method to get the path as specified in the configuration, which can then be passed to legacy plugins that expect to perform their own resolution.
      • For implementers: Store the path exactly as provided in the configuration. Do not resolve relative paths at storage time.
      Returns:
      an explicit target path, overriding the default value
      See Also:

    • targetPath

      @Nonnull default Path targetPath(@Nonnull Project project)
      Returns the fully resolved absolute target path where files should be copied.

      Purpose: This method performs the complete path resolution logic, converting the potentially relative targetPath() into an absolute filesystem path. This is the method that Maven 4 API consumers should use when they need to know the actual destination directory for copying files.

      Resolution Algorithm:

      1. Obtain the configured target path (which may be empty, relative, or absolute)
      2. If the configured target path is absolute (e.g., /tmp/custom):
        • Return it unchanged (no resolution needed)
      3. Otherwise, get the output directory for this source root's scope() by calling project.getOutputDirectory(scope()):
      4. If the configured target path is empty:
        • Return the output directory as-is
      5. If the configured target path is relative (e.g., META-INF/resources):
        • Resolve it against the output directory using outputDirectory.resolve(targetPath)

      Concrete Examples:

      Given a project at /home/user/myproject with ProjectScope.MAIN:

      Target Path Resolution Examples
      Configuration (targetPath()) Output Directory Result (targetPath(project)) Explanation
      Optional.empty() /home/user/myproject/target/classes /home/user/myproject/target/classes No explicit path → use output directory
      Optional.of(Path.of("META-INF")) /home/user/myproject/target/classes /home/user/myproject/target/classes/META-INF Relative path → resolve against output directory
      Optional.of(Path.of("WEB-INF/classes")) /home/user/myproject/target/classes /home/user/myproject/target/classes/WEB-INF/classes Relative path with subdirectories
      Optional.of(Path.of("/tmp/custom")) /home/user/myproject/target/classes /tmp/custom Absolute path → use as-is (no resolution)

      Relationship to targetPath():

      This method is the resolution counterpart to targetPath(), which is the storage method. While targetPath() returns the path as configured (potentially relative), this method returns the absolute path where files will actually be written. The separation allows:

      • Maven 4 API consumers to get absolute paths via this method
      • Maven 3 compatibility layer to get relative paths via targetPath() for legacy plugins
      • Implementations to store paths without premature resolution

      Implementation Note: The default implementation is equivalent to: 

      
 Optional<Path> configured = targetPath();
 if (configured.isPresent() && configured.get().isAbsolute()) {
     return configured.get();
 }
 Path outputDir = project.getOutputDirectory(scope());
 return configured.map(outputDir::resolve).orElse(outputDir);
      Parameters:
      project - the project to use for obtaining the output directory
      Returns:
      the absolute path where files from directory() should be copied
      See Also:

    • stringFiltering

      default boolean stringFiltering()
      Returns whether resources are filtered to replace tokens with parameterized values. The default value is false.
      Returns:
      whether resources are filtered to replace tokens with parameterized values

    • enabled

      default boolean enabled()
      Returns whether the directory described by this source element should be included in the build. The default value is true.
      Returns:
      whether the directory described by this source element should be included in the build