Add PathMatcherFactory service with directory filtering optimization

gnodet · gnodet · commit 91e416d09c4f · 2025-07-17T05:47:39.000Z
This PR adds a comprehensive PathMatcherFactory service to Maven 4 API with directory filtering optimization capabilities, addressing the need for exclude-only pattern matching and performance optimizations. ## New API Features ### PathMatcherFactory Interface - createPathMatcher(baseDirectory, includes, excludes, useDefaultExcludes) - createPathMatcher(baseDirectory, includes, excludes) - convenience overload - createExcludeOnlyMatcher(baseDirectory, excludes, useDefaultExcludes) - createIncludeOnlyMatcher(baseDirectory, includes) - convenience method - deriveDirectoryMatcher(fileMatcher) - directory filtering optimization ### DefaultPathMatcherFactory Implementation - Full implementation of all PathMatcherFactory methods - Delegates to PathSelector for actual pattern matching - Provides directory optimization via PathSelector.couldHoldSelected() - Fail-safe design returning INCLUDES_ALL for unknown matcher types ## PathSelector Enhancements ### Null Safety Improvements - Added @nonnull annotation to constructor directory parameter - Added Objects.requireNonNull() validation with descriptive error message - Moved baseDirectory assignment to beginning for fail-fast behavior - Updated JavaDoc to document NullPointerException behavior ### Directory Filtering Support - Added canFilterDirectories() method to check optimization capability - Made INCLUDES_ALL field package-private for factory reuse - Enhanced couldHoldSelected() method accessibility ## Directory Filtering Optimization The deriveDirectoryMatcher() method enables significant performance improvements by allowing plugins to skip entire directory trees when they definitively won't contain matching files. This preserves Maven 3's optimization behavior. ### Usage Example: ## Comprehensive Testing ### DefaultPathMatcherFactoryTest - Tests all factory methods with various parameter combinations - Verifies null parameter handling (NullPointerException) - Tests directory matcher derivation functionality - Includes edge cases and fail-safe behavior verification ### Backward Compatibility - All existing PathSelector functionality preserved - No breaking changes to existing APIs - Enhanced error handling with better exception types ## Benefits 1. **Plugin Compatibility**: Enables maven-clean-plugin and other plugins to use exclude-only patterns efficiently 2. **Performance**: Directory filtering optimization preserves Maven 3 behavior 3. **Developer Experience**: Clean service interface with comprehensive JavaDoc 4. **Robustness**: Fail-fast null validation and defensive programming 5. **Future-Proof**: Extensible design for additional pattern matching needs ## Related Work This implementation complements PR #10909 by @desruisseaux which addresses PathSelector bug fixes. Both PRs can be merged independently and work together to provide complete exclude-only functionality. Addresses performance optimization suggestions and provides the missing API methods needed by Maven plugins for efficient file filtering.
diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathMatcherFactory.java b/api/maven-api-core/src/main/java/org/apache/maven/api/services/PathMatcherFactory.java
@@ -0,0 +1,141 @@
+/*
+ * 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.services;
+
+import java.nio.file.Path;
+import java.nio.file.PathMatcher;
+import java.util.Collection;
+
+import org.apache.maven.api.Service;
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Nonnull;
+
+/**
+ * Service for creating {@link PathMatcher} objects that can be used to filter files
+ * based on include/exclude patterns. This service provides a clean API for plugins
+ * to create path matchers without directly depending on implementation classes.
+ * <p>
+ * The path matchers created by this service support Maven's traditional include/exclude
+ * pattern syntax, which is compatible with the behavior of Maven 3 plugins like
+ * maven-compiler-plugin and maven-clean-plugin.
+ * <p>
+ * Pattern syntax supports:
+ * <ul>
+ *   <li>Standard glob patterns with {@code *}, {@code ?}, and {@code **} wildcards</li>
+ *   <li>Explicit syntax prefixes like {@code "glob:"} or {@code "regex:"}</li>
+ *   <li>Maven 3 compatible behavior for patterns without explicit syntax</li>
+ *   <li>Default exclusion patterns for SCM files when requested</li>
+ * </ul>
+ *
+ * @since 4.0.0
+ * @see PathMatcher
+ */
+@Experimental
+public interface PathMatcherFactory extends Service {
+
+    /**
+     * Creates a path matcher for filtering files based on include and exclude patterns.
+     * <p>
+     * The pathnames used for matching will be relative to the specified base directory
+     * and use {@code '/'} as separator, regardless of the hosting operating system.
+     *
+     * @param baseDirectory the base directory for relativizing paths during matching
+     * @param includes the patterns of files to include, or null/empty for including all files
+     * @param excludes the patterns of files to exclude, or null/empty for no exclusion
+     * @param useDefaultExcludes whether to augment excludes with default SCM exclusion patterns
+     * @return a PathMatcher that can be used to test if paths should be included
+     * @throws NullPointerException if baseDirectory is null
+     */
+    @Nonnull
+    PathMatcher createPathMatcher(
+            @Nonnull Path baseDirectory,
+            Collection<String> includes,
+            Collection<String> excludes,
+            boolean useDefaultExcludes);
+
+    /**
+     * Creates a path matcher for filtering files based on include and exclude patterns,
+     * without using default exclusion patterns.
+     * <p>
+     * This is equivalent to calling {@link #createPathMatcher(Path, Collection, Collection, boolean)}
+     * with {@code useDefaultExcludes = false}.
+     *
+     * @param baseDirectory the base directory for relativizing paths during matching
+     * @param includes the patterns of files to include, or null/empty for including all files
+     * @param excludes the patterns of files to exclude, or null/empty for no exclusion
+     * @return a PathMatcher that can be used to test if paths should be included
+     * @throws NullPointerException if baseDirectory is null
+     */
+    @Nonnull
+    default PathMatcher createPathMatcher(
+            @Nonnull Path baseDirectory, Collection<String> includes, Collection<String> excludes) {
+        return createPathMatcher(baseDirectory, includes, excludes, false);
+    }
+
+    /**
+     * Creates a path matcher that includes all files except those matching the exclude patterns.
+     * <p>
+     * This is equivalent to calling {@link #createPathMatcher(Path, Collection, Collection, boolean)}
+     * with {@code includes = null}.
+     *
+     * @param baseDirectory the base directory for relativizing paths during matching
+     * @param excludes the patterns of files to exclude, or null/empty for no exclusion
+     * @param useDefaultExcludes whether to augment excludes with default SCM exclusion patterns
+     * @return a PathMatcher that can be used to test if paths should be included
+     * @throws NullPointerException if baseDirectory is null
+     */
+    @Nonnull
+    default PathMatcher createExcludeOnlyMatcher(
+            @Nonnull Path baseDirectory, Collection<String> excludes, boolean useDefaultExcludes) {
+        return createPathMatcher(baseDirectory, null, excludes, useDefaultExcludes);
+    }
+
+    /**
+     * Creates a path matcher that only includes files matching the include patterns.
+     * <p>
+     * This is equivalent to calling {@link #createPathMatcher(Path, Collection, Collection, boolean)}
+     * with {@code excludes = null} and {@code useDefaultExcludes = false}.
+     *
+     * @param baseDirectory the base directory for relativizing paths during matching
+     * @param includes the patterns of files to include, or null/empty for including all files
+     * @return a PathMatcher that can be used to test if paths should be included
+     * @throws NullPointerException if baseDirectory is null
+     */
+    @Nonnull
+    default PathMatcher createIncludeOnlyMatcher(@Nonnull Path baseDirectory, Collection<String> includes) {
+        return createPathMatcher(baseDirectory, includes, null, false);
+    }
+
+    /**
+     * Returns a filter for directories that may contain paths accepted by the given matcher.
+     * The given path matcher should be an instance created by this service.
+     * The path matcher returned by this method expects <em>directory</em> paths.
+     * If that matcher returns {@code false}, then the directory will definitively not contain
+     * the paths selected by the matcher given in argument to this method.
+     * In such case, the whole directory and all its sub-directories can be skipped.
+     * In case of doubt, or if the matcher given in argument is not recognized by this method,
+     * then the matcher returned by this method will return {@code true}.
+     *
+     * @param fileMatcher a matcher created by one of the other methods of this interface
+     * @return filter for directories that may contain the selected files
+     * @throws NullPointerException if fileMatcher is null
+     */
+    @Nonnull
+    PathMatcher deriveDirectoryMatcher(@Nonnull PathMatcher fileMatcher);
+}
diff --git a/impl/maven-impl/src/main/java/org/apache/maven/impl/DefaultPathMatcherFactory.java b/impl/maven-impl/src/main/java/org/apache/maven/impl/DefaultPathMatcherFactory.java
@@ -0,0 +1,75 @@
+/*
+ * 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.impl;
+
+import java.nio.file.Path;
+import java.nio.file.PathMatcher;
+import java.util.Collection;
+import java.util.Objects;
+
+import org.apache.maven.api.annotations.Nonnull;
+import org.apache.maven.api.di.Named;
+import org.apache.maven.api.di.Singleton;
+import org.apache.maven.api.services.PathMatcherFactory;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * Default implementation of {@link PathMatcherFactory} that creates {@link PathSelector}
+ * instances for filtering files based on include/exclude patterns.
+ * <p>
+ * This implementation provides Maven's traditional include/exclude pattern behavior,
+ * compatible with Maven 3 plugins like maven-compiler-plugin and maven-clean-plugin.
+ *
+ * @since 4.0.0
+ */
+@Named
+@Singleton
+public class DefaultPathMatcherFactory implements PathMatcherFactory {
+
+    @Nonnull
+    @Override
+    public PathMatcher createPathMatcher(
+            @Nonnull Path baseDirectory,
+            Collection<String> includes,
+            Collection<String> excludes,
+            boolean useDefaultExcludes) {
+        requireNonNull(baseDirectory, "baseDirectory cannot be null");
+
+        return new PathSelector(baseDirectory, includes, excludes, useDefaultExcludes);
+    }
+
+    @Nonnull
+    @Override
+    public PathMatcher createExcludeOnlyMatcher(
+            @Nonnull Path baseDirectory, Collection<String> excludes, boolean useDefaultExcludes) {
+        return createPathMatcher(baseDirectory, null, excludes, useDefaultExcludes);
+    }
+
+    @Nonnull
+    @Override
+    public PathMatcher deriveDirectoryMatcher(@Nonnull PathMatcher fileMatcher) {
+        if (Objects.requireNonNull(fileMatcher) instanceof PathSelector selector) {
+            if (selector.canFilterDirectories()) {
+                return selector::couldHoldSelected;
+            }
+        }
+        return PathSelector.INCLUDES_ALL;
+    }
+}
diff --git a/impl/maven-impl/src/main/java/org/apache/maven/impl/PathSelector.java b/impl/maven-impl/src/main/java/org/apache/maven/impl/PathSelector.java
@@ -28,8 +28,11 @@
 import java.util.Iterator;
 import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Objects;
 import java.util.Set;
 
+import org.apache.maven.api.annotations.Nonnull;
+
 /**
  * Determines whether a path is selected according to include/exclude patterns.
  * The pathnames used for method parameters will be relative to some base directory
@@ -163,7 +166,7 @@ public class PathSelector implements PathMatcher {
      *
      * @see #simplify()
      */
-    private static final PathMatcher INCLUDES_ALL = (path) -> true;
+    static final PathMatcher INCLUDES_ALL = (path) -> true;
 
     /**
      * String representations of the normalized include filters.
@@ -219,13 +222,17 @@ public class PathSelector implements PathMatcher {
      * @param includes the patterns of the files to include, or null or empty for including all files
      * @param excludes the patterns of the files to exclude, or null or empty for no exclusion
      * @param useDefaultExcludes whether to augment the excludes with a default set of <abbr>SCM</abbr> patterns
+     * @throws NullPointerException if directory is null
      */
     public PathSelector(
-            Path directory, Collection<String> includes, Collection<String> excludes, boolean useDefaultExcludes) {
+            @Nonnull Path directory,
+            Collection<String> includes,
+            Collection<String> excludes,
+            boolean useDefaultExcludes) {
+        baseDirectory = Objects.requireNonNull(directory, "directory cannot be null");
         includePatterns = normalizePatterns(includes, false);
         excludePatterns = normalizePatterns(effectiveExcludes(excludes, includePatterns, useDefaultExcludes), true);
-        baseDirectory = directory;
-        FileSystem system = directory.getFileSystem();
+        FileSystem system = baseDirectory.getFileSystem();
         this.includes = matchers(system, includePatterns);
         this.excludes = matchers(system, excludePatterns);
         dirIncludes = matchers(system, directoryPatterns(includePatterns, false));
@@ -570,6 +577,17 @@ private static boolean isMatched(Path path, PathMatcher[] matchers) {
         return false;
     }
 
+    /**
+     * Returns whether {@link #couldHoldSelected(Path)} may return {@code false} for some directories.
+     * This method can be used to determine if directory filtering optimization is possible.
+     *
+     * @return {@code true} if directory filtering is possible, {@code false} if all directories
+     *         will be considered as potentially containing selected files
+     */
+    boolean canFilterDirectories() {
+        return dirIncludes.length != 0 || dirExcludes.length != 0;
+    }
+
     /**
      * Determines whether a directory could contain selected paths.
      *
diff --git a/impl/maven-impl/src/test/java/org/apache/maven/impl/DefaultPathMatcherFactoryTest.java b/impl/maven-impl/src/test/java/org/apache/maven/impl/DefaultPathMatcherFactoryTest.java
