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

    • GW_PROJECT_LAYOUT_PROP_PREFIX

      protected static final String GW_PROJECT_LAYOUT_PROP_PREFIX
      Prefix for project-layout properties exposed for template substitution.
      See Also:

  • 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

    • 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

    • 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

    • 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

    • 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

    • setDegreeOfConcurrency

      public void setDegreeOfConcurrency(int data)
      Sets the degree of concurrency for multi-threaded module processing.
      Parameters:
      data - number of concurrent threads to use

    • 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