Package org.apache.maven.api.services

Interface PathMatcherFactory

All Superinterfaces:
Service
All Known Implementing Classes:
DefaultPathMatcherFactory
@Experimental public interface PathMatcherFactory extends Service
Service for creating 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.

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.

Pattern syntax supports:

  • Standard glob patterns with *, ?, and ** wildcards
  • Explicit syntax prefixes like "glob:" or "regex:"
  • Maven 3 compatible behavior for patterns without explicit syntax
  • Default exclusion patterns for SCM files when requested
Since:
4.0.0
See Also:

  • Method Details

    • createPathMatcher

      @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.

      The pathnames used for matching will be relative to the specified base directory and use '/' as separator, regardless of the hosting operating system.

      Parameters:
      baseDirectory - the base directory for relativizing paths during matching
      includes - the patterns of files to include, or null/empty for including all files
      excludes - the patterns of files to exclude, or null/empty for no exclusion
      useDefaultExcludes - whether to augment excludes with default SCM exclusion patterns
      Returns:
      a PathMatcher that can be used to test if paths should be included
      Throws:
      NullPointerException - if baseDirectory is null

    • createPathMatcher

      @Nonnull default PathMatcher createPathMatcher(@Nonnull Path baseDirectory, Collection<String> includes, Collection<String> excludes)
      Creates a path matcher for filtering files based on include and exclude patterns, without using default exclusion patterns.

      This is equivalent to calling createPathMatcher(Path, Collection, Collection, boolean) with useDefaultExcludes = false.

      Parameters:
      baseDirectory - the base directory for relativizing paths during matching
      includes - the patterns of files to include, or null/empty for including all files
      excludes - the patterns of files to exclude, or null/empty for no exclusion
      Returns:
      a PathMatcher that can be used to test if paths should be included
      Throws:
      NullPointerException - if baseDirectory is null

    • createExcludeOnlyMatcher

      @Nonnull default PathMatcher createExcludeOnlyMatcher(@Nonnull Path baseDirectory, Collection<String> excludes, boolean useDefaultExcludes)
      Creates a path matcher that includes all files except those matching the exclude patterns.

      This is equivalent to calling createPathMatcher(Path, Collection, Collection, boolean) with includes = null.

      Parameters:
      baseDirectory - the base directory for relativizing paths during matching
      excludes - the patterns of files to exclude, or null/empty for no exclusion
      useDefaultExcludes - whether to augment excludes with default SCM exclusion patterns
      Returns:
      a PathMatcher that can be used to test if paths should be included
      Throws:
      NullPointerException - if baseDirectory is null

    • createIncludeOnlyMatcher

      @Nonnull default PathMatcher createIncludeOnlyMatcher(@Nonnull Path baseDirectory, Collection<String> includes)
      Creates a path matcher that only includes files matching the include patterns.

      This is equivalent to calling createPathMatcher(Path, Collection, Collection, boolean) with excludes = null and useDefaultExcludes = false.

      Parameters:
      baseDirectory - the base directory for relativizing paths during matching
      includes - the patterns of files to include, or null/empty for including all files
      Returns:
      a PathMatcher that can be used to test if paths should be included
      Throws:
      NullPointerException - if baseDirectory is null

    • deriveDirectoryMatcher

      @Nonnull PathMatcher deriveDirectoryMatcher(@Nonnull PathMatcher fileMatcher)
      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 directory paths. If that matcher returns 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 true.
      Parameters:
      fileMatcher - a matcher created by one of the other methods of this interface
      Returns:
      filter for directories that may contain the selected files
      Throws:
      NullPointerException - if fileMatcher is null

    • includesAll

      @Nonnull PathMatcher includesAll()
      Returns the path matcher that unconditionally returns true for all files. It should be the matcher returned by the other methods of this interface when the given patterns match all files.
      Returns:
      path matcher that unconditionally returns true for all files

    • isIncludesAll

      default boolean isIncludesAll(@Nonnull PathMatcher matcher)
      Returns whether the given matcher includes all files.. This method may conservatively returns false if case of doubt. A return value of true means that the pattern is certain to match all files.
      Parameters:
      matcher - the matcher to test
      Returns:
      whether the given matcher includes all files