extractors;
+ /**
+ * A set of root directories to exclude from being scanned, if the extractor scans source directories
+ * to obtain metadata.
+ *
+ * Users can specify this to prevent certain generated source roots from being parsed by this plugin
+ * in the event that those source roots contain potentially malformed or incompatible code.
+ *
+ *
This is primarily designed to facilitate allowing this plugin to operate with generated sources
+ * that use annotations or documentation in an uncontrollable format that may conflict with the parsing
+ * rules we utilise.
+ *
+ *
Note that this only accepts source roots. It will not accept
+ * specific paths within a source root (e.g. specific packages). In this context, a source root
+ * would be considered to be a directory holding a full Java package structure which can be
+ * passed directly to {@code javac} for compilation, or {@code javadoc} for documentation.
+ *
+ *
As an example, the following configuration will prevent this goal scanning any
+ * generated sources from annotation processors:
+ *
+ *
{@code
+ *
+ * ${project.build.directory}/generated-sources/annotations
+ * ${project.build.directory}/generated-test-sources/annotations
+ *
+ * }
+ *
+ * @since TBC
+ */
+ @Parameter
+ private Set excludedScanDirectories = Collections.emptySet();
+
/**
* By default, an exception is throw if no mojo descriptor is found. As the maven-plugin is defined in core, the
* descriptor generator mojo is bound to generate-resources phase.
@@ -351,6 +382,7 @@ public void generate() throws MojoExecutionException {
request.setInternalJavadocVersion(internalJavadocVersion);
request.setExternalJavadocBaseUrls(externalJavadocBaseUrls);
request.setSettings(mavenSession.getSettings());
+ request.setExcludedScanDirectories(excludedScanDirectories);
mojoScanner.populatePluginDescriptor(request);
request.setPluginDescriptor(extendPluginDescriptor(request));
diff --git a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java
index 043473499..ae31e2207 100644
--- a/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java
+++ b/maven-plugin-tools-annotations/src/main/java/org/apache/maven/tools/plugin/extractor/annotations/JavaAnnotationsMojoDescriptorExtractor.java
@@ -254,7 +254,7 @@ private JavaProjectBuilder scanJavadoc(
JavaProjectBuilder builder = new JavaProjectBuilder(new SortedClassLibraryBuilder());
builder.setEncoding(request.getEncoding());
- extendJavaProjectBuilder(builder, request.getProject());
+ extendJavaProjectBuilder(request, builder, request.getProject());
for (MojoAnnotatedClass mojoAnnotatedClass : mojoAnnotatedClasses) {
if (Objects.equals(
@@ -289,7 +289,7 @@ private JavaProjectBuilder scanJavadoc(
}
for (MavenProject mavenProject : mavenProjects) {
- extendJavaProjectBuilder(builder, mavenProject);
+ extendJavaProjectBuilder(request, builder, mavenProject);
}
return builder;
@@ -630,11 +630,19 @@ protected void extendJavaProjectBuilderWithSourcesJar(
}
}
- private void extendJavaProjectBuilder(JavaProjectBuilder builder, final MavenProject project) {
+ private void extendJavaProjectBuilder(
+ PluginToolsRequest request, JavaProjectBuilder builder, final MavenProject project) {
List sources = new ArrayList<>();
for (String source : project.getCompileSourceRoots()) {
- sources.add(new File(source));
+ File sourceFile = new File(source);
+
+ // Allow users to exclude certain paths such as generated sources from being scanned, in the case that
+ // this may be problematic for them (e.g. using obscure unsupported syntax by the parser, comments that
+ // cannot be controlled, etc.)
+ if (!isExcludedDirectory(request.getExcludedScanDirectories(), sourceFile)) {
+ sources.add(sourceFile);
+ }
}
// TODO be more dynamic
@@ -642,9 +650,23 @@ private void extendJavaProjectBuilder(JavaProjectBuilder builder, final MavenPro
if (!project.getCompileSourceRoots().contains(generatedPlugin.getAbsolutePath()) && generatedPlugin.exists()) {
sources.add(generatedPlugin);
}
+
extendJavaProjectBuilder(builder, sources, project.getArtifacts());
}
+ private boolean isExcludedDirectory(Collection excludedDirectories, File sourceFile) {
+ for (File excludedScanDirectory : excludedDirectories) {
+ File candidateFile = sourceFile;
+ while (candidateFile != null) {
+ if (excludedScanDirectory.equals(candidateFile)) {
+ return true;
+ }
+ candidateFile = candidateFile.getParentFile();
+ }
+ }
+ return false;
+ }
+
private void extendJavaProjectBuilder(
JavaProjectBuilder builder, List sourceDirectories, Set artifacts) {
diff --git a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/DefaultPluginToolsRequest.java b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/DefaultPluginToolsRequest.java
index 1beb53791..6990fda0a 100644
--- a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/DefaultPluginToolsRequest.java
+++ b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/DefaultPluginToolsRequest.java
@@ -18,7 +18,9 @@
*/
package org.apache.maven.tools.plugin;
+import java.io.File;
import java.net.URI;
+import java.util.Collection;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
@@ -66,6 +68,8 @@ public class DefaultPluginToolsRequest implements PluginToolsRequest {
private String mavenApiVersion;
+ private Collection excludedScanDirectories;
+
public DefaultPluginToolsRequest(MavenProject project, PluginDescriptor pluginDescriptor) {
this.project = project;
this.pluginDescriptor = pluginDescriptor;
@@ -232,4 +236,17 @@ public PluginToolsRequest setUsedMavenApiVersion(String mavenApiVersion) {
public String getUsedMavenApiVersion() {
return mavenApiVersion;
}
+
+ @Override
+ public Collection getExcludedScanDirectories() {
+ if (excludedScanDirectories == null) {
+ excludedScanDirectories = new HashSet<>();
+ }
+ return excludedScanDirectories;
+ }
+
+ @Override
+ public void setExcludedScanDirectories(Collection excludedScanDirectories) {
+ this.excludedScanDirectories = excludedScanDirectories;
+ }
}
diff --git a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/PluginToolsRequest.java b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/PluginToolsRequest.java
index 079b120d4..64f232d3e 100644
--- a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/PluginToolsRequest.java
+++ b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/PluginToolsRequest.java
@@ -18,7 +18,9 @@
*/
package org.apache.maven.tools.plugin;
+import java.io.File;
import java.net.URI;
+import java.util.Collection;
import java.util.List;
import java.util.Set;
@@ -211,4 +213,20 @@ public interface PluginToolsRequest {
* @since 3.8.0
*/
String getUsedMavenApiVersion();
+
+ /**
+ * Get the collection of directories to exclude from scanning during the detection of sources.
+ *
+ * @return the directories to exclude from scanning during detection of sources.
+ * @since TBC
+ */
+ Collection getExcludedScanDirectories();
+
+ /**
+ * Set the collection of directories to exclude from scanning during the detection of sources.
+ *
+ * @param excludedScanDirectories the directories to exclude from scanning during detection of sources.
+ * @since TBC
+ */
+ void setExcludedScanDirectories(Collection excludedScanDirectories);
}
diff --git a/maven-plugin-tools-java/src/main/java/org/apache/maven/tools/plugin/extractor/javadoc/JavaJavadocMojoDescriptorExtractor.java b/maven-plugin-tools-java/src/main/java/org/apache/maven/tools/plugin/extractor/javadoc/JavaJavadocMojoDescriptorExtractor.java
index 7bd772f68..a990b7c4f 100644
--- a/maven-plugin-tools-java/src/main/java/org/apache/maven/tools/plugin/extractor/javadoc/JavaJavadocMojoDescriptorExtractor.java
+++ b/maven-plugin-tools-java/src/main/java/org/apache/maven/tools/plugin/extractor/javadoc/JavaJavadocMojoDescriptorExtractor.java
@@ -548,7 +548,13 @@ protected Collection discoverClasses(final PluginToolsRequest request
MavenProject project = request.getProject();
for (String source : project.getCompileSourceRoots()) {
- builder.addSourceTree(new File(source));
+ // Allow users to exclude certain paths such as generated sources from being scanned, in the case that
+ // this may be problematic for them (e.g. using obscure unsupported syntax by the parser, comments that
+ // cannot be controlled, etc.)
+ File sourceFile = new File(source);
+ if (!isExcludedDirectory(request.getExcludedScanDirectories(), sourceFile)) {
+ builder.addSourceTree(sourceFile);
+ }
}
// TODO be more dynamic
@@ -573,4 +579,17 @@ protected void validate(MojoDescriptor mojoDescriptor) throws InvalidParameterEx
}
}
}
+
+ private boolean isExcludedDirectory(Collection excludedDirectories, File sourceFile) {
+ for (File excludedScanDirectory : excludedDirectories) {
+ File candidateFile = sourceFile;
+ while (candidateFile != null) {
+ if (excludedScanDirectory.equals(candidateFile)) {
+ return true;
+ }
+ candidateFile = candidateFile.getParentFile();
+ }
+ }
+ return false;
+ }
}
From 64a95079c419fe4c7bc74d0f0c8e4479845bbd0d Mon Sep 17 00:00:00 2001
From: Ash <73482956+ascopes@users.noreply.github.com>
Date: Tue, 23 Dec 2025 11:04:58 +0000
Subject: [PATCH 2/2] Apply suggestions from code review
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
.../src/it/gh-944-exclude-source-directory/pom.xml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/maven-plugin-plugin/src/it/gh-944-exclude-source-directory/pom.xml b/maven-plugin-plugin/src/it/gh-944-exclude-source-directory/pom.xml
index 6276aca0c..c59b6e3fc 100644
--- a/maven-plugin-plugin/src/it/gh-944-exclude-source-directory/pom.xml
+++ b/maven-plugin-plugin/src/it/gh-944-exclude-source-directory/pom.xml
@@ -22,8 +22,8 @@ under the License.
4.0.0
- org.apache.maven.its.mplugin-382
- mplugin-382-exclude-provided-dependency
+ org.apache.maven.its.gh-944-exclude-source-directory
+ gh-944-exclude-source-directory
1.0-SNAPSHOT
maven-plugin