org.entityfs
Interface FileSystemBuilder<T extends FileSystemBuilder<T>>

All Known Subinterfaces:
FSFileSystemBuilder<T>
All Known Implementing Classes:
AbstractFileSystemBuilder, AbstractFileSystemBuilderImpl, AbstractFSFileSystemBuilder, FSROFileSystemBuilder, FSRWFileSystemBuilder, JarFileSystemBuilder, RamFileSystemBuilder, ZipFileSystemBuilder

public interface FileSystemBuilder<T extends FileSystemBuilder<T>>

A file system builder encapsulates the logic for creating a FileSystem. Every file system implementation has one or more builder classes. Implementations of this interface add their own file system implementation-specific setter methods.

The builder objects are designed to be single-use; use them once and then discard them.

File system builders are designed using a variant of the builder pattern that returns the builder from setter methods. This gives the builders a compact and readable notation. For instance:
FileSystem myfs = new FSROFileSystemBuilder().
  setRoot(new File("../..")).
  setName("My protected files").
  enableLocking().
  create();

Implementations are encouraged to inherit AbstractFileSystemBuilderImpl.

Since:
1.0
Author:
Karl Gustafsson

Field Summary
static int DEFAULT_BUFFER_SIZE
          When files are copied, data may be temporarily stored in a memory buffer.
 
Method Summary
 T addCapabilityProvider(CapabilityProvider cp)
          Add a capability provider to the file system.
 T addCapabilityProviders(Collection<? extends CapabilityProvider> cps)
          Add all capability providers in the collection.
 FileSystem create()
          Create the file system that is being built by this builder object.
 T disableAccessControls()
          This is a shorter form for setAccessController(DisabledAccessController.INSTANCE).
 T disableEntityValidityControls()
          A short form for setEntityValidityControlStrategy(null).
 T enableEvents()
          Enable event handling for the file system.
 T enableLocking()
          Enable entity locking with the default settings for lock adapter factory (a NonFairReadWriteEntityLockAdapterFactory and lock acquiring strategy.
 AccessController getAccessController()
          Get the access controller to use for controlling access to entities.
 int getBufferSize()
          Set the size in bytes of internal buffers used for various tasks such as copying files (for some implementations).
 Collection<CapabilityProvider> getCapabilityProviders()
          Get the capability providers.
 EntityValidityControlStrategy getEntityValidityControlStrategy()
          Get the file system's entity validity control strategy.
 LockAcquiringStrategy getLockAcquiringStrategy()
          Get the lock acquiring strategy.
 EntityLockAdapterFactory getLockAdapterFactory()
          Get the lock adapter factory.
 LogAdapter getLogAdapter()
          Get the log adapter that the file system will use.
 String getName()
          Get the file system's name.
 boolean isLockingSupported()
          Does the file system being built support locking?
 T setAccessController(AccessController ac)
          Set the access controller to use for controlling access to entities.
 T setBufferSize(int sz)
          Set the size in bytes of internal buffers used for various tasks such as copying files (for some implementations).
 T setEntityValidityControlStrategy(EntityValidityControlStrategy evcs)
          Set the file system's entity validity control strategy.
 T setLockAcquiringStrategy(LockAcquiringStrategy las)
          Set the lock acquiring strategy that the file system will use.
 T setLockAdapterFactory(EntityLockAdapterFactory laf)
          Set the lock adapter factory that the file system will use.
 T setLogAdapter(LogAdapter l)
          Set the log adapter to use for the file system.
 T setName(String n)
          Set the name of the file system.
 

Field Detail

DEFAULT_BUFFER_SIZE

static final int DEFAULT_BUFFER_SIZE
When files are copied, data may be temporarily stored in a memory buffer. This is the memory buffer's default size (8192 bytes). Set a new value by calling setBufferSize(int)

See Also:
Constant Field Values
Method Detail

setLogAdapter

T setLogAdapter(LogAdapter l)
Set the log adapter to use for the file system. After creating the file system, its log adapter can be changed by giving a new log adapter to the file system's LogAdapterHolder.

Parameters:
l - The log adapter.
Returns:
The builder.
See Also:
FileSystem.getLogAdapterHolder()

getLogAdapter

LogAdapter getLogAdapter()
Get the log adapter that the file system will use.

Returns:
The log adapter.

setLockAcquiringStrategy

T setLockAcquiringStrategy(LockAcquiringStrategy las)
Set the lock acquiring strategy that the file system will use. If no strategy is set, the file system will use a file system builder-specific default strategy. If set to null, locking will be disabled for the file system. For read-only file systems, the default strategy is null.

Parameters:
las - The lock acquiring strategy or null if entity locking should be disabled.
Returns:
The builder.

getLockAcquiringStrategy

LockAcquiringStrategy getLockAcquiringStrategy()
Get the lock acquiring strategy. For read only file systems, this returns null if no strategy is set.

Returns:
The lock acquiring strategy.

setLockAdapterFactory

T setLockAdapterFactory(EntityLockAdapterFactory laf)
Set the lock adapter factory that the file system will use. If no factory is set, the file system will use a file system builder-specific default factory. If set to null, locking will be disabled for the file system. For read-only file systems, the default factory is null.

Parameters:
laf - The lock adapter factory or null if entity locking should be disabled.
Returns:
The builder.

getLockAdapterFactory

EntityLockAdapterFactory getLockAdapterFactory()
Get the lock adapter factory. For read only file systems, this returns null if no factory is set.

Returns:
The lock adapter factory.

isLockingSupported

boolean isLockingSupported()
Does the file system being built support locking?

Returns:
true if the file system being built supports locking.
See Also:
enableLocking()

enableLocking

T enableLocking()
                                             throws UnsupportedOperationException
Enable entity locking with the default settings for lock adapter factory (a NonFairReadWriteEntityLockAdapterFactory and lock acquiring strategy. (a SimpleLockAcquiringStrategy).

This is equivalent to calling setLockAcquiringStrategy(LockAcquiringStrategy) and then setLockAdapterFactory(EntityLockAdapterFactory).

Returns:
The builder.
Throws:
UnsupportedOperationException - If the file system does not support locking
See Also:
isLockingSupported()

setAccessController

T setAccessController(AccessController ac)
Set the access controller to use for controlling access to entities.

Parameters:
ac - The access controller.
Returns:
The builder.

disableAccessControls

T disableAccessControls()
This is a shorter form for setAccessController(DisabledAccessController.INSTANCE).

Returns:
The builder.

getAccessController

AccessController getAccessController()
Get the access controller to use for controlling access to entities. If no access controller is set, this method returns the default access controller, DisabledAccessController.

Returns:
The access controller.

setName

T setName(String n)
Set the name of the file system. The name should be unique within the environment where the file system should be used (usually JVM-unique). The name can be used to identify the file system.

This property is mandatory.

Parameters:
n - The file system name,
Returns:
The builder.

getName

String getName()
Get the file system's name.

Returns:
The file system's name.

addCapabilityProvider

T addCapabilityProvider(CapabilityProvider cp)
Add a capability provider to the file system. The capability provider adds a capability to the file system; something that the file system otherwise would not be able to do.

The order in which capability providers are added is significant. A capability provider will only see the effects of capability providers added before it. The documentation of each capability provider should describe how it should be used together with other capability providers.

Parameters:
cp - The capability provider.
Returns:
The builder.

addCapabilityProviders

T addCapabilityProviders(Collection<? extends CapabilityProvider> cps)
Add all capability providers in the collection. The providers are added in the order that they are returned when iterating over the supplied collection.

Parameters:
cps - The collection of capability providers.
Returns:
The builder.

getCapabilityProviders

Collection<CapabilityProvider> getCapabilityProviders()
Get the capability providers.

Returns:
The list of capability providers.

setEntityValidityControlStrategy

T setEntityValidityControlStrategy(EntityValidityControlStrategy evcs)
Set the file system's entity validity control strategy. The strategy is used by entity objects to validate that they still exist in the backing file system when their methods are used. In this way, entities can detect that they have been deleted by someone that did not go through its file system (for instance by another program). If all file system access is known to be through entity methods in the same file system, this can safely be disabled.

Parameters:
evcs - The entity validity control strategy. Set to null to disable entity validity controlling altogether.
Returns:
The builder.

disableEntityValidityControls

T disableEntityValidityControls()
A short form for setEntityValidityControlStrategy(null).

Returns:
The builder.

getEntityValidityControlStrategy

EntityValidityControlStrategy getEntityValidityControlStrategy()
Get the file system's entity validity control strategy. If no strategy is set, this may return null for file systems that (think that they) completely own their own backends, such as the Ram file system or the Zip file system.

Returns:
The entity validity control strategy.

enableEvents

T enableEvents()
Enable event handling for the file system. If this is enabled, file systems and file system entities will be Observable for EntityEvent:s.

Returns:
The builder.

setBufferSize

T setBufferSize(int sz)
Set the size in bytes of internal buffers used for various tasks such as copying files (for some implementations). The default size is 4096 bytes.

Parameters:
sz - The size of the buffers in bytes.
Returns:
The builder.

getBufferSize

int getBufferSize()
Set the size in bytes of internal buffers used for various tasks such as copying files (for some implementations).

Returns:
The size of the buffers in bytes.

create

FileSystem create()
                  throws FileSystemConfigurationException
Create the file system that is being built by this builder object. After calling this, the builder object should be discarded.

Returns:
A new file system object.
Throws:
FileSystemConfigurationException - On configuration errors.