Table of Contents
Well, what is a file, anyway? The answer is, of course, it depends. It depends on what you intend it to do. Sometimes a file is just a container of binary data that a client can read from, and sometimes it is a container of data with a unique identity that can be manipulated and moved around in the context of a file system.
EntityFS supports several different ways of viewing files and directories, all depending on what the client intends to do with them. This chapter describes the simple, low-level file and directory interfaces, Chapter 4, File systems describes what a file system is in EntityFS and Chapter 5, Entities describes what it means when a file or a directory is an entity.
Clients are encouraged to take the simplest possible view on the objects that they use. If a client just wants to read data from a file, it should use a ReadableFile instead of the full file entity (EFile). This makes mocking and testing much easier.
The sections below contain a walkthrough through the simple low-level interfaces for files and directories. Graphical inheritance charts are in Inheritance chart for EFile, Inheritance chart for Directory and Inheritance chart for all entity objcets.
Implemented by: Directory, EFile
Lockable is a marker interface that identifies the implementing object as being capable of locking for exclusive access by a thread or a process somehow.
Entity locking is described in Chapter 7, Locking and multi-threaded access.
Implements: Lockable.
Implemented by: Directory, EFile
ReadLockable gives the implementing object the capability of being locked for exclusive read access by a thread, several reading threads or a process. It is up to the implementing object to decide whether to actually support locking and, if so, the locking semantics to use.
Entity locking is described in Chapter 7, Locking and multi-threaded access.
Implements: Lockable.
Implemented by: Directory, EFile
WriteLockable gives the implementing object the capability of being locked for exclusive write access by a thread or a process. It is up to the implementing object to decide whether to actually support locking and, if so, the locking semantics to use.
Entity locking is described in Chapter 7, Locking and multi-threaded access.
Implements: Lockable, ReadLockable, WriteLockable.
Implemented by: Directory, EFile
ReadWriteLockable combines the ReadLockable and WriteLockable interfaces.
Implements: Lockable, ReadLockable.
Implemented by: Directory, EFile
Named is implemented by objects that has a name that can be read, such as a file name.
Implements: Lockable, WriteLockable.
Implemented by: Directory, EFile
Deletable is implemented by objects that can be deleted.
Implements: Lockable, ReadLockable.
Implemented by: EFile
ReadableFile defines a file that can be repeatedly opened for read only access and queried for its size. It is ReadLockable, so an implementing object may be able to be locked for exclusive read access, if it chooses to implement that.
In many ways, it is often better to use a ReadableFile as a method argument instead of, as is customarily done in Java libraries today, an InputStream. The reasons for that are explained in the Introduction section of the Architecture overview.
Table 3.1. Important ReadableFile implementations
Class | Description |
---|---|
ByteArrayReadableFile | A file that reads data from a byte array. |
CharSequenceReadableFile | A file that reads data from a CharSequence
(such as a String ). |
GZipReadableFile | A file containing data compressed with the gzip algorithm. The data is transparently decompressed when the file is read. |
Table 3.2. ReadableFile adapters
Class | Description |
---|---|
FileReadableFile | Adapts a File to the NamedReadableFile interface. |
NamedReadableFileAdapter | Adapts a ReadableFile to the NamedReadableFile interface. |
ReadWritableFileAdapter | Adapts a File to the ReadWritableFile interface. |
See also NamedReadableFile.
Implements: Lockable, Named, ReadableFile, ReadLockable.
Implemented by: EFile
The NamedReadableFile is a ReadableFile that has a name.
Table 3.3. Important NamedReadableFile implementations
Class | Description |
---|---|
ClasspathNamedReadableFile | A file that reads data from a resource on the classpath. |
ManualNamedReadableFile | A file that reads its data from a byte array or a
CharSequence (such as a
String ). |
UrlReadableFile | A file that reads its data from the target of a URL, such as a hyperlink. |
Table 3.4. NamedReadableFile adapters
Class | Description |
---|---|
FileReadableFile | Adapts a File to the NamedReadableFile interface. |
NamedReadableFileAdapter | Adapts a ReadableFile to the NamedReadableFile interface. |
ReadWritableFileAdapter | Adapts a File to the ReadWritableFile interface. |
Implements: Lockable, WriteLockable.
Implemented by: EFile
WritableFile defines a file that can be written or appended to. It is WriteLockable, so an implementing object may be able to be locked for exclusive write access, if it chooses to implement that.
In many ways, it is often better to use a WritableFile as a method argument instead of, as is customarily done in Java libraries today, an OutputStream. The reasons for that are explained in the Introduction section of the Architecture overview.
Table 3.5. Important WritableFile implementations
Class | Description |
---|---|
ByteArrayWritableFile | A file that writes data to a byte array. |
GZipWritableFile | A file that will gzip compress all data written to it. |
Table 3.6. WritableFile adapters
Class | Description |
---|---|
ReadWritableFileAdapter | Adapts a File to the ReadWritableFile interface. |
Implements: Lockable, ReadLockable, ReadWriteLockable, WriteLockable.
Implemented by: EFile
RandomlyAccessibleFile defines a file that can be opened for random access. It is ReadWriteLockable, so an implementing object may be able to be locked for exclusive read or write access, if it chooses to implement that.
EntityFS' RandomAccess object and not Java's RandomAccessFile is used to represent an open random access object. The API for RandomAccess is similar to RandomAccessFile, but it is an interface instead of a class.
Table 3.7. Important RandomlyAccessibleFile implementations
Class | Description |
---|---|
ByteArrayReadableFile | A read-only file that reads data from a byte array. |
Table 3.8. RandomlyAccessibleFile adapters
Class | Description |
---|---|
ReadWritableFileAdapter | Adapts a File to the ReadWritableFile interface. |
Implements: Deletable, Lockable, RandomlyAccessibleFile, ReadableFile, ReadLockable, ReadWriteLockable, WritableFile, WriteLockable.
Implemented by: EFile
ReadWritableFile combines all the other file interfaces and adds methods for copying data and for querying the file's size.
Table 3.9. ReadWritableFile adapters
Class | Description |
---|---|
ReadWritableFileAdapter | Adapts a File to the ReadWritableFile interface. |
Implements: Lockable, ReadLockable.
Implemented by: Directory
EntityHolder is a container that stores entities by their names. Clients can query the object for individual entities, but not list all entities that it contains.
Table 3.10. Important EntityHolder implementations
Class | Description |
---|---|
AggregatingEntityRepository | An EntityRepository that gives an aggregated view of the entities from zero or more other entity repositories. |
CompoundEntityHolder | Entity holder that combines zero or more other entity holders. |
Implements: Iterable<EntityView>, Lockable, ReadLockable.
Implemented by: Directory
EntityListable is a container that stores entities. Clients can use the object to get a list of the stored entities, but cannot query it for individual entities.
Table 3.11. Important EntityListable implementations
Class | Description |
---|---|
AggregatingEntityRepository | An EntityRepository that gives an aggregated view of the entities from zero or more other entity repositories. |
ManualEntityListable | Entity listable that uses a list of entities that can be manipulated by the client. |
Implements: EntityHolder, EntityListable, Iterable<EntityView>, Lockable, ReadLockable.
Implemented by: Directory
EntityRepository combines the EntityHolder and EntityListable interfaces to provide a read only repository for entities.
Table 3.12. Important EntityRepository implementations
Class | Description |
---|---|
AggregatingEntityRepository | An EntityRepository that gives an aggregated view of the entities from zero or more other entity repositories. |