Interface ICommonFileSystem<FD>

Type Parameters:
FD - Type of the file descriptor, such as e.g. a string representing a file path.
All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
ISynchronizedFileSystem<FD>
All Known Implementing Classes:
EntityFileSystem
public interface ICommonFileSystem<FD> extends AutoCloseable
High-level interface for abstracting common file system operations. Implementations could use a real file system, a database or any other storage medium.
Since:
8.3.0
Author:
XIMA MEDIA GmbH

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    copy(FD source, FD target)
    Copies the file with the given source key to the target key.
    void
    delete(FD file)
    Deletes the file or directory with the given key.
    boolean
    exists(FD file)
    Checks whether this file system contains a file (or folder) with the given key.
    Instant
    getFileLastModifiedAt(FD file)
    Gets the last modified time of the file with the given key.
    String
    getFileLastModifiedBy(FD file)
    Gets the user who last modified the file with the given key.
    Iterable<FD>
    getFiles()
    Gets the keys of all existing files.
    FileSize
    getFileSize(FD file)
    Gets the size of the file with the given key.
    boolean
    hasPendingChanges(FD file)
    Checks whether the content of the file with the given key has been changed and is in a pending state, not yet persisted or synchronized with an external storage medium.
    boolean
    isOpen()
    Checks whether this file system is open.
    Iterable<FD>
    listFolder(FD folder)
    Gets the keys of all existing files within the given folder, non-recursively.
    Iterable<FD>
    listFolderRecursively(FD folder)
    Gets the keys of all existing files within the given folder, recursively.
    void
    makeFile(FD file)
    Creates a new file with no content.
    void
    makeFolder(FD fileKey)
    Creates a new folder with no content.
    InputStream
    openFileInput(FD file)
    Gets an input stream for the data of the file with the given key.
    InputStream
    openFileInputMarkable(FD file)
    Gets an input stream for the data of the file with the given key.
    OutputStream
    openFileOutput(FD file)
    Opens an output stream to the given file key.
    void
    refresh()
    If the implementation employs any kind of caching: discards all caches and refreshes the file system so that all entries represent the most up-to-date state.
    void
    refresh(Iterable<FD> files)
    If the implementation employs any kind of caching: discards all caches and refreshes the file system so that all given entries represent the most up-to-date state.
    Map<FD,FD>
    rename(FD source, FD target)
    Renames the file system entry with the given source key to the target key.
    <FileSystem>
    FileSystem
    unwrap(Class<? extends FileSystem> type)
    Unwraps this file system to the given type.

    Methods inherited from interface AutoCloseable

    close

  • Method Details

    • copy

      void copy(FD source, FD target) throws IOException
      Copies the file with the given source key to the target key. If the source key does not exist, this method does nothing. If the target key exists already, an IOException is thrown.

      If the source is a directory, all contents of the source must also be copied to the target.

      Parameters:
      source - The descriptor of the file to copy.
      target - The descriptor of the file to copy to.
      Throws:
      IOException - If an error occurs while copying the file data.

    • delete

      void delete(FD file) throws IOException
      Deletes the file or directory with the given key. If the file or directory does not exist, this method does nothing.
      Parameters:
      file - The file descriptor of the file to delete.
      Throws:
      IOException - If an error occurs while deleting the file.

    • exists

      boolean exists(FD file)
      Checks whether this file system contains a file (or folder) with the given key. Returns false if the file could not be checked.
      Parameters:
      file - The file descriptor.
      Returns:
      true if the file (or folder) exists, false otherwise.

    • getFileLastModifiedAt

      Instant getFileLastModifiedAt(FD file) throws IOException
      Gets the last modified time of the file with the given key. If the file does not exist, or if the last modified time is not available, Instant.EPOCH is returned.
      Parameters:
      file - The file descriptor.
      Returns:
      The last modified time of the file, or Instant.EPOCH if the file does not exist.
      Throws:
      IOException - If an error occurs while loading the last modified time.

    • getFileLastModifiedBy

      String getFileLastModifiedBy(FD file) throws IOException
      Gets the user who last modified the file with the given key. If the file does not exist, or if the last modified user is not available, the empty string is returned.
      Parameters:
      file - The key of the file.
      Returns:
      The user who last modified the file, or the empty string if the file does not exist.
      Throws:
      IOException - If an error occurs while loading the user who last modified the file.

    • getFileSize

      FileSize getFileSize(FD file) throws IOException
      Gets the size of the file with the given key. If the file does not exist, or if the size cannot be determined 0 is returned.
      Parameters:
      file - The file descriptor.
      Returns:
      The size of the file, or 0 if unavailable.
      Throws:
      IOException - If an error occurs while loading the file size.

    • getFiles

      Iterable<FD> getFiles()
      Gets the keys of all existing files.
      Returns:
      The keys of all existing files.

    • hasPendingChanges

      boolean hasPendingChanges(FD file)
      Checks whether the content of the file with the given key has been changed and is in a pending state, not yet persisted or synchronized with an external storage medium.
      Parameters:
      file - The file descriptor.
      Returns:
      true if the content has pending changes, false otherwise.

    • isOpen

      boolean isOpen()
      Checks whether this file system is open. If the file system is not open, no operations can be performed. See AutoCloseable.close().
      Returns:
      true if the file system is still open, false otherwise.

    • listFolder

      Iterable<FD> listFolder(FD folder) throws IOException
      Gets the keys of all existing files within the given folder, non-recursively. Only the files in the given folder are returned, not files in subfolders.

      The given folder is not included in the result.

      Parameters:
      folder - The key to start at.
      Returns:
      The keys of all existing files within the given folder.
      Throws:
      IOException - If an error occurs while listing the folder contents.

    • listFolderRecursively

      Iterable<FD> listFolderRecursively(FD folder) throws IOException
      Gets the keys of all existing files within the given folder, recursively. This is a recursive operation, so all files in all subfolders are included. Folder contents are returned in breadth-first order, i.e. all files in the same folder are returned before files in subfolders.

      The given folder is not included in the result.

      Parameters:
      folder - The file descriptor of the folder.
      Returns:
      The keys of all existing files within the given folder and subfolders.
      Throws:
      IOException - If an error occurs while listing the folder contents.

    • makeFile

      void makeFile(FD file) throws IOException
      Creates a new file with no content. Does nothing if the file already exists.
      Parameters:
      file - The file descriptor.
      Throws:
      IOException - If an error occurs while creating the file.

    • makeFolder

      void makeFolder(FD fileKey) throws IOException
      Creates a new folder with no content. Does nothing if the file already exists.
      Parameters:
      fileKey - The key of the folder.
      Throws:
      IOException - If an error occurs while creating the folder.

    • openFileInput

      InputStream openFileInput(FD file) throws IOException
      Gets an input stream for the data of the file with the given key. If the file does not exist, or if the file data is not available, an empty input stream is returned.

      No guarantees are made regarding the features of the input stream, other than data can be read from it.

      Parameters:
      file - The file descriptor.
      Returns:
      An input stream for the data of the file, or an empty stream if the file does not exist or the data is not available.
      Throws:
      IOException - If an error occurs while opening the file data from the temporary file.

    • openFileInputMarkable

      InputStream openFileInputMarkable(FD file) throws IOException
      Gets an input stream for the data of the file with the given key. If the file does not exist, or if the file data is not available, an empty input stream is returned.

      The returned input stream supports mark and reset operations.

      Parameters:
      file - The file descriptor.
      Returns:
      An input stream for the data of the file, or an empty stream if the file does not exist or the data is not available.
      Throws:
      IOException - If an error occurs while opening the file data from the temporary file.

    • openFileOutput

      OutputStream openFileOutput(FD file) throws IOException
      Opens an output stream to the given file key. If the file does not exist yet, it is created. If the file exists already, the content is overwritten.
      Parameters:
      file - The file descriptor.
      Returns:
      An output stream for writing the file data.
      Throws:
      IOException - If an error occurs while opening the file output stream.

    • refresh

      void refresh() throws IOException
      If the implementation employs any kind of caching: discards all caches and refreshes the file system so that all entries represent the most up-to-date state.
      Throws:
      IOException - If an error occurs while refreshing the file system.

    • refresh

      void refresh(Iterable<FD> files) throws IOException
      If the implementation employs any kind of caching: discards all caches and refreshes the file system so that all given entries represent the most up-to-date state. If a file is given, only that file is refreshed. If a folder is given, all files and folder in that folder are refreshed (recursively).
      Parameters:
      files - The files to refresh.
      Throws:
      IOException - If an error occurs while refreshing the file system.

    • rename

      Map<FD,FD> rename(FD source, FD target) throws IOException
      Renames the file system entry with the given source key to the target key. If the source key does not exist, this method does nothing.

      When source and target are directories, all contents of the source must also be moved to the target.

      Parameters:
      source - The descriptor of the file to rename.
      target - The descriptor of the file towards which to rename.
      Returns:
      Mapping from the old to the new files or directories. Includes the contents of directories if the source is a directory.
      Throws:
      IllegalArgumentException - If the target key exists already.
      IOException - If an error occurs while renaming the file.

    • unwrap

      <FileSystem> FileSystem unwrap(Class<? extends FileSystem> type)
      Unwraps this file system to the given type. If this file system is an instance of the given type, it is returned. Otherwise, potential wrappers are unwrapped until the given type is reached. If the file system cannot be unwrapped to the given type, null is returned.

      If multiple wrappers are present, the first one that can be unwrapped to the given type is returned.

      Type Parameters:
      FileSystem - The type of the desired file system.
      Parameters:
      type - The type to unwrap to.
      Returns:
      The unwrapped file system, or null if the file system cannot be unwrapped to the given type.