Package dev.jcputney.elearning.parser.api

Interface FileAccess

All Known Implementing Classes:
AbstractS3FileAccess, CachedFileAccess, ClasspathFileAccess, InMemoryFileAccess, LocalFileAccess, S3FileAccessV1, S3FileAccessV2, ZipFileAccess
public interface FileAccess
An interface for accessing files within a package or directory. This interface is a core component of the module parser architecture, providing a unified way to access files regardless of their storage mechanism (local file system, ZIP archive, cloud storage, etc.).

Implementations of this interface should provide methods for:

  • Checking if a file exists
  • Listing files within a directory
  • Retrieving file contents as an InputStream

An implementation of this interface should be provided to parsers for reading files within a module package. The default implementation is the LocalFileAccess class, but other implementations are available for different storage mechanisms:

  • ZipFileAccess - For accessing files in ZIP archives
  • S3FileAccess implementations - For accessing files in AWS S3 buckets

This interface follows the Strategy pattern, allowing different file access strategies to be interchanged without affecting the parsers that use them.

  • Method Details

    • getRootPath

      String getRootPath()
      Retrieves the root path used for file access.
      Returns:
      The root path used for file access.

    • fileExists

      default boolean fileExists(String path)
      Checks if a file exists at the given path.
      Parameters:
      path - The path to check.
      Returns:
      True if the file exists, false otherwise.
      Throws:
      IllegalArgumentException - if a path is null

    • fileExistsInternal

      boolean fileExistsInternal(String path)
      Internal method to check if a file exists at the given path. This method is called by the default implementation of fileExists(String).
      Parameters:
      path - The path to check (guaranteed to be non-null).
      Returns:
      True if the file exists, false otherwise.

    • listFiles

      default List<String> listFiles(String directoryPath) throws IOException
      Lists all files within a specified directory path.
      Parameters:
      directoryPath - The directory to list files from.
      Returns:
      A list of file paths within the directory.
      Throws:
      IOException - if there's an error accessing the directory or listing its contents.
      IllegalArgumentException - if directoryPath is null

    • checkForRootPath

      default boolean checkForRootPath(Set<String> topLevelDirs, String entryName)
      Checks if a file entry represents a root-level directory or if multiple top-level directories are present in the provided set.
      Parameters:
      topLevelDirs - A set of strings representing the top-level directories encountered so far. This set is modified by the method to add new entries if applicable.
      entryName - The name of the file entry to evaluate, potentially containing a directory path.
      Returns:
      True if the file entry is at the root level or if more than one top-level directory is present; false otherwise.

    • listFilesInternal

      List<String> listFilesInternal(String directoryPath) throws IOException
      Internal method to list all files within a specified directory path. This method is called by the default implementation of listFiles(String).
      Parameters:
      directoryPath - The directory to list files from (guaranteed to be non-null).
      Returns:
      A list of file paths within the directory.
      Throws:
      IOException - if there's an error accessing the directory or listing its contents.

    • getFileContents

      default InputStream getFileContents(String path) throws IOException
      Retrieves the contents of a file as an InputStream.
      Parameters:
      path - The path to retrieve contents from.
      Returns:
      An InputStream of the file contents.
      Throws:
      IOException - if the file can't be read.
      IllegalArgumentException - if a path is null

    • getFileContentsInternal

      InputStream getFileContentsInternal(String path) throws IOException
      Internal method to retrieve the contents of a file as an InputStream. This method is called by the default implementation of getFileContents(String).
      Parameters:
      path - The path to retrieve contents from (guaranteed to be non-null).
      Returns:
      An InputStream of the file contents.
      Throws:
      IOException - if the file can't be read.

    • fullPath

      default String fullPath(String path)
      Constructs the full path for the given relative or absolute path.

      This method handles path normalization according to the following rules:

      • If the path starts with a forward slash ("/"), it is treated as an absolute path and the leading "/" is removed.
      • Otherwise, the path is treated as relative and the rootPath is prefixed to form the full path.
      • If rootPath is empty, the relative path is returned as-is without any prefix.

      This method is used internally by implementations to normalize paths before accessing files.

      Parameters:
      path - The relative or absolute path for which the full path is to be generated.
      Returns:
      The constructed full path as a string.
      Throws:
      IllegalArgumentException - if a path is null

    • fileExistsBatch

      default Map<String,Boolean> fileExistsBatch(List<String> paths)
      Checks if multiple files exist in a batch operation.

      Default implementation calls fileExists() for each path individually. Implementations that support batch operations (like S3) should override this method to provide more efficient batch checking.

      Parameters:
      paths - List of file paths to check
      Returns:
      Map where keys are the file paths and values indicate whether the file exists
      Throws:
      IllegalArgumentException - if paths is null or contains null elements

    • prefetchCommonFiles

      default void prefetchCommonFiles()
      Prefetches common module files for faster subsequent access.

      The default implementation does nothing. Implementations that support caching (like S3) may override this to preload commonly accessed files.

    • getAllFiles

      default List<String> getAllFiles() throws IOException
      Gets a list of all files in the module.

      This method should return a cached list of all files available in the module. Implementations should scan the module once and cache the results for efficiency.

      Returns:
      List of all file paths in the module
      Throws:
      IOException - if there's an error accessing the module contents

    • clearCaches

      default void clearCaches()
      Clears any internal caches maintained by this FileAccess instance.

      This method should be called when the underlying storage might have changed or when memory needs to be freed. Implementations that maintain caches should override this method to clear their specific caches.

    • getTotalSize

      default long getTotalSize() throws IOException
      Gets the total size of all files in the module.

      This method calculates the sum of all file sizes in the module. Implementations that maintain file size caches can provide efficient calculation of the total module size.

      Returns:
      Total size of all files in bytes
      Throws:
      IOException - if there's an error accessing file sizes