org.entityfs
Interface FileSystem

All Superinterfaces:

Observable

All Known Subinterfaces:

FileSystemImplementation

All Known Implementing Classes:

AbstractFileSystem, ROFileSystemImpl, RWFileSystemImpl

public interface FileSystem
extends Observable

This is the public (client-visible) interface for a file system implementation. A file system contains Entity:s, commonly EFile:s and Directory:s, but perhaps also other entity types if supported by the file system implementation or provided by a CapabilityProvider. Entities are organized in a directory hierarchy with the root directory as the root node. All entities have a Directory parent entity except for the root directory whose parent is null. An entity's location in the hierarchy and its location relative to other entities are represented by EntityLocation objects.

There are several different FileSystem implementations. They differ in how they store file and file system data. One implementation is the Ram file system that stores data in-memory. Another implementation is the FS file system that uses a regular file system to store its data. Both file systems present the same interface to clients and files can be copied back and forth between the two. This makes the client implementation independent of how file data happen to be stored at its current deploy location. (As long as it does not require capabilities that are file system-specific.)

A file system is instantiated by using a file system implementation's FileSystemBuilder and perhaps by adding additional capabilities via CapabilityProvider:s.

Entity:s in a file system are entities in the true sense of the word. A consequence of that is that entities cannot be moved between different file systems; only copied. (See Entity for more discussion on entities.)

FileSystem implementations are designed for concurrent access by several threads. Locking can be enabled for a file system by calling FileSystemBuilder.enableLocking().

To get sufficiently exclusive access to an entity in a locking file system, a client thread can lock it for reading or writing. Many Entity methods require that the calling thread holds a lock when calling them. The locking semantics are the same as for Java's ReadWriteLock:

• Locks are reentrant
• A thread that holds a write lock for an entity has exclusive access to that entity
• A thread holding a read lock for an entity potentially shares that entity with any number of other threads holding read locks for the same entity.

The actual locking implementation can be different, however. The file system client decides what implementation to use when creating the file system by providing an implementation of EntityLockAdapterFactory.

Entities does not enforce any specific locking strategy (the order in which locks are acquired); that is up to the client implementation to decide. The entity utility objects (such as Directories) use a strategy where locks are acquired top-down in the file system hierarchy. If several entities in the same directory are locked, the locks are acquired in hashCode order. Since locks are reentrant, that strategy might be overridden by the client.

Read only file systems are trivially thread-safe and they don't use any locking. Their locking methods are still callable, though.

A file system may use an AccessController to grant or deny access to entities. If no access controller is used, all clients have access to all entities. The access control mechanism should not be seen as a full-blown security solution; rather as a support for implementing a security solution. It is, for instance, possible for a client without write access to an entity to write lock it and in that way deny other clients access to it.

File system implementations prefer to have exclusive access to the underlying file system, especially for operations other than creating new files or directories. How gracefully a file system can handle changes made by other clients depend on the implementation of EntityValidityControlStrategy used and on the file system implementation itself. An exception to the rule is when the file system client uses a DirectoryMonitorer to monitor a directory for changes (for incoming files, for instance).

Individual entities as well as the entire file system can be configured to be Observable for updates. All events sent by entities are also sent from the file system. The event handling can be enabled when the file system is created by calling FileSystemBuilder.enableEvents().

A short note on error handling: EntityFS use unchecked exceptions to signal errors. All exceptions thrown by EntityFS methods inherit FileSystemException. The documentation for some methods declare specific exceptions that are thrown for specific error conditions, but other exceptions might be thrown as well by for other errors. To be sure to catch all EntityFS exceptions, catch FileSystemException. For a discussion on checked versus unchecked exceptions, see this Wikipedia article.

In addition to the methods defined in this interface, methods implemented in FileSystems may be of use for file system clients.

Since:

1.0

Author:

Karl Gustafsson

See Also:

FileSystems

In_jar:

entityfs-core

Method Summary

void	close() Close and discard this file system instance.
AccessController	getAccessController() Get the file system's access controller.
int	getBufferSize() Get the buffer size configured when creating the file system.
<T extends FileSystemCapability> T	getCapability(FileSystemCapabilityType<T> type) Get a supported FileSystemCapability.
<T extends EntityCapability> T	getCapabilityForEntity(EntityView ev, EntityCapabilityType<T> type) Get a supported EntityCapability for an Entity (or an entity viewed by an EntityView.
LockAcquiringStrategy	getLockAcquiringStrategy() Get the file system's lock acquiring strategy object.
EntityLockAdapterFactory	getLockAdapterFactory() Get the file system's lock adapter factory.
LockCommandExecutor	getLockCommandExecutor() Get the file system's lock command executor.
LogAdapter	getLogAdapter() Convenient alternative to calling getLogAdapterHolder().getLogAdapter().
LogAdapterHolder	getLogAdapterHolder() Get the file system's current LogAdapterHolder.
String	getName() Get the file system's name.
Directory	getRootDirectory() Get the file system's root directory.
Set<FileSystemCapabilityType<?>>	getSupportedCapabilities() Get the set of all supported file system capability types for this file system.
Set<EntityCapabilityType<?>>	getSupportedEntityCapabilities() Get the set of all supported entity capability types for this file system.
Directory	getTemporaryFilesDirectory() Get the directory where this file system keeps its temporary files.
boolean	isAccessControlling() Does the file system use any kind of access controls?
boolean	isLocking() Does the file system do any kind of entity locking? Read only file systems never use any locking.
boolean	isReadOnly() Is the file system read only?
void	setReadOnly(boolean readOnly) Set this file system read only true or read/write false.
void	setTemporaryFilesDirectory(Directory d) Set the directory where this file system keeps its temporary files.
boolean	supportsCapability(FileSystemCapabilityType<?> type) Check if the file system supports a specific FileSystemCapability .
boolean	supportsCapabilityForEntity(EntityView ev, EntityCapabilityType<?> type) Check if an Entity (or an entity viewed by an EntityView supports a specific EntityCapability.
boolean	supportsCapabilityForEntityType(EntityType et, EntityCapabilityType<?> type) Check if a entity type supports a capability type in this file system.

Methods inherited from interface org.entityfs.event.Observable

addObserver, countObservers, deleteObserver, deleteObservers

Method Detail

getName

String getName()

Get the file system's name. The file system name is a unique identifier that may be set by the client when creating the file system. This can for instance be used to tell different {link FileSystem} instances apart when registering JMX MBeans for the file system.

Returns:

The file system name. If set, it should be unique within the current system (JVM, application server cluster, etc.).

isReadOnly

boolean isReadOnly()

Is the file system read only?

Returns:

true if the file system is read only, false if it is read/write.

setReadOnly

void setReadOnly(boolean readOnly)

Set this file system read only true or read/write false.

File systems that are created read only cannot be set read/write. If this method is called with a false argument on a read only file system, the method exits silently. (No exception is thrown.)

Parameters:

readOnly - Should the file system be set read only?

isLocking

boolean isLocking()

Does the file system do any kind of entity locking? Read only file systems never use any locking. For read/write file systems, that is dependent on the implementation of EntityLockAdapterFactory that is used.

Returns:

true if the file system is locking, false if not.

isAccessControlling

boolean isAccessControlling()

Does the file system use any kind of access controls?

Returns:

true if the file system is access controlling, false if not.

getLogAdapterHolder

LogAdapterHolder getLogAdapterHolder()

Get the file system's current LogAdapterHolder.

Returns:

The file system's LogAdapterHolder.

See Also:

getLogAdapter()

getLogAdapter

LogAdapter getLogAdapter()

Convenient alternative to calling getLogAdapterHolder().getLogAdapter().

The LogAdapter returned from this method should not be saved by the client. (Not for a long time, anyway.) Save the file system's LogAdapterHolder instead or let the client call getLogAdapter() every time it wants to log.

Returns:

The current LogAdapter.

See Also:

getLogAdapterHolder()

getLockAdapterFactory

EntityLockAdapterFactory getLockAdapterFactory()

Get the file system's lock adapter factory. Clients can use this to create their own LockAdapter:s for their own locking.

Returns:

The file system's lock adapter factory.

getLockAcquiringStrategy

LockAcquiringStrategy getLockAcquiringStrategy()

Get the file system's lock acquiring strategy object. Clients can use this to acquire locks in the same way as the file system.

Returns:

The file system's lock acquiring strategy.

getRootDirectory

Directory getRootDirectory()

Get the file system's root directory.

Returns:

The root directory.

setTemporaryFilesDirectory

void setTemporaryFilesDirectory(Directory d)
                                throws IllegalArgumentException

Set the directory where this file system keeps its temporary files. This is optional.

Parameters:

d - The Directory for temporary files. The directory must be in this file system.

Throws:

IllegalArgumentException - If the directory is not in this file system.

See Also:

getTemporaryFilesDirectory()

getTemporaryFilesDirectory

Directory getTemporaryFilesDirectory()

Get the directory where this file system keeps its temporary files. The directory must have been set with a call to setTemporaryFilesDirectory(Directory) before calling this method.

Returns:

The directory for temporary files, or null if it has not been set.

getAccessController

AccessController getAccessController()

Get the file system's access controller.

Returns:

The file system's access controller, or DisabledAccessController.INSTANCE if access controls are disabled.

getLockCommandExecutor

LockCommandExecutor getLockCommandExecutor()

Get the file system's lock command executor. The lock command executor can be used to acquire locks for several entities at once in a way that is compliant with the executor's locking strategy.

This is used, for instance, by utility classes to acquire locks required for access control checks and other operations.

The default LockCommandExecutor implementation is LockCommandExecutorImpl. Some AccessController:s may require other implementations.

Returns:

The file system's lock command executor.

supportsCapability

boolean supportsCapability(FileSystemCapabilityType<?> type)

Check if the file system supports a specific FileSystemCapability . Capabilities are either supported directly by file system implementations or by CapabilityProvider:s given to the file system at creation time.

Parameters:

type - The capability's FileSystemCapabilityType.

Returns:

true if the file system supports the capability, false if not.

See Also:

getCapability(FileSystemCapabilityType)

getCapability

<T extends FileSystemCapability> T getCapability(FileSystemCapabilityType<T> type)
                                             throws UnsupportedCapabilityException

Get a supported FileSystemCapability.

Parameters:

type - The capability's FileSystemCapabilityType.

Returns:

The capability object.

Throws:

UnsupportedCapabilityException - If the requested capability is not supported by the file system.

See Also:

supportsCapability(FileSystemCapabilityType)

getSupportedCapabilities

Set<FileSystemCapabilityType<?>> getSupportedCapabilities()

Get the set of all supported file system capability types for this file system.

Returns:

The set of all supported file system capability types.

supportsCapabilityForEntity

boolean supportsCapabilityForEntity(EntityView ev,
                                    EntityCapabilityType<?> type)

Check if an Entity (or an entity viewed by an EntityView supports a specific EntityCapability. Capabilities are either supported directly by file system implementations or by CapabilityProvider:s given to the file system at creation time.

Parameters:

ev - The EntityView to check for.

type - The capability's EntityCapabilityType.

Returns:

true if the entity supports the capability, false if not.

See Also:

getCapabilityForEntity(EntityView, EntityCapabilityType), supportsCapabilityForEntityType(EntityType, EntityCapabilityType), EntityView.supportsCapability(EntityCapabilityType)

supportsCapabilityForEntityType

boolean supportsCapabilityForEntityType(EntityType et,
                                        EntityCapabilityType<?> type)

Check if a entity type supports a capability type in this file system. Capabilities are either supported directly by file system implementations or by CapabilityProvider:s given to the file system at creation time.

There may be exceptions to the result returned by this method for certain special entities (i.e. the root directory). For querying about capabilities of existing entities, use the EntityView.supportsCapability(EntityCapabilityType) method instead.

Parameters:

et - The entity type.

type - The entity capability type.

Returns:

true if the capability type is supported by the supplied entity type in this file systems. (There may be exceptions to that rule, however. See above.)

See Also:

supportsCapabilityForEntity(EntityView, EntityCapabilityType)

getCapabilityForEntity

<T extends EntityCapability> T getCapabilityForEntity(EntityView ev,
                                                      EntityCapabilityType<T> type)
                                                  throws UnsupportedCapabilityException

Get a supported EntityCapability for an Entity (or an entity viewed by an EntityView.

Parameters:

ev - The EntityView to get the capability object for.

type - The capability's EntityCapabilityType.

Returns:

An EntityCapability object for the Entity.

Throws:

UnsupportedCapabilityException - If the capability is not supported by the Entity.

See Also:

supportsCapabilityForEntity(EntityView, EntityCapabilityType), EntityView.getCapability(EntityCapabilityType)

getSupportedEntityCapabilities

Set<EntityCapabilityType<?>> getSupportedEntityCapabilities()

Get the set of all supported entity capability types for this file system.

Returns:

The set of all supported entity capability types for this file system.

getBufferSize

int getBufferSize()

Get the buffer size configured when creating the file system. The buffer size is used as the default size of temporary buffers used for various tasks such as for copying files (for some implementations). The default size is 4096 bytes.

Returns:

The size of temporary buffers in bytes.

close

void close()

Close and discard this file system instance.

Different file system implementations implement this differently. File systems that are built on open files (the Zip file system, for instance), close that file.

This should be implemented so that it is possible to call close several times on the same file system instance without getting any errors.