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 projectDir, Configurator configurator)
      Creates a new file processor.
      Parameters:
      projectDir - root directory used as a base for relative paths
      configurator - configuration source used by implementations

  • Method Details

    • scanDocuments

      public void scanDocuments(File basedir) throws IOException
      Scans documents in the given root directory and prepares inputs for documentation generation. This overload defaults the scan start directory to basedir.
      Parameters:
      basedir - root directory to scan
      Throws:
      IOException - if an error occurs reading files

    • 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 - 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 projectDir 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 scanDir 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 root directory of the project
      Returns:
      true if the file matches all criteria for processing; false otherwise

    • matchPath

      boolean matchPath(File projectDir, File file, String relativeProjectDir, String relativeScanDir)

    • processParentFiles

      protected void processParentFiles(ProjectLayout projectLayout) throws IOException
      Processes non-module files and directories directly under projectDir.
      Parameters:
      projectLayout - project layout
      Throws:
      FileNotFoundException - if the project layout cannot be created
      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

    • findFiles

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

    • shouldIncludeInFindFiles

      boolean shouldIncludeInFindFiles(File projectDir, File file)
      Determines whether an entry found in findFiles(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

    • findFiles

      List<File> findFiles(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

    • setDegreeOfConcurrency

      public void setDegreeOfConcurrency(int data)
      Enables or disables multi-threaded module processing.
      Parameters:
      data - true to enable, false to disable

    • 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 excludes configured for this processor.
      Returns:
      exclude list

    • setExcludes

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

      Each entry may be:

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

    • getProjectDir

      public File getProjectDir()
      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 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

    • setScanDir

      public void setScanDir(File scanDir)
      Sets the scan directory that originated the current match operation.
      Parameters:
      scanDir - 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)

    • getScanDir

      public File getScanDir()
      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 Configurator getConfigurator()
      Returns the configuration source for this processor.
      Returns:
      configurator