Package org.refcodes.filesystem

Interface FileSystem

  • All Superinterfaces:
    org.refcodes.component.Component, org.refcodes.component.Destroyable
    All Known Implementing Classes:
    ChangeRootFileSystemWrapperImpl, InMemoryFileSystemImpl

    public interface FileSystem
extends org.refcodes.component.Component
    A file system represents an abstraction for any "physical" storage medium where file (handles) can be stored and retrieved. The file (handles) are structured in a hierarchy similar to a file system's hierarchy with folders and files. The hierarchy may be completely virtual (the underlying system just knows of "keys" and directories are simulated by key naming conventions), so the underlying physical file system might be an FTP server or an in-memory Map (with virtual files and folders) or a real file system with a real directory and file hierarchy. The file system only contains file (handle)s, any construct such as a "directory" does not exist from the file system's point of view and therefore cannot be created or removed explicitly. Them are created or removed implicitly when file (handles) are created or removed. An implementation for, lets say, a file system, should take care to remove physical folders from the file system when removing a file (handle) (the corresponding file from the file system's folder) in case the folder from which the file (handle) (file) was removed ends up empty! In turn, when creating a file (handle), the corresponding directory structure must be created in case we have a file system with a "file system nature". File (handles) are never instantiated directly, them are retrieved from the file system as them can be implementation specific. A specific file (handle) instance therefore is always attached to a specific instance of a file system. Using file (handle)s interchangeably between tow different file system instances will (usually) fail. A file system and the file (handle)s are a self contained systems similar to the entities of an O/R mapper being attached to a specific persistence provider. Whenever an operation returns a file (handle), this file (handle) is to be considered the actual working copy and to be used in favor to a previous data file (handle) identifying the same data. The returned file (handle) will provide updated information. A file (handle) in the file system is identified by a unique key, which in turn consists of a path and a name. The path and the name are concatenated by a path separator, usually the slash "/". The path itself might be composed with path separators. Having this, a "file system nature" file system can map the file (handle)s to files in a directory hierarchy on the file system. Any path or key being provided is to be normalized by an implementation of the file system (using the FileSystemUtility) by removing any trailing path separators. Illegal paths will cause an IllegalPathException, IllegalNameException or an IllegalKeyException, i.e. path which do not start with a path separator or have two or more subsequent path separators in then or any other illegal characters.

    • Nested Class Summary

      • Nested classes/interfaces inherited from interface org.refcodes.component.Destroyable

        org.refcodes.component.Destroyable.DestroyAutomaton

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static char PATH_DELIMITER
      The default path delimiter to be used by all implementations if this file system to ensure interoperability.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      FileHandle createFile​(java.lang.String aKey)
      Creates a file (handle) with the given key.
      FileHandle createFile​(java.lang.String aPath, java.lang.String aName)
      Creates a file (handle) with the given path and name.
      void deleteFile​(FileHandle aFileHandle)
      Deletes a file (handle) from the file system.
      java.io.InputStream fromFile​(FileHandle aFromFileHandle)
      An input stream is being provided from which the data of the file (handle) may be read.
      void fromFile​(FileHandle aFromFileHandle, java.io.File aToFile)
      The data contained in the given file (handle) is written to the provided file.
      void fromFile​(FileHandle aFromFileHandle, java.io.OutputStream aOutputStream)
      The data contained in the given file (handle) is written to the provided output stream.
      FileHandle getFileHandle​(java.lang.String aKey)
      Gets a file (handle) with the given key from the file system.
      FileHandle getFileHandle​(java.lang.String aPath, java.lang.String aName)
      Gets a file (handle) with the given path and name from the file system.
      java.util.List<FileHandle> getFileHandles​(java.lang.String aPath, boolean isRecursively)
      With the behavior of the hasFiles(String, boolean) method, all file (handle)s found for the path are returned.
      boolean hasFile​(java.lang.String aKey)
      Tests whether the file system knows a file (handle) with the given key.
      boolean hasFile​(java.lang.String aPath, java.lang.String aName)
      Tests whether the file system knows a file (handle) with the given path and name.
      boolean hasFile​(FileHandle aFileHandle)
      Returns true in case the given file (handle) exists.
      boolean hasFiles​(java.lang.String aPath, boolean isRecursively)
      Determines whether there is any file (handle)s found for the given path.
      FileHandle moveFile​(FileHandle aFileHandle, java.lang.String aNewKey)
      Renames the file (handle), it will be accessible via the provided key.
      FileHandle renameFile​(FileHandle aFileHandle, java.lang.String aNewName)
      Renames the file (handle), the name part of the key will be renamed to the new name.
      java.io.OutputStream toFile​(FileHandle aToFileHandle)
      Returns an output stream which may be used to write (or append, in case data did already exist for the file system) data to a file (handle).
      void toFile​(FileHandle aToFileHandle, byte[] aBuffer)
      Data provided by the given buffer is written to the file (handle) (or appended to the file (handle)'s data in case the file (handle) did already contain data).
      void toFile​(FileHandle aToFileHandle, java.io.File aFromFile)
      Data provided by the given input stream is written to the file (handle) (or appended to the file (handle)'s data in case the file (handle) did already contain data).
      void toFile​(FileHandle aToFileHandle, java.io.InputStream aInputStream)
      Data provided by the given input stream is written to the file (handle) (or appended to the file (handle)'s data in case the file (handle) did already contain data).

      • Methods inherited from interface org.refcodes.component.Destroyable

        destroy

    • Field Detail

      • PATH_DELIMITER

        static final char PATH_DELIMITER
        The default path delimiter to be used by all implementations if this file system to ensure interoperability.

    • Method Detail

      • hasFile

        boolean hasFile​(java.lang.String aKey)
         throws IllegalKeyException,
                NoListAccessException,
                UnknownFileSystemException,
                java.io.IOException
        Tests whether the file system knows a file (handle) with the given key.
        Parameters:
        aKey - The key which to test if there is a file (handle).
        Returns:
        True in case there is a file (handle) with the given key exists.
        Throws:
        IllegalKeyException - in case the path was not a valid path.
        NoListAccessException - in case listing the content in the file system was denied.
        UnknownFileSystemException - in case the "underlying" (physical) file system is not known (may not exist any more), i.e. it may have been removed after the file system instance has been created.
        java.io.IOException - in case an I/O related problem occurred while accessing the file (handle).

      • hasFile

        boolean hasFile​(java.lang.String aPath,
                java.lang.String aName)
         throws IllegalPathException,
                IllegalNameException,
                NoListAccessException,
                UnknownFileSystemException,
                java.io.IOException
        Tests whether the file system knows a file (handle) with the given path and name. Caution, path and name are not just concatenated with a path separator in between to get the key: The name must not contain any path separator! In case of a file system implementation of the file system ("file system nature") the name must actually represent the filename of the file representing the file (handle).
        Parameters:
        aPath - The path part of the key for which to test if there is a file (handle).
        aName - The name part of the key for which to test if there is a file (handle).
        Returns:
        True in case there is a file (handle) with the given path and name exists.
        Throws:
        IllegalPathException - in case the path was not a valid path.
        IllegalNameException - in case the name was not a valid path.
        NoListAccessException - in case listing the content in the file syste was denied.
        UnknownFileSystemException - in case the "underlying" (physical) file system is not known (may not exist any more), i.e. it may have been removed after the file system instance has been created.
        java.io.IOException - in case an I/O related problem occurred while accessing the file (handle)

      • hasFile

        boolean hasFile​(FileHandle aFileHandle)
         throws NoListAccessException,
                UnknownFileSystemException,
                java.io.IOException,
                IllegalFileHandleException
        Returns true in case the given file (handle) exists.
        Parameters:
        aFileHandle - The file (handle) which's existence is to be tested.
        Returns:
        True in case the file (handle) exists, else false is returned.
        Throws:
        NoListAccessException - in case listing the content in the file system was denied.
        UnknownFileSystemException - in case the "underlying" (physical) file system is not known (may not exist any more), i.e. it may have been removed after the file system instance has been created.
        java.io.IOException - in case an I/O related problem occurred while accessing the file (handle)
        IllegalFileHandleException - in case the file handle with name and path is not valid, i.e. the name contains a path separator.

      • createFile

        FileHandle createFile​(java.lang.String aPath,
                      java.lang.String aName)
               throws FileAlreadyExistsException,
                      NoCreateAccessException,
                      IllegalNameException,
                      IllegalPathException,
                      UnknownFileSystemException,
                      java.io.IOException,
                      NoListAccessException
        Creates a file (handle) with the given path and name. Caution, path and name are not just concatenated with a path separator in between to get the key: The name must not contain any path separator! In case of a file system implementation of the file system ("file system alternative") the name will actually represent the filename of the file representing the file handle.
        Parameters:
        aPath - The path part of the key for which to create the file (handle).
        aName - The name part of the key for which to create the file (handle).
        Returns:
        The newly created file (handle).
        Throws:
        FileAlreadyExistsException - in case a file (handle) with the given key (path and name) already exists.
        NoCreateAccessException - in case create access to the file system was denied.
        IllegalNameException - in case the name was not a valid path.
        IllegalPathException - in case the path was not a valid path.
        UnknownFileSystemException - in case the "underlying" (physical) file system is not known (may not exist any more), i.e. it may have been removed after the file system instance has been created.
        java.io.IOException - in case an I/O related problem occurred while accessing the file (handle)
        NoListAccessException - in case listing the content in the file system was denied.

      • getFileHandle

        FileHandle getFileHandle​(java.lang.String aKey)
                  throws NoListAccessException,
                         IllegalKeyException,
                         UnknownFileSystemException,
                         java.io.IOException,
                         UnknownKeyException
        Gets a file (handle) with the given key from the file system.
        Parameters:
        aKey - The key for which to retrieve the file (handle).
        Returns:
        The retrieved file (handle).
        Throws:
        NoListAccessException - in case listing the content in the file system was denied.
        IllegalKeyException - in case the key with name and path is not valid, i.e. the name contains a path separator.
        UnknownFileSystemException - in case the "underlying" (physical) file system is not known (may not exist any more), i.e. it may have been removed after the file system instance has been created.
        java.io.IOException - in case an I/O related problem occurred while accessing the file (handle)
        UnknownKeyException - in case the given key (path and name) does not exist in the file system.

      • getFileHandle

        FileHandle getFileHandle​(java.lang.String aPath,
                         java.lang.String aName)
                  throws NoListAccessException,
                         IllegalNameException,
                         IllegalPathException,
                         UnknownFileSystemException,
                         java.io.IOException,
                         UnknownKeyException
        Gets a file (handle) with the given path and name from the file system. Caution, path and name are not just concatenated with a path separator in between to get the key: The name must not contain any path separator! In case of a file system implementation of the file system ("file system nature") the name will actually represent the filename of the file representing the file (handle).
        Parameters:
        aPath - The path part of the key for which to retrieve the file (handle).
        aName - The name part of the key for which to retrieve the file (handle).
        Returns:
        The retrieved file (handle).
        Throws:
        NoListAccessException - in case listing the content in the file system was denied.
        IllegalNameException - in case the name was not a valid path.
        IllegalPathException - in case the path was not a valid path.
        UnknownFileSystemException - in case the "underlying" (physical) file system is not known (may not exist any more), i.e. it may have been removed after the file system instance has been created.
        java.io.IOException - in case an I/O related problem occurred while accessing the file (handle)
        UnknownKeyException - in case the given key (path and name) does not exist in the file system.

      • hasFiles

        boolean hasFiles​(java.lang.String aPath,
                 boolean isRecursively)
          throws NoListAccessException,
                 IllegalPathException,
                 UnknownFileSystemException,
                 java.io.IOException
        Determines whether there is any file (handle)s found for the given path. In case the recursive flag is set, then the specified path and all children of that path (separated by the path separator) are examined, else exactly the specified path is examined. Speaking of a set recursive flag, it is merely checked whether the given path is part of any key of the file (handle)s stored in the file system by taking the path separators into account. I.e. the given path must match a key from the beginning till the end of the path and the key must either continue from then on with a path separator as next character or must end there (be equal to the path). I.e. matches in between a key where the next position of the key does not contain a path separator are ignored. Example: A given path is "/a/bc/def", a given key is "a/bc/defg", the path does not match the key, although the path is contained in the key! A given path is "/a/bc/def", a given key is "a/bc/def/g", the path does match the key as the key continues the path with a path separator "/".
        Parameters:
        aPath - The path where to look whether there are file (handle)s or not.
        isRecursively - When true all children of that path are examined as well.
        Returns:
        True in case file (handle)s were found.
        Throws:
        NoListAccessException - in case listing the content in the file system was denied.
        IllegalPathException - in case the path was not a valid path.
        UnknownFileSystemException - in case the "underlying" (physical) file system is not known (may not exist any more), i.e. it may have been removed after the file system instance has been created.
        java.io.IOException - in case an I/O related problem occurred while accessing the file (handle)