Package dev.jcputney.elearning.parser.api

Interface FileAccess

All Known Implementing Classes:
CachedFileAccess, ClasspathFileAccess, LocalFileAccess, ResourceUtils.SafeFileAccess, 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 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).
      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 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 path is null