[MNG-8395] Redirect the <sourceDirectory> element to <Source> (#2061)

* Include the list of <Source> elements in the path translation.

* Add a `SourceRoot` interface for the properties declared in the POM's `<Source>` element.
The API use method names without `get` prefix in anticipation for possible use of records in the future.

In the `MavenProject` class, the `compileSourceRoots`, `testCompileSourceRoots` and `scriptSourceRoots`
fields are replaced by redirections to the new `sources` field with paths wrapped in `SourceRoot` objects.
The getters and setters methods for the previous fields are deprecated.
This commit contains other opportunistic deprecations on methods working with deprecated interfaces.

In the POM file, the above-cited properties are ignored if a corresponding `<Source>` element exists.
This rule exits because Maven sets default values to those fields, which can interfer with user's setting.

* Deprecate POM elements that are replaced by <Source> elements.

* Add @deprecated annotation on model elements flagged as @deprecated in the documentation.

* Update `ProjectManager` API using `SourceRoot`:

- Add `addSourceRoot(Project, …)` methods.
- Add `getSourceRoots()` and `getEnabledSourceRoots(ProjectScope, Language)`.
- Remove `get/addResource(Project, …)` methods.
- Remove `get/addCompileSourceRoots(Project, …)` methods.

---------

Co-authored-by: Guillaume Nodet <[email protected]>

Author: desruisseaux

api/maven-api-core/src/main/java/org/apache/maven/api/Language.java

@@ -45,6 +45,19 @@ public interface Language extends ExtensibleEnum {
      */
     Language NONE = language("none");
 
+    /**
+     * The "resources" language. This is used for files such as images to provide in the output.
+     */
+    Language RESOURCES = language("resources");
+
+    /**
+     * The "script" language. Provided for compatibility with Maven 3.
+     *
+     * @deprecated Use {@link #RESOURCES} instead.
+     */
+    @Deprecated
+    Language SCRIPT = language("script");
+
     // TODO: this should be moved out from here to Java Support (builtin into core)
     Language JAVA_FAMILY = language("java");
 }

api/maven-api-core/src/main/java/org/apache/maven/api/Project.java

@@ -49,25 +49,25 @@
 public interface Project {
 
     /**
-     * Returns the project groupId.
+     * {@return the project groupId}.
      */
     @Nonnull
     String getGroupId();
 
     /**
-     * Returns the project artifactId.
+     * {@return the project artifactId}.
      */
     @Nonnull
     String getArtifactId();
 
     /**
-     * Returns the project version.
+     * {@return the project version}.
      */
     @Nonnull
     String getVersion();
 
     /**
-     * Returns the project packaging.
+     * {@return the project packaging}.
      * <p>
      * Note: unlike in legacy code, logical checks against string representing packaging (returned by this method)
      * are NOT recommended (code like {@code "pom".equals(project.getPackaging)} must be avoided). Use method
@@ -79,7 +79,7 @@ public interface Project {
     Packaging getPackaging();
 
     /**
-     * Returns the project language. It is by default determined by {@link #getPackaging()}.
+     * {@return the project language}. It is by default determined by {@link #getPackaging()}.
      *
      * @see #getPackaging()
      */
@@ -89,7 +89,7 @@ default Language getLanguage() {
     }
 
     /**
-     * Returns the project POM artifact, which is the artifact of the POM of this project. Every project have a POM
+     * {@return the project POM artifact}, which is the artifact of the POM of this project. Every project have a POM
      * artifact, even if the existence of backing POM file is NOT a requirement (i.e. for some transient projects).
      *
      * @see org.apache.maven.api.services.ArtifactManager#getPath(Artifact)
@@ -100,7 +100,7 @@ default ProducedArtifact getPomArtifact() {
     }
 
     /**
-     * Returns the project main artifact, which is the artifact produced by this project build, if applicable.
+     * {@return the project main artifact}, which is the artifact produced by this project build, if applicable.
      * This artifact MAY be absent if the project is actually not producing any main artifact (i.e. "pom" packaging).
      *
      * @see #getPackaging()
@@ -113,7 +113,7 @@ default Optional<ProducedArtifact> getMainArtifact() {
     }
 
     /**
-     * Returns the project artifacts as immutable list. Elements are the project POM artifact and the artifact
+     * {@return the project artifacts as immutable list}. Elements are the project POM artifact and the artifact
      * produced by this project build, if applicable. Hence, the returned list may have one or two elements
      * (never less than 1, never more than 2), depending on project packaging.
      * <p>
@@ -129,13 +129,15 @@ default Optional<ProducedArtifact> getMainArtifact() {
     List<ProducedArtifact> getArtifacts();
 
     /**
-     * Returns the project model.
+     * {@return the project model}.
      */
     @Nonnull
     Model getModel();
 
     /**
      * Shorthand method.
+     *
+     * @return the build element of the project model
      */
     @Nonnull
     default Build getBuild() {
@@ -170,19 +172,19 @@ default Build getBuild() {
     Path getBasedir();
 
     /**
-     * Returns the project direct dependencies (directly specified or inherited).
+     * {@return the project direct dependencies (directly specified or inherited)}.
      */
     @Nonnull
     List<DependencyCoordinates> getDependencies();
 
     /**
-     * Returns the project managed dependencies (directly specified or inherited).
+     * {@return the project managed dependencies (directly specified or inherited)}.
      */
     @Nonnull
     List<DependencyCoordinates> getManagedDependencies();
 
     /**
-     * Returns the project ID, usable as key.
+     * {@return the project ID, usable as key}.
      */
     @Nonnull
     default String getId() {
@@ -216,6 +218,7 @@ default String getId() {
      * Gets the root directory of the project, which is the parent directory
      * containing the {@code .mvn} directory or flagged with {@code root="true"}.
      *
+     * @return the root directory of the project
      * @throws IllegalStateException if the root directory could not be found
      * @see Session#getRootDirectory()
      */

api/maven-api-core/src/main/java/org/apache/maven/api/SourceRoot.java

@@ -0,0 +1,111 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api;
+
+import java.nio.file.Path;
+import java.nio.file.PathMatcher;
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * A root directory of source files.
+ * The sources may be Java main classes, test classes, resources or anything else identified by the scope.
+ */
+public interface SourceRoot {
+    /**
+     * {@return the root directory where the sources are stored}.
+     * The path is relative to the <abbr>POM</abbr> file.
+     */
+    Path directory();
+
+    /**
+     * {@return the list of pattern matchers for the files to include}.
+     * 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 {@code .java} suffix.
+     */
+    default List<PathMatcher> includes() {
+        return List.of();
+    }
+
+    /**
+     * {@return the list of pattern matchers for the files to exclude}.
+     * The exclusions are applied after the inclusions.
+     * The default implementation returns an empty list.
+     */
+    default List<PathMatcher> excludes() {
+        return List.of();
+    }
+
+    /**
+     * {@return in which context the source files will be used}.
+     * The default value is {@link ProjectScope#MAIN}.
+     */
+    default ProjectScope scope() {
+        return ProjectScope.MAIN;
+    }
+
+    /**
+     * {@return the language of the source files}.
+     */
+    Language language();
+
+    /**
+     * {@return the name of the Java module (or other language-specific module) which is built by the sources}.
+     * The default value is empty.
+     */
+    default Optional<String> module() {
+        return Optional.empty();
+    }
+
+    /**
+     * {@return the version of the platform where the code will be executed}.
+     * In a Java environment, this is the value of the {@code --release} compiler option.
+     * The default value is empty.
+     */
+    default Optional<Version> targetVersion() {
+        return Optional.empty();
+    }
+
+    /**
+     * {@return an explicit target path, overriding the default value}.
+     * When a target path is explicitly specified, the values of the {@link #module()} and {@link #targetVersion()}
+     * elements are not used for inferring the path (they are still used as compiler options however).
+     * It means that for scripts and resources, the files below the path specified by {@link #directory()}
+     * are copied to the path specified by {@code targetPath()} with the exact same directory structure.
+     */
+    default Optional<Path> targetPath() {
+        return Optional.empty();
+    }
+
+    /**
+     * {@return whether resources are filtered to replace tokens with parameterized values}.
+     * The default value is {@code false}.
+     */
+    default boolean stringFiltering() {
+        return false;
+    }
+
+    /**
+     * {@return whether the directory described by this source element should be included in the build}.
+     * The default value is {@code true}.
+     */
+    default boolean enabled() {
+        return true;
+    }
+}