au.com.prunge.jgenfile
Interface FileSystem

All Known Implementing Classes:

AbstractFileSystem

public interface FileSystem

A file system has methods to batch commands and allows retrieval of metadata relating to the file system itself, as well as a batch run method for operations that can be used to improve performance.

Version:

1.0

Author:

Peter Runge

Method Summary

void	addOperationHints(au.com.prunge.jgenfile.OperationHints hints) Adds operation hints that operations created from this file system or objects derived from the file system (e.g.
au.com.prunge.jgenfile.BatchOperation	createBatchOperation(List operationList, boolean abortOnError) Creates an operation that runs a number of operations.
au.com.prunge.jgenfile.CanGetItemFromAbsoluteReferenceOperation	createCanGetItemFromAbsoluteReferenceOperation(au.com.prunge.jgenfile.AbsoluteItemReference ref) Creates an operation that tests whether an item in the file system can be acquired given the specified absolute reference.
au.com.prunge.jgenfile.CanGetFileSystemMetadataOperation	createCanGetMetadataOperation(Set metadataKeySet) Creates an operation that tests whether the specified metadata is accessible for this file system.
au.com.prunge.jgenfile.CanGetRootsOperation	createCanGetRootsOperation() Creates an operation that tests whether the roots in this file system can be retrieved.
au.com.prunge.jgenfile.CanSetFileSystemMetadataOperation	createCanSetMetadataOperation(Set metadataKeySet) Creates an operation that tests whether the specified metadata can be set for this file system.
au.com.prunge.jgenfile.CloseFileSystemOperation	createCloseOperation() Creates an operation that closes this file system.
au.com.prunge.jgenfile.GetFileSystemMetadataOperation	createGetAllMetadataOperation() Creates an operation that acquires all available metadata for this file system.
au.com.prunge.jgenfile.GetItemFromAbsoluteReferenceOperation	createGetItemFromAbsoluteReferenceOperation(au.com.prunge.jgenfile.AbsoluteItemReference ref) Creates an operation that gets an item in the file system given an absolute reference.
au.com.prunge.jgenfile.GetFileSystemMetadataOperation	createGetMetadataOperation(Set metadataKeySet) Creates an operation that acquires the specified metadata.
au.com.prunge.jgenfile.GetRootOperation	createGetRootOperation(String rootName) Creates an operation that retrieves the root with the specified name in the file system.
au.com.prunge.jgenfile.GetRootsOperation	createGetRootsOperation() Creates an operation that retrieves the roots in this file system.
au.com.prunge.jgenfile.SetFileSystemMetadataOperation	createSetMetadataOperation(Map metadataMap) Creates an operation that sets the specified metadata for this file system.
Set	getAllFileSystemMetadataKeysSet() Returns a set of metadata keys that can be used to access metadata for this file system.
Set	getAllItemMetadataKeysSet() Returns a set of metadata keys that can be used to access metadata for items.
OperationHints.Value	getOperationHint(OperationHints.Key key) Returns the value of a single hint.
au.com.prunge.jgenfile.OperationHints	getOperationHints() Returns the operation hints that operations created from this file system or objects derived from the file system (e.g.
void	setOperationHint(OperationHints.Key key, OperationHints.Value value) Sets the value of a single hint.
void	setOperationHints(au.com.prunge.jgenfile.OperationHints hints) Sets operation hints that operations created from this file system or objects derived from the file system (e.g.

Method Detail

createGetRootsOperation

public au.com.prunge.jgenfile.GetRootsOperation createGetRootsOperation()
                                                                 throws JGenFileException

Creates an operation that retrieves the roots in this file system.

Throws:

JGenFileException - if an error occurs creating the operation.

createCanGetRootsOperation

public au.com.prunge.jgenfile.CanGetRootsOperation createCanGetRootsOperation()
                                                                       throws JGenFileException

Creates an operation that tests whether the roots in this file system can be retrieved.

Throws:

JGenFileException - if an error occurs creating the operation.

createGetRootOperation

public au.com.prunge.jgenfile.GetRootOperation createGetRootOperation(String rootName)
                                                               throws JGenFileException

Creates an operation that retrieves the root with the specified name in the file system.

Parameters:

rootName - the name of the root.

Throws:

JGenFileException - if an error occurs creating the operation.

createGetItemFromAbsoluteReferenceOperation

public au.com.prunge.jgenfile.GetItemFromAbsoluteReferenceOperation createGetItemFromAbsoluteReferenceOperation(au.com.prunge.jgenfile.AbsoluteItemReference ref)
                                                                                                         throws JGenFileException,
                                                                                                                NullPointerException

Creates an operation that gets an item in the file system given an absolute reference.

Parameters:

ref - an absolute reference to the item.

Throws:

JGenFileException - if an error occurs creating the operation.

NullPointerException - if ref is null.

createCanGetItemFromAbsoluteReferenceOperation

public au.com.prunge.jgenfile.CanGetItemFromAbsoluteReferenceOperation createCanGetItemFromAbsoluteReferenceOperation(au.com.prunge.jgenfile.AbsoluteItemReference ref)
                                                                                                               throws JGenFileException,
                                                                                                                      NullPointerException

Creates an operation that tests whether an item in the file system can be acquired given the specified absolute reference.

Parameters:

ref - an absolute reference to the item.

Throws:

JGenFileException - if an error occurs creating the operation.

NullPointerException - if ref is null.

createBatchOperation

public au.com.prunge.jgenfile.BatchOperation createBatchOperation(List operationList,
                                                                  boolean abortOnError)
                                                           throws JGenFileException,
                                                                  NullPointerException,
                                                                  IllegalArgumentException

Creates an operation that runs a number of operations. This method should be used instead of calling each individual operation's run method to improve performance. The file system implementation might be able to optimize the operations.

For example, if the size of ten files in a directory need to be acquired, you can run all the commands through this method which might use a single transaction through a socket to get all the required information. This would be faster than running each command separately since this would need ten transactions.

The results for each operation that is run successfully must be filled in by this method, whether or not the operation itself was run or some optimization was used instead.

Parameters:

operationList - a list of operations to run.

abortOnError - if true, if an error is encountered running an operation, no more operations should be run. If false, the other operations will attempt to execute even if an error occurs.

Returns:

an operation that will execute all the specified operations.

Throws:

JGenFileException - if an error occurs creating the operation.

NullPointerException - if operationList is null.

IllegalArgumentException - if operationList contains an object that does not implement Operation.

createCloseOperation

public au.com.prunge.jgenfile.CloseFileSystemOperation createCloseOperation()
                                                                     throws JGenFileException

Creates an operation that closes this file system.

After using a file system, closing it allows resources that it is using to be cleaned up. For example, if the file system uses a socket to access the network that socket may be closed when a close operation is run.

Throws:

JGenFileException - if the operation could not be created.

createGetMetadataOperation

public au.com.prunge.jgenfile.GetFileSystemMetadataOperation createGetMetadataOperation(Set metadataKeySet)
                                                                                 throws JGenFileException,
                                                                                        NullPointerException

Creates an operation that acquires the specified metadata.

Parameters:

metadataKeySet - a set of MetadataKey objects.

Throws:

JGenFileException - if the operation could not be created.

NullPointerException - if metadataKeySet is null.

See Also:

MetadataKey

createGetAllMetadataOperation

public au.com.prunge.jgenfile.GetFileSystemMetadataOperation createGetAllMetadataOperation()
                                                                                    throws JGenFileException

Creates an operation that acquires all available metadata for this file system.

Throws:

JGenFileException - if the operation could not be created.

createCanGetMetadataOperation

public au.com.prunge.jgenfile.CanGetFileSystemMetadataOperation createCanGetMetadataOperation(Set metadataKeySet)
                                                                                       throws JGenFileException,
                                                                                              NullPointerException

Creates an operation that tests whether the specified metadata is accessible for this file system.

Parameters:

metadataKeySet - a set of MetadataKey objects representing the elements of metadata to test for.

Throws:

JGenFileException - if the operation could not be created.

NullPointerException - if metadataKeySet is null.

See Also:

MetadataKey

createSetMetadataOperation

public au.com.prunge.jgenfile.SetFileSystemMetadataOperation createSetMetadataOperation(Map metadataMap)
                                                                                 throws JGenFileException,
                                                                                        NullPointerException

Creates an operation that sets the specified metadata for this file system.

The map's keys should consist of MetadataKey objects, the values should be appropriate for each key.

Parameters:

metadataMap - a map of MetadataKeys to values.

Throws:

JGenFileException - if the operation could not be created.

NullPointerException - if metadataMap is null.

See Also:

MetadataKey

createCanSetMetadataOperation

public au.com.prunge.jgenfile.CanSetFileSystemMetadataOperation createCanSetMetadataOperation(Set metadataKeySet)
                                                                                       throws JGenFileException,
                                                                                              NullPointerException

Creates an operation that tests whether the specified metadata can be set for this file system.

Parameters:

metadataKeySet - a set of MetadataKey objects representing the elements of metadata to test for.

Throws:

JGenFileException - if the operation could not be created.

NullPointerException - if metadataKeySet is null.

See Also:

MetadataKey

getAllItemMetadataKeysSet

public Set getAllItemMetadataKeysSet()

Returns a set of metadata keys that can be used to access metadata for items.

This method returns a set of all the possible keys that can be used by items in the file system. Not all items in the file system need to have metadata for the keys returned in the set. It is possible that no items actually have metadata for this key. This method may be useful for user interfaces for giving the user a choice of what columns to display.

For example, a file system may support a 'bit rate' metadata key for accessing the bit rate of MP3 files. This metadata will only be available for MP3 files. This method should include a key for this metadata in the set returned by this method.

Returns:

a set of metadata key objects. May return an empty set if no metadata is supported.

getAllFileSystemMetadataKeysSet

public Set getAllFileSystemMetadataKeysSet()

Returns a set of metadata keys that can be used to access metadata for this file system.

Returns:

a set of metadata key objects. May return an empty set if no metadata is supported.

addOperationHints

public void addOperationHints(au.com.prunge.jgenfile.OperationHints hints)
                       throws NullPointerException

Adds operation hints that operations created from this file system or objects derived from the file system (e.g. items) will have by default. The specified hints are combined with the hints already registered in the file system.

Parameters:

hints - the hints to add.

Throws:

NullPointerException - if hints is null.

setOperationHints

public void setOperationHints(au.com.prunge.jgenfile.OperationHints hints)
                       throws NullPointerException

Sets operation hints that operations created from this file system or objects derived from the file system (e.g. items) will have by default. Any hints that are already added to this file system will be lost.

Parameters:

hints - the hints to set.

Throws:

NullPointerException - if hints is null.

getOperationHints

public au.com.prunge.jgenfile.OperationHints getOperationHints()

Returns the operation hints that operations created from this file system or objects derived from the file system (e.g. items) will have by default.

Returns:

the operation hints in this file system.

getOperationHint

public OperationHints.Value getOperationHint(OperationHints.Key key)
                                      throws NullPointerException

Returns the value of a single hint. Returns null if the specified hint has not been set for this file system.

Parameters:

key - the operation hints key to get the value of.

Returns:

the value of a single hint, or null.

Throws:

NullPointerException - if key is null.

setOperationHint

public void setOperationHint(OperationHints.Key key,
                             OperationHints.Value value)
                      throws NullPointerException

Sets the value of a single hint.

Parameters:

key - the key for the operation hint.

value - the value to give the operation hint.

Throws:

NullPointerException - if key or value is null.