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
Abstract base implementation for processors that traverse project directories and perform work on their 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. Subclasses can override the protected processing hooks to supply their file-specific behavior.

  • Field Details

    • rootDir

      private File rootDir
      Root directory used to calculate project-relative paths during the current processing 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
      Number of worker threads used for module processing. A value greater than one enables concurrent module processing.

    • nonRecursive

      private boolean nonRecursive
      Indicates whether module discovery and recursive module processing are disabled for the current run.

    • pathMatcher

      private PathMatcher pathMatcher
      Optional matcher that limits file or module processing to matching paths.

    • excludes

      private String[] excludes
      Optional exact paths or path-pattern expressions excluded from traversal.

    • configurator

      private final MutableConfigurator configurator
      Layered, mutable configuration source supplied to processor implementations.

    • moduleThreadTimeoutMinutes

      private long moduleThreadTimeoutMinutes
      Maximum number of minutes to await module worker-pool termination before forcing shutdown.

  • Constructor Details

    • AbstractFileProcessor

      protected AbstractFileProcessor(File rootDir, Configurator configurator)
      Creates a new file processor.
      Parameters:
      rootDir - root directory used as a base for relative paths
      configurator - configuration source layered for use 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 or module to scan
      Throws:
      IOException - if a subclass encounters an error while reading or processing files
      IllegalStateException - if concurrent module processing fails or is interrupted

    • processModulesMultiThreaded

      void processModulesMultiThreaded(ProjectLayout projectLayout, List<String> modules)
      Processes all discovered modules concurrently.
      Parameters:
      projectLayout - layout for the parent project directory
      modules - relative paths of the modules to process
      Throws:
      IllegalStateException - if a module cannot be processed or the calling thread is interrupted while waiting for a module

    • 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 located in 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, ProjectLayout projectLayout)
      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 is excluded by the project layout, returns false.
      3. If no matcher is configured, includes only the explicitly configured scan path.
      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
      projectLayout - layout for the project containing the file
      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 a subclass encounters an error while processing parent files

    • processFile

      protected void processFile(ProjectLayout projectLayout, File file) throws IOException
      Processes one file in a project layout.
      Parameters:
      projectLayout - project layout
      file - file to process
      Throws:
      IOException - if a subclass cannot read or process the file

    • 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 a directory cannot be listed

    • 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) throws IOException
      Processes a project layout for documentation gathering.
      Specified by:
      processFolder in class ProjectProcessor
      Parameters:
      projectLayout - layout describing sources, tests, docs, and modules
      Throws:
      IllegalArgumentException - if project files cannot be listed or processed
      IOException

    • 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) throws IOException
      Processes files in a project directory matching a provided pattern or directory.
      Parameters:
      layout - project layout
      filePattern - directory path, glob:, or regex: pattern
      Throws:
      IOException - if matching files cannot be listed or processed

    • 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