Package org.machanism.machai.project.layout

Class ProjectLayout

java.lang.Object
org.machanism.machai.project.layout.ProjectLayout
Direct Known Subclasses:
DefaultProjectLayout, GradleProjectLayout, JScriptProjectLayout, MavenProjectLayout, PythonProjectLayout
public abstract class ProjectLayout extends Object
Base abstraction for describing a project's conventional on-disk layout.

A ProjectLayout implementation translates build-tool conventions and/or build metadata into root-relative paths, such as source roots, test roots, documentation roots, and (optionally) module directories.

Implementations are expected to be configured with a project root via projectDir(File) prior to calling any accessors.

Root-relative paths

Paths returned from this API are typically expressed as root-relative strings using / as a separator. Callers should resolve them against getProjectDir() before accessing the filesystem.

Example

 
 java.io.File projectDir = new java.io.File("C:\\repo");
 ProjectLayout layout = new MavenProjectLayout().projectDir(projectDir);

 java.util.List<String> sources = layout.getSources();
Since:
0.0.2
Author:
Viktor Tovstyi

  • Field Details

    • NO_MODULES

      protected static final List<String> NO_MODULES
      Sentinel value indicating that the layout does not declare any modules.

      Subclasses may return this constant from getModules() to signal that the project structure is flat (non-parent) without allocating a new list instance.

    • logger

      private static org.slf4j.Logger logger
      Logger used for layout-wide diagnostic messages.

    • excludeDirs

      private List<String> excludeDirs
      Directory names that should be ignored when scanning projects.

    • tempDir

      private static String tempDir
      Cached path to Machai's temporary working directory.

    • projectDir

      private File projectDir
      Root directory configured for this layout.

  • Constructor Details

    • ProjectLayout

      public ProjectLayout()

  • Method Details

    • projectDir

      public ProjectLayout projectDir(File projectDir)
      Sets the project root directory used by this layout.
      Parameters:
      projectDir - the project root directory
      Returns:
      this instance for chaining

    • getProjectDir

      public File getProjectDir()
      Returns the configured project root directory.
      Returns:
      the project root directory

    • getModules

      @Nullable public List<String> getModules()
      Returns a list of module directories (or names) within this project.
      Returns:
      module directories, or null when the layout does not declare modules

    • getRelativePath

      public String getRelativePath(String basePath, File file)
      Computes a root-relative path for a file, based on the provided base path.
      Parameters:
      basePath - absolute path of the base directory
      file - target file
      Returns:
      the path of file relative to basePath

    • getSources

      public abstract Collection<String> getSources()
      Returns the root-relative source directories for production code.
      Returns:
      list of root-relative source directories

    • getDocuments

      public abstract Collection<String> getDocuments()
      Returns the root-relative documentation directories.
      Returns:
      list of root-relative documentation directories

    • getTests

      public abstract Collection<String> getTests()
      Returns the root-relative source directories for test code.
      Returns:
      list of root-relative test source directories

    • getRelativePath

      public static String getRelativePath(File dir, File file)
      Computes the relative path from the specified project directory to the target file. The result is not prefixed with ./.
      Parameters:
      dir - the base project directory
      file - the target file for which to compute the relative path
      Returns:
      the relative path string, or null if the target file is not within the project directory
      See Also:

    • getRelativePath

      public static String getRelativePath(File dir, File file, boolean addSingleDot)
      Computes the relative path from the specified project directory to the target file. Optionally, the result can be prefixed with ./ if addSingleDot is true.

      If the target file is the same as the project directory, returns .. If an absolute path is provided, it must be located within the project directory.

      Parameters:
      dir - the base project directory
      file - the target file for which to compute the relative path
      addSingleDot - if true, prefixes the result with ./ when appropriate
      Returns:
      the relative path string, or null if the target file is not within the project directory

    • listFiles

      public List<File> listFiles(File dir)
      Recursively lists all files under a directory, excluding known build/tooling directories.
      Parameters:
      dir - directory to traverse
      Returns:
      files found; never null

    • listDirectories

      public List<File> listDirectories(File projectDir)
      Recursively lists all directories, excluding known build/tooling directories.
      Parameters:
      projectDir - directory to traverse
      Returns:
      directories found; never null

    • getProjectName

      public String getProjectName()
      Returns a human-friendly project name, when available.
      Returns:
      the project name or null if unknown

    • getProjectId

      public String getProjectId()
      Returns a stable project identifier, when available.
      Returns:
      the project identifier or null if unknown

    • getProjectLayoutType

      public String getProjectLayoutType()
      Returns the layout type name (derived from the implementing class name).
      Returns:
      a short layout type name

    • getParentId

      public String getParentId()
      Returns the parent project identifier, when available.
      Returns:
      parent project identifier or null if unknown

    • isExcludedPath

      public boolean isExcludedPath(File file)
      Checks whether the specified file or directory path matches any of the configured exclusion patterns (glob templates or exact string matches).

      Exclusion patterns can be specified as standard glob expressions (e.g., "/**\/temp/**", "*.log") or exact paths/names. If a pattern does not start with "glob:", it is automatically treated as a glob pattern.

      Parameters:
      file - the File to check for exclusion; can be null
      Returns:
      true if the file matches any exclusion pattern; false otherwise

    • getTempDir

      public static String getTempDir()
      Returns the system temporary directory path, initializing it if necessary.

      If the temporary directory has not been set, this method retrieves the value of the java.io.tmpdir system property, logs the initialization, and caches the result for future calls.

      Returns:
      the absolute path to the system temporary directory

    • getExcludeDirs

      public List<String> getExcludeDirs()
      Returns the mutable list of directory exclusion patterns used by this layout's directory-scanning operations.

      Patterns are interpreted by isExcludedPath(File). Callers may add layout-specific patterns to the returned list.

      Returns:
      the configured exclusion patterns

    • setExcludeDirs

      public void setExcludeDirs(List<String> excludeDirs)
      Replaces the directory exclusion patterns used by this layout.
      Parameters:
      excludeDirs - exclusion patterns to use during directory scanning