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.

hasFile

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.

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

getFileHandle

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

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). This may be used to store data from a file in a
file (handle).

Parameters:

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

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). This may be used to store data from a file in a
file (handle).

Parameters:

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

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). This may be used to store data from a string or
other data structure.

Parameters:

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

hasFiles

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.