Module org.refcodes.filesystem
Package org.refcodes.filesystem

Interface FileSystem

All Superinterfaces:
org.refcodes.component.Component, org.refcodes.component.Destroyable
All Known Implementing Classes:
ChangeRootFileSystemDecorator, InMemoryFileSystem
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 aCause 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.