org.refcodes.component.Component
, org.refcodes.component.Destroyable
ChangeRootFileSystemWrapperImpl
, InMemoryFileSystemImpl
public interface FileSystem
extends org.refcodes.component.Component
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.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.
|
Modifier and Type | Method | Description |
---|---|---|
FileHandle |
createFile(String aKey) |
Creates a file (handle) with the given key.
|
FileHandle |
createFile(String aPath,
String aName) |
Creates a file (handle) with the given path and name.
|
void |
deleteFile(FileHandle aFileHandle) |
Deletes a file (handle) from the file system.
|
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,
File aToFile) |
The data contained in the given file (handle) is written to the provided
file.
|
void |
fromFile(FileHandle aFromFileHandle,
OutputStream aOutputStream) |
The data contained in the given file (handle) is written to the provided
output stream.
|
FileHandle |
getFileHandle(String aKey) |
Gets a file (handle) with the given key from the file system.
|
FileHandle |
getFileHandle(String aPath,
String aName) |
Gets a file (handle) with the given path and name from the file system.
|
List<FileHandle> |
getFileHandles(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(String aKey) |
Tests whether the file system knows a file (handle) with the given key.
|
boolean |
hasFile(String aPath,
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(String aPath,
boolean isRecursively) |
Determines whether there is any file (handle)s found for the given path.
|
FileHandle |
moveFile(FileHandle aFileHandle,
String aNewKey) |
Renames the file (handle), it will be accessible via the provided key.
|
FileHandle |
renameFile(FileHandle aFileHandle,
String aNewName) |
Renames the file (handle), the name part of the key will be renamed to
the new name.
|
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,
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,
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).
|
static final char PATH_DELIMITER
boolean hasFile(String aKey) throws IllegalKeyException, NoListAccessException, UnknownFileSystemException, IOException
aKey
- The key which to test if there is a file (handle).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.IOException
- in case an I/O related problem occurred while
accessing the file (handle).boolean hasFile(String aPath, String aName) throws IllegalPathException, IllegalNameException, NoListAccessException, UnknownFileSystemException, IOException
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).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.IOException
- in case an I/O related problem occurred while
accessing the file (handle)boolean hasFile(FileHandle aFileHandle) throws NoListAccessException, UnknownFileSystemException, IOException, IllegalFileHandleException
aFileHandle
- The file (handle) which's existence is to be tested.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.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.FileHandle createFile(String aKey) throws FileAlreadyExistsException, NoCreateAccessException, IllegalKeyException, UnknownFileSystemException, IOException, NoListAccessException
aKey
- The key for which to create the file (handle).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.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.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.FileHandle createFile(String aPath, String aName) throws FileAlreadyExistsException, NoCreateAccessException, IllegalNameException, IllegalPathException, UnknownFileSystemException, IOException, NoListAccessException
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).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.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.FileHandle getFileHandle(String aKey) throws NoListAccessException, IllegalKeyException, UnknownFileSystemException, IOException, UnknownKeyException
aKey
- The key for which to retrieve the file (handle).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.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.FileHandle getFileHandle(String aPath, String aName) throws NoListAccessException, IllegalNameException, IllegalPathException, UnknownFileSystemException, IOException, UnknownKeyException
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).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.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.void fromFile(FileHandle aFromFileHandle, OutputStream aOutputStream) throws ConcurrentAccessException, UnknownFileException, NoReadAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileHandleException
aFromFileHandle
- The file (handle) which is to be written to the
output stream.aOutputStream
- The stream to which to write.ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.UnknownFileException
- in case none such file (handle) was found in
the file system.NoReadAccessException
- in case read access to 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.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.IllegalFileHandleException
- in case the file handle with name and
path is not valid, i.e. the name contains a path separator.void toFile(FileHandle aToFileHandle, InputStream aInputStream) throws ConcurrentAccessException, UnknownFileException, NoWriteAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileHandleException
aToFileHandle
- The file (handle) to which data is to be written.aInputStream
- The input stream from which to read the data which is
to be written to the file (handle).ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.UnknownFileException
- in case none such file (handle) was found in
the file system.NoWriteAccessException
- in case write access to 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.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.IllegalFileHandleException
- in case the file handle with name and
path is not valid, i.e. the name contains a path separator.InputStream fromFile(FileHandle aFromFileHandle) throws ConcurrentAccessException, UnknownFileException, UnknownFileException, NoReadAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileHandleException
aFromFileHandle
- The file (handle) for which to get the input
stream.ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.UnknownFileException
- in case none such file (handle) was found in
the file system.UnknownFileException
- in case none such file (handle) was found in
the file system.NoReadAccessException
- in case read access to 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.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.IllegalFileHandleException
- in case the file handle with name and
path is not valid, i.e. the name contains a path separator.OutputStream toFile(FileHandle aToFileHandle) throws ConcurrentAccessException, UnknownFileException, NoWriteAccessException, UnknownFileSystemException, IOException, IllegalFileHandleException
aToFileHandle
- The file (handle) to which to write data.ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.UnknownFileException
- in case none such file (handle) was found in
the file system.NoWriteAccessException
- in case write access to 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.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.void fromFile(FileHandle aFromFileHandle, File aToFile) throws ConcurrentAccessException, UnknownFileException, NoReadAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileHandleException
aFromFileHandle
- The file (handle) which is to be written to the
output stream.aToFile
- The file to which the data is to be written.ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.UnknownFileException
- in case none such file (handle) was found in
the file system.NoReadAccessException
- in case read access to 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.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.IllegalFileHandleException
- in case the file handle with name and
path is not valid, i.e. the name contains a path separator.void toFile(FileHandle aToFileHandle, File aFromFile) throws ConcurrentAccessException, UnknownFileException, NoWriteAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileHandleException
aToFileHandle
- The file (handle) to which data is to be written.aFromFile
- The file from which to read the data which is to be
written to the file (handle).ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.UnknownFileException
- in case none such file (handle) was found in
the file system.NoWriteAccessException
- in case write access to 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.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.IllegalFileHandleException
- in case the file handle with name and
path is not valid, i.e. the name contains a path separator.void toFile(FileHandle aToFileHandle, byte[] aBuffer) throws ConcurrentAccessException, UnknownFileException, NoWriteAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileHandleException
aToFileHandle
- The file (handle) to which data is to be written.aBuffer
- The buffer from which to read the data which is to be
written to the file (handle).ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.UnknownFileException
- in case none such file (handle) was found in
the file system.NoWriteAccessException
- in case write access to 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.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.IllegalFileHandleException
- in case the file handle with name and
path is not valid, i.e. the name contains a path separator.FileHandle renameFile(FileHandle aFileHandle, String aNewName) throws UnknownFileException, ConcurrentAccessException, FileAlreadyExistsException, NoCreateAccessException, NoDeleteAccessException, IllegalNameException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileHandleException
aFileHandle
- The file (handle) to be renamed.aNewName
- The new name of the file (handle).UnknownFileException
- in case none such file (handle) was found in
the file system.ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.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.NoDeleteAccessException
- in case create access to the file system
was denied.IllegalNameException
- in case the name 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.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.IllegalFileHandleException
- in case the file handle with name and
path is not valid, i.e. the name contains a path separator.FileHandle moveFile(FileHandle aFileHandle, String aNewKey) throws UnknownFileException, ConcurrentAccessException, FileAlreadyExistsException, NoCreateAccessException, NoDeleteAccessException, IllegalKeyException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileHandleException
aFileHandle
- The file (handle) to be renamed.aNewKey
- The new key (path and name) of the file (handle).UnknownFileException
- in case none such file (handle) was found in
the file system.ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.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.NoDeleteAccessException
- in case create access to 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.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.IllegalFileHandleException
- in case the file handle with name and
path is not valid, i.e. the name contains a path separator.void deleteFile(FileHandle aFileHandle) throws ConcurrentAccessException, UnknownFileException, NoDeleteAccessException, UnknownFileSystemException, IOException, NoListAccessException, IllegalFileHandleException
aFileHandle
- The file (handle) to be deleted.ConcurrentAccessException
- in case the file (handle) is
concurrently read, modified or deleted.UnknownFileException
- in case none such file (handle) was found in
the file system.NoDeleteAccessException
- in case create access to 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.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.IllegalFileHandleException
- in case the file handle with name and
path is not valid, i.e. the name contains a path separator.boolean hasFiles(String aPath, boolean isRecursively) throws NoListAccessException, IllegalPathException, UnknownFileSystemException, IOException
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.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.IOException
- in case an I/O related problem occurred while
accessing the file (handle)List<FileHandle> getFileHandles(String aPath, boolean isRecursively) throws NoListAccessException, UnknownPathException, IllegalPathException, UnknownFileSystemException, IOException
hasFiles(String, boolean)
method, all
file (handle)s found for the path are returned. Especially the recursive
flag is described in the method hasFiles(String, boolean)
.aPath
- The path where to search for the file (handle)s.isRecursively
- the is recursivelyNoListAccessException
- in case listing the content in the file
system was denied.UnknownPathException
- in case the given path did not exist in the
file system.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.IOException
- in case an I/O related problem occurred while
accessing the file (handle)Copyright © 2021. All rights reserved.