Package dev.jcputney.elearning.parser.api

Interface FileAccess

All Known Implementing Classes:
AbstractArchiveFileAccess, 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

    • 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).

      IMPORTANT CONTRACT: All returned paths MUST be relative to getRootPath(). For example, if rootPath="module-root" and storage contains "module-root/page.html", this method must return ["page.html"], NOT ["module-root/page.html"].

      The fullPath(String) method will prepend the root path when needed for internal storage access.

      Parameters:
      directoryPath - The directory to list files from (guaranteed to be non-null).
      Returns:
      A list of file paths relative to rootPath.
      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 storage path for the given relative or absolute path.

      IMPORTANT: This method is for internal use by FileAccess implementations only. External callers should never need to call this method.

      Implementations use this to convert caller-provided relative paths into internal storage paths. For example, when a caller requests "page.html" and the rootPath is "module-root", this method returns "module-root/page.html" for storage access.

      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.
      Parameters:
      path - The relative or absolute path for which the full path is to be generated.
      Returns:
      The constructed full storage 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.

      IMPORTANT CONTRACT: All returned paths MUST be relative to getRootPath(). See listFilesInternal(String) for details on the path format requirements.

      Returns:
      List of all file paths relative to rootPath
      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