Package org.machanism.machai.gw.processor

Class AbstractFileProcessor

java.lang.Object
org.machanism.machai.project.ProjectProcessor
org.machanism.machai.gw.processor.AbstractFileProcessor
Direct Known Subclasses:
AIFileProcessor
public abstract class AbstractFileProcessor extends ProjectProcessor
Base implementation for processors that traverse a project directory and perform work on files and folders.

AbstractFileProcessor provides common functionality used by the Ghostwriter CLI, such as:

  • Collecting files under a project directory while excluding common build and tooling folders,
  • Supporting optional include matching via PathMatcher and optional exclusion patterns, and
  • Delegating per-file work to subclasses via processFile(ProjectLayout, File).

This class does not perform dependency resolution or builds; it operates on the filesystem only.

  • Field Details

    • rootDir

      private File rootDir
      Root scanning directory for the current documentation run.

    • path

      private File path
      Specifies a special scanning path or path pattern. This should be a relative path with respect to the current processing project. If an absolute path is provided, it must be located within the rootDir.

    • threads

      private int threads
      Degree of concurrency for module processing.

    • nonRecursive

      private boolean nonRecursive
      Whether module discovery/recursion is disabled for the current run.

    • pathMatcher

      private PathMatcher pathMatcher
      Optional matcher used to limit module/file processing to a subset.

    • excludes

      private String[] excludes
      Optional list of path patterns or exact paths to exclude.

    • configurator

      private final MutableConfigurator configurator
      Configuration source used to initialize providers.

    • moduleThreadTimeoutMinutes

      private long moduleThreadTimeoutMinutes
      Timeout for module processing worker pool shutdown, in minutes.

  • Constructor Details

    • AbstractFileProcessor

      protected AbstractFileProcessor(File rootDir, Configurator configurator)
      Creates a new file processor.
      Parameters:
      rootDir - root directory used as a base for relative path
      configurator - configuration source used by implementations

  • Method Details

    • scanFolder

      public void scanFolder(File projectDir) throws IOException
      Recursively scans project folders, processing documentation inputs for all found modules and files.
      Overrides:
      scanFolder in class ProjectProcessor
      Parameters:
      projectDir - the directory containing the project/module to be scanned
      Throws:
      IOException - if an error occurs reading files

    • processModulesMultiThreaded

      void processModulesMultiThreaded(File projectDir, List<String> modules)
      Processes all discovered modules concurrently.
      Parameters:
      projectDir - the parent project directory
      modules - list of module relative paths

    • shutdownExecutor

      void shutdownExecutor(ExecutorService executor)
      Shuts down an ExecutorService safely without throwing from a finally block.

      Sonar java:S1143/java:S1163 - do not throw from finally blocks; preserve the thread interruption status.

      Parameters:
      executor - executor to stop (may be null)

    • isModuleDir

      public static boolean isModuleDir(ProjectLayout projectLayout, File dir)
      Checks whether dir is one of the project module directories.
      Parameters:
      projectLayout - layout containing module definitions
      dir - directory candidate
      Returns:
      true if dir is a module directory, otherwise false

    • match

      protected boolean match(File file, File projectDir)
      Determines whether the specified file should be included for processing based on exclusion rules, path matching patterns, and project structure.

      The matching logic proceeds as follows:

      1. If the file is null, returns false.
      2. If the file's absolute path contains any of the excluded directory names defined in ProjectLayout.EXCLUDE_DIRS, returns false.
      3. Computes the relative path from rootDir to file. If this is null, returns false.
      4. Uses pathMatcher to check if the relative path matches the configured pattern.
      5. If it does not match and path is not null, performs a secondary match that attempts to resolve the scan directory against the file and re-check from the project root.
      Parameters:
      file - the file to check for inclusion
      projectDir - the project directory of the project
      Returns:
      true if the file matches all criteria for processing; false otherwise

    • processParentFiles

      protected void processParentFiles(ProjectLayout projectLayout) throws IOException
      Processes non-module files and directories directly under rootDir.
      Parameters:
      projectLayout - project layout
      Throws:
      IOException - if file reading fails

    • processFile

      protected void processFile(ProjectLayout projectLayout, File file) throws IOException
      Extracts guidance for a file and, when present, performs provider processing.
      Parameters:
      projectLayout - project layout
      file - file to process
      Throws:
      IOException - if reading the file or provider execution fails

    • listFiles

      List<File> listFiles(File projectDir) throws IOException
      Recursively lists all files under a directory, excluding known build/tooling directories.
      Parameters:
      projectDir - directory to traverse
      Returns:
      list of files found
      Throws:
      IOException - if directory listing fails

    • shouldIncludeInListFiles

      boolean shouldIncludeInListFiles(File projectDir, File file)
      Determines whether an entry found in listFiles(File) should be included.

      Sonar java:S135 - reduce break/continue statements by isolating filtering.

      Parameters:
      projectDir - project directory being traversed
      file - candidate entry
      Returns:
      true when the entry should be included

    • shouldExcludePath

      public boolean shouldExcludePath(Path path)
      Determines whether a relative path should be excluded according to excludes.
      Parameters:
      path - project-relative path
      Returns:
      true when excluded

    • addMatchingFile

      void addMatchingFile(List<File> result, PathMatcher matcher, File projectDir, File file)
      Adds a file to the result when it is eligible for the requested pattern.
      Parameters:
      result - collection of matches
      matcher - optional path matcher
      projectDir - project root
      file - candidate file

    • isPathPattern

      static boolean isPathPattern(String pattern)
      Tests whether a scan pattern string is a glob: or regex: matcher.
      Parameters:
      pattern - scan directory argument
      Returns:
      true when the pattern uses a path-matcher prefix

    • getPatternPath

      static PathMatcher getPatternPath(String path)
      Returns a PathMatcher when the provided string is a path pattern.
      Parameters:
      path - pattern candidate
      Returns:
      matcher or null when path is not a pattern

    • processFolder

      public void processFolder(ProjectLayout projectLayout)
      Processes a project layout for documentation gathering.
      Specified by:
      processFolder in class ProjectProcessor
      Parameters:
      projectLayout - layout describing sources, tests, docs, and modules

    • listFiles

      List<File> listFiles(File projectDir, String pattern) throws IOException
      Finds all files/directories in the provided project folder that match a pattern.
      Parameters:
      projectDir - project root
      pattern - directory path, glob: matcher, or regex: matcher
      Returns:
      matching files/directories
      Throws:
      IOException - if directory traversal fails

    • pathDepth

      static int pathDepth(String path)
      Computes the depth of a path for sorting.
      Parameters:
      path - input path
      Returns:
      number of path segments

    • processProjectDir

      public void processProjectDir(ProjectLayout layout, String filePattern)
      Processes files in a project directory matching a provided pattern or directory.
      Parameters:
      layout - project layout
      filePattern - directory path, glob:, or regex: pattern

    • setThreads

      public void setThreads(int threads)
      Configures the number of threads to be used for multi-threaded module processing.
      Parameters:
      threads - the number of concurrent threads to use; must be a positive integer
      Throws:
      IllegalArgumentException - if the specified number of threads is less than or equal to zero

    • setNonRecursive

      public void setNonRecursive(boolean nonRecursive)
      Sets whether scanning is restricted to the current directory only.
      Parameters:
      nonRecursive - true to disable module recursion

    • getExcludes

      public String[] getExcludes()
      Returns the exclude patterns configured for this processor.
      Returns:
      exclude list

    • setExcludes

      public void setExcludes(String[] excludes)
      Sets exclude patterns or paths.

      Each entry may be:

      • a glob: or regex: matcher expression
      • an exact relative path (compared using Strings.CS)
      Parameters:
      excludes - exclude list

    • getRootDir

      public File getRootDir()
      Returns the root directory used as a base for relative paths.
      Returns:
      root directory

    • isNonRecursive

      public boolean isNonRecursive()
      Returns whether recursion into modules/subdirectories is disabled.
      Returns:
      true when non-recursive mode is enabled

    • getModuleThreadTimeoutMinutes

      public long getModuleThreadTimeoutMinutes()
      Returns the timeout (in minutes) to wait for module processing completion during shutdown.
      Returns:
      shutdown timeout in minutes

    • setModuleThreadTimeoutMinutes

      public void setModuleThreadTimeoutMinutes(long moduleThreadTimeoutMinutes)
      Sets the module processing shutdown timeout.
      Parameters:
      moduleThreadTimeoutMinutes - timeout in minutes; must be greater than 0
      Throws:
      IllegalArgumentException - if the timeout is not positive

    • setPath

      public void setPath(File path)
      Sets the scan directory that originated the current match operation.
      Parameters:
      path - scan directory

    • setPathMatcher

      public void setPathMatcher(PathMatcher pathMatcher)
      Sets the path matcher used to include only matching files.
      Parameters:
      pathMatcher - matcher (may be null to disable matching)

    • getPath

      public File getPath()
      Returns the scan directory used to derive match semantics.
      Returns:
      scan directory or null

    • getPathMatcher

      public PathMatcher getPathMatcher()
      Returns the matcher used to decide whether a file is included.
      Returns:
      matcher or null when matching is disabled

    • getConfigurator

      public MutableConfigurator getConfigurator()
      Returns the configuration source for this processor.
      Returns:
      configurator