M
- the type of the file system model.public abstract class FsController<M extends FsModel> extends Object
The mount point
of the
file system model
addresses the file system at the head
of this chain of federated file systems.
Where the methods of this abstract class accept a
file system entry name
as a parameter, this MUST get
resolved against the mount point
URI of this
controller's file system model
.
Even on modern computers, I/O operations are inherently unreliable: They can fail on hardware errors, network timeouts, third party interactions etc. In an ideal world, we would like all file system operations to be truly transactional like some relational database services. However, file system have to cope with really big data, much more than most relational databases will ever see. Its not uncommon these days to store some gigabytes of data in a single file, for example a video file. However, buffering gigabytes of data just for an eventual rollback of a transaction is still not a realistic option and considering the fact that faster computers have always been used to store even bigger data then its getting clear that it never will be. Therefore, the contract of this abstract class strives for only limited transactional support as follows.
RuntimeException
or an IOException
to respectively indicate
wrong input parameters or a file system operation failure.
Where the following terms consider a failure, the term equally applies to
both exception types.
sync(de.schlichtherle.truezip.util.BitField<de.schlichtherle.truezip.fs.FsSyncOption>)
, all file system operations SHOULD be
atomic, that is they either succeed or fail completely as if they had
not been called.
FsDriver.newController(de.schlichtherle.truezip.fs.FsManager, de.schlichtherle.truezip.fs.FsModel, de.schlichtherle.truezip.fs.FsController<? extends de.schlichtherle.truezip.fs.FsModel>)
and FsCompositeDriver.newController(de.schlichtherle.truezip.fs.FsManager, de.schlichtherle.truezip.fs.FsModel, de.schlichtherle.truezip.fs.FsController<? extends de.schlichtherle.truezip.fs.FsModel>)
.
sync(de.schlichtherle.truezip.util.BitField<de.schlichtherle.truezip.fs.FsSyncOption>)
has succeeded, all previous file system
operations MUST be durable.
Furthermore, any changes to the stored data in the parent file system or
storage system which have been made by third parties up to this point in
time MUST be visible to the users of this class.
This enables file system operations to use I/O buffers most of the time and
eventually synchronize their contents with the parent file system or storage
system upon a call to sync
.
FsManager
,
RFC 2119: Key words for use in RFCs to Indicate Requirement LevelsConstructor and Description |
---|
FsController() |
Modifier and Type | Method and Description |
---|---|
boolean |
equals(Object that)
Two file system controllers are considered equal if and only if they
are identical.
|
abstract FsEntry |
getEntry(FsEntryName name)
Returns the file system entry for the given name or
null if it
doesn't exist. |
abstract InputSocket<?> |
getInputSocket(FsEntryName name,
BitField<FsInputOption> options)
Returns an input socket for reading the contents of the file system
entry addressed by the given name from the file system.
|
abstract M |
getModel()
Returns the file system model.
|
abstract OutputSocket<?> |
getOutputSocket(FsEntryName name,
BitField<FsOutputOption> options,
Entry template)
Returns an output socket for writing the contents of the entry addressed
by the given name to the file system.
|
abstract FsController<?> |
getParent()
Returns the controller for the parent file system or
null if
and only if this file system is not federated, i.e. |
int |
hashCode()
Returns a hash code which is consistent with
equals(java.lang.Object) . |
boolean |
isExecutable(FsEntryName name)
Returns
false if the named file system entry is not executable. |
abstract boolean |
isReadable(FsEntryName name)
Returns
false if the named file system entry is not readable. |
abstract boolean |
isReadOnly()
Returns
true if and only if the file system is read-only. |
abstract boolean |
isWritable(FsEntryName name)
Returns
false if the named file system entry is not writable. |
abstract void |
mknod(FsEntryName name,
Entry.Type type,
BitField<FsOutputOption> options,
Entry template)
Creates or replaces and finally links a chain of one or more entries
for the given entry
name into the file system. |
abstract void |
setReadOnly(FsEntryName name)
Sets the named file system entry as read-only.
|
abstract boolean |
setTime(FsEntryName name,
BitField<Entry.Access> types,
long value,
BitField<FsOutputOption> options)
Makes an attempt to set the last access time of all types in the given
bit field for the file system entry with the given name.
|
boolean |
setTime(FsEntryName name,
Map<Entry.Access,Long> times,
BitField<FsOutputOption> options)
Makes an attempt to set the last access time of all types in the given
map for the file system entry with the given name.
|
abstract void |
sync(BitField<FsSyncOption> options)
Commits all unsynchronized changes to the contents of this file system
to its parent file system,
releases the associated resources (e.g.
|
String |
toString()
Returns a string representation of this object for debugging and logging
purposes.
|
abstract void |
unlink(FsEntryName name,
BitField<FsOutputOption> options)
Removes the named file system entry from the file system.
|
public final boolean equals(@CheckForNull Object that)
@Nullable public abstract FsEntry getEntry(FsEntryName name) throws IOException
null
if it
doesn't exist.
Modifying the returned entry does not show any effect on the file system
and may result in an UnsupportedOperationException
.name
- the name of the file system entry.null
if no file system entry
exists for the given name.IOException
- on any I/O failure.public abstract InputSocket<?> getInputSocket(FsEntryName name, BitField<FsInputOption> options)
name
- the file system entry name.options
- the input options.InputSocket
.public abstract M getModel()
public abstract OutputSocket<?> getOutputSocket(FsEntryName name, BitField<FsOutputOption> options, @CheckForNull Entry template)
template
is not null
, then the output entry shall
have as many of its properties copied as reasonable, e.g. the last
modification time.name
- a file system entry name.options
- a bit field of output options.template
- a nullable template for the properties of the output
entry.OutputSocket
.@Nullable public abstract FsController<?> getParent()
null
if
and only if this file system is not federated, i.e. not a member of
another file system.
Multiple invocations must return the same object.public final int hashCode()
equals(java.lang.Object)
.public boolean isExecutable(FsEntryName name) throws IOException
false
if the named file system entry is not executable.
The implementation in the class FsController
always returns
false
.
name
- the name of the file system entry.false
if the named file system entry is not executable.IOException
- on any I/O failure.public abstract boolean isReadable(FsEntryName name) throws IOException
false
if the named file system entry is not readable.name
- the name of the file system entry.false
if the named file system entry is not readable.IOException
- on any I/O failure.public abstract boolean isReadOnly() throws IOException
true
if and only if the file system is read-only.true
if and only if the file system is read-only.IOException
- on any I/O failure.public abstract boolean isWritable(FsEntryName name) throws IOException
false
if the named file system entry is not writable.name
- the name of the file system entry.false
if the named file system entry is not writable.IOException
- on any I/O failure.public abstract void mknod(FsEntryName name, Entry.Type type, BitField<FsOutputOption> options, @CheckForNull Entry template) throws IOException
name
into the file system.name
- the file system entry name.type
- the file system entry type.options
- the file system output options.
If FsOutputOption.CREATE_PARENTS
is set, any missing
parent directories will be created and linked into the file
system with its last modification time set to the system's
current time.template
- if not null
, then the file system entry
at the end of the chain shall inherit as much properties from
this entry as possible - with the exception of its name and type.IOException
- on any I/O failure, including but not limited to
these reasons:
name
contains characters which are not
supported by the file system.
FsOutputOption.EXCLUSIVE
is set or the entry is a
directory.
createParents
is
false
.
public abstract void setReadOnly(FsEntryName name) throws IOException
name
- the name of the file system entry.IOException
- on any I/O failure or if this operation is not
supported.public abstract boolean setTime(FsEntryName name, BitField<Entry.Access> types, long value, BitField<FsOutputOption> options) throws IOException
false
is returned or an IOException
is thrown, then
still some of the last access times may have been set.name
- the file system entry name.types
- the access types.value
- the last access time.options
- the file system output options.true
if and only if setting the access time for all
types in types
succeeded.IOException
- on any I/O failure.public boolean setTime(FsEntryName name, Map<Entry.Access,Long> times, BitField<FsOutputOption> options) throws IOException
false
is returned or an IOException
is thrown, then
still some of the last access times may have been set.
Whether or not this is an atomic operation is specific to the
implementation.name
- the file system entry name.times
- the access times.options
- the file system output options.true
if and only if setting the access time for all
types in times
succeeded.IOException
- on any I/O failure.NullPointerException
- if any key or value in the map is
null
.public abstract void sync(BitField<FsSyncOption> options) throws FsSyncWarningException, FsSyncException
options
- the options for synchronizing the file system.FsSyncWarningException
- if only warning conditions
apply.
This implies that the respective parent file system has been
synchronized with constraints, e.g. if an unclosed archive entry
stream gets forcibly closed.FsSyncException
- if any error conditions apply.public String toString()
public abstract void unlink(FsEntryName name, BitField<FsOutputOption> options) throws IOException
name
- the file system entry name.options
- output options for this operation.IOException
- on any I/O failure.Copyright © 2005–2018 Schlichtherle IT Services. All rights reserved.