net.java.truevfs.kernel.spec

Interface FsController

All Known Implementing Classes:

AbstractKeyController, FsAbstractController, FsAccessOptionsController, FsDecoratingController, HttpController, InstrumentingController

@ImplementationsShouldExtend(value=FsAbstractController.class)
public interface FsController

Provides read/write access to a file system.

General Properties

The mount point of the file system model addresses the file system accessed by this controller. Where the methods of this abstract class accept a file system node name as a parameter, this MUST get resolved against the mount point URI of this controller's file system model.

As of TrueVFS 0.10, application level transactions are not supported, that is, multiple file system operations cannot get composed into a single application level transaction - support for this feature may be added in a future version.

However, individual file system operations do come with assertions about their atomicity, consistency, isolation and durability. Each method of this interface which is expected to access the file system (rather than just memory) is annotated with an FsAssertion. The annotation is Inherited, so the assertion forms part of the contract which any implementation of this interface should comply to.

Note that file system controllers are generally allowed to buffer any changes made to their file system. This is generally true for file system controllers which operate on archive files. This means that all changes made to the file system via this interface may not be entirely durable until they get committed by calling sync(net.java.truecommons.shed.BitField<net.java.truevfs.kernel.spec.FsSyncOption>). The annotations account for this stipulation by leaving the durability property undefined.

An implementation which wants to buffer its changes until sync gets called needs to notify the file system manager by calling setMounted(true) on the controller's file system model before the first change is commenced. Likewise, when sync gets called, the controller needs to notify the file system manager by calling setMounted(false) on the controller's file system model if and only if the sync has been successfully completed. This protocol enables proper management of the controller's life cycle.

Implementations should be safe for multi-threaded access.

Author:

Christian Schlichtherle

See Also:

FsManager, FsModel, RFC 2119: Key words for use in RFCs to Indicate Requirement Levels

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	FsController.Factory<Context> A factory for file system controllers.

Method Summary

Modifier and Type	Method and Description
void	checkAccess(net.java.truecommons.shed.BitField<FsAccessOption> options, FsNodeName name, net.java.truecommons.shed.BitField<net.java.truecommons.cio.Entry.Access> types) Checks if the file system node for the given name exists when constrained by the given access options and permits the given access types.
FsModel	getModel() Returns the file system model.
FsController	getParent() Returns the controller for the parent file system or null if and only if this file system is not federated, i.e.
net.java.truecommons.cio.InputSocket<? extends net.java.truecommons.cio.Entry>	input(net.java.truecommons.shed.BitField<FsAccessOption> options, FsNodeName name) Returns an input socket for reading the contents of the file system node addressed by the given name from the file system.
void	make(net.java.truecommons.shed.BitField<FsAccessOption> options, FsNodeName name, net.java.truecommons.cio.Entry.Type type, net.java.truecommons.cio.Entry template) Creates or replaces and finally links a chain of one or more entries for the given node name into the file system.
FsNode	node(net.java.truecommons.shed.BitField<FsAccessOption> options, FsNodeName name) Returns the file system node for the given name or null if it doesn't exist.
net.java.truecommons.cio.OutputSocket<? extends net.java.truecommons.cio.Entry>	output(net.java.truecommons.shed.BitField<FsAccessOption> options, FsNodeName name, net.java.truecommons.cio.Entry template) Returns an output socket for writing the contents of the node addressed by the given name to the file system.
void	setReadOnly(net.java.truecommons.shed.BitField<FsAccessOption> options, FsNodeName name) Sets the named file system node as read-only.
boolean	setTime(net.java.truecommons.shed.BitField<FsAccessOption> options, FsNodeName name, net.java.truecommons.shed.BitField<net.java.truecommons.cio.Entry.Access> types, long value) Makes an attempt to set the last access time of all types in the given bit field for the file system node with the given name.
boolean	setTime(net.java.truecommons.shed.BitField<FsAccessOption> options, FsNodeName name, Map<net.java.truecommons.cio.Entry.Access,Long> times) Makes an attempt to set the last access time of all types in the given map for the file system node with the given name.
void	sync(net.java.truecommons.shed.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.
void	unlink(net.java.truecommons.shed.BitField<FsAccessOption> options, FsNodeName name) Removes the named file system node from the file system.

Method Detail

checkAccess

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
void checkAccess(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                                                                                       FsNodeName name,
                                                                                                                                       net.java.truecommons.shed.BitField<net.java.truecommons.cio.Entry.Access> types)
                                                                                                                                throws IOException

Checks if the file system node for the given name exists when constrained by the given access options and permits the given access types.

Parameters:

options - the options for accessing the file system node.

name - the name of the file system node.

types - the types of the desired access.

Throws:

IOException - on any I/O error.

getModel

FsModel getModel()

Returns the file system model.

Returns:

The file system model.

getParent

@Nullable
FsController getParent()

Returns the controller for the parent file system or 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.

Returns:

The nullable controller for the parent file system.

input

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
net.java.truecommons.cio.InputSocket<? extends net.java.truecommons.cio.Entry> input(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                                                                                                                                                           FsNodeName name)

Returns an input socket for reading the contents of the file system node addressed by the given name from the file system. Note that the assertions for this file system operation equally apply to any channel or stream created by the returned input socket!

Parameters:

options - the options for accessing the file system node.

name - the name of the file system node.

Returns:

An InputSocket.

make

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES)
void make(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                                           FsNodeName name,
                                                                                           net.java.truecommons.cio.Entry.Type type,
                                                                                           @CheckForNull
                                                                                           net.java.truecommons.cio.Entry template)
                                                                                    throws IOException

Creates or replaces and finally links a chain of one or more entries for the given node name into the file system.

Parameters:

options - the options for accessing the file system node. If FsAccessOption.CREATE_PARENTS is set, any missing parent directories shall get created with an undefined last modification time.

name - the name of the file system node.

type - the file system node type.

template - if not null, then the file system node at the end of the chain shall inherit as much properties from this node as possible - with the exception of its name and type.

Throws:

IOException - on any I/O error, including but not limited to these reasons:

• The file system is read only.
• name contains characters which are not supported by the file system.
• The node already exists and either the option FsAccessOption.EXCLUSIVE is set or the node is a directory.
• The node exists as a different type.
• A parent node exists but is not a directory.
• A parent node is missing and createParents is false.

node

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES,
             durable=NOT_APPLICABLE)
 @CheckForNull
FsNode node(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                                                                                                 FsNodeName name)
                                                                                                                                          throws IOException

Returns the file system node for the given name or null if it doesn't exist. Modifying the returned node does not show any effect on the file system and should result in an UnsupportedOperationException.

Parameters:

options - the options for accessing the file system node.

name - the name of the file system node.

Returns:

A file system node or null if no file system node exists for the given name.

Throws:

IOException - on any I/O error.

output

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES)
net.java.truecommons.cio.OutputSocket<? extends net.java.truecommons.cio.Entry> output(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                                                                                                                        FsNodeName name,
                                                                                                                                                                        @CheckForNull
                                                                                                                                                                        net.java.truecommons.cio.Entry template)

Returns an output socket for writing the contents of the node addressed by the given name to the file system. Note that the assertions for this file system operation equally apply to any channel or stream created by the returned output socket!

Parameters:

options - the options for accessing the file system node. If FsAccessOption.CREATE_PARENTS is set, any missing parent directories shall get created with an undefined last modification time.

name - the name of the file system node.

template - if not null, then the file system node at the end of the chain shall inherit as much properties from this node as possible - with the exception of its name and type.

Returns:

An OutputSocket.

setReadOnly

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES)
void setReadOnly(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                                                  FsNodeName name)
                                                                                           throws IOException

Sets the named file system node as read-only. This method will fail for typical archive file system controller implementations because they do not support it.

Parameters:

options - the options for accessing the file system node.

name - the name of the file system node.

Throws:

IOException - on any I/O error or if this operation is not supported.

setTime

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=YES)
boolean setTime(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                                                FsNodeName name,
                                                                                                net.java.truecommons.shed.BitField<net.java.truecommons.cio.Entry.Access> types,
                                                                                                long value)
                                                                                         throws IOException

Makes an attempt to set the last access time of all types in the given bit field for the file system node with the given name. If false is returned or an IOException is thrown, then still some of the last access times may have been set.

Parameters:

options - the options for accessing the file system node.

name - the name of the file system node.

types - the access types.

value - the last access time.

Returns:

true if and only if setting the access time for all types in types succeeded.

Throws:

IOException - on any I/O error.

setTime

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=YES)
boolean setTime(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                                                FsNodeName name,
                                                                                                Map<net.java.truecommons.cio.Entry.Access,Long> times)
                                                                                         throws IOException

Makes an attempt to set the last access time of all types in the given map for the file system node with the given name. If 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.

Parameters:

options - the options for accessing the file system node.

name - the name of the file system node.

times - the access times.

Returns:

true if and only if setting the access time for all types in times succeeded.

Throws:

IOException - on any I/O error.

NullPointerException - if any key or value in the map is null.

sync

@FsAssertion(atomic=NO,
             consistent=YES,
             isolated=YES)
void sync(net.java.truecommons.shed.BitField<FsSyncOption> options)
                                                                                   throws FsSyncException

Commits all unsynchronized changes to the contents of this file system to its parent file system, releases the associated resources (e.g. target archive files) for access by third parties (e.g. other processes), cleans up any temporary allocated resources (e.g. temporary files) and purges any cached data. Note that temporary resources may get allocated even if the federated file systems were accessed read-only. If this is not a federated file system, i.e. if its not a member of a parent file system, then nothing happens. Otherwise, the state of this file system controller is reset.

An implementation may ignore calls to this method if its stateless.

Parameters:

options - the options for synchronizing the file system.

Throws:

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.

unlink

@FsAssertion(atomic=YES,
             consistent=YES,
             isolated=YES)
void unlink(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                                             FsNodeName name)
                                                                                      throws IOException

Removes the named file system node from the file system. If the named file system node is a directory, it must be empty.

Parameters:

options - the options for accessing the file system node.

name - the name of the file system node.

Throws:

IOException - on any I/O error.