Package nl.esciencecenter.xenon.filesystems

Class FileSystem

java.lang.Object

nl.esciencecenter.xenon.filesystems.FileSystem

All Implemented Interfaces:

java.lang.AutoCloseable

public abstract class FileSystem
extends java.lang.Object
implements java.lang.AutoCloseable

FileSystem represent a (possibly remote) file system that can be used to access data.

Method Summary

Modifier and Type	Method	Description
abstract java.io.OutputStream	appendToFile(Path file)	Open an existing file and return an OutputStream to append data to this file.
CopyStatus	cancel(java.lang.String copyIdentifier)	Cancel a copy operation.
void	close()	Close this FileSystem.
java.lang.String	copy(Path source, FileSystem destinationFS, Path destination, CopyMode mode, boolean recursive)	Asynchronously Copy an existing source path to a target path on a different file system.
static FileSystem	create(java.lang.String adaptor)	Create a new FileSystem using the adaptor that connects to a data store at the default location using the default credentials to get access.
static FileSystem	create(java.lang.String adaptor, java.lang.String location)	Create a new FileSystem using the adaptor that connects to a data store at location using the default credentials to get access.
static FileSystem	create(java.lang.String adaptor, java.lang.String location, Credential credential)	Create a new FileSystem using the adaptor that connects to a data store at location using the credentials to get access.
static FileSystem	create(java.lang.String adaptor, java.lang.String location, Credential credential, java.util.Map<java.lang.String,java.lang.String> properties)	Create a new FileSystem using the adaptor that connects to a data store at location using the credentials to get access.
void	createDirectories(Path dir)	Creates a new directory, failing if the directory already exists.
abstract void	createDirectory(Path dir)	Creates a new directory, failing if the directory already exists.
abstract void	createFile(Path file)	Creates a new empty file, failing if the file already exists.
abstract void	createSymbolicLink(Path link, Path target)	Creates a new symbolic link, failing if the link already exists (optional operation).
void	delete(Path path, boolean recursive)	Deletes an existing path.
boolean	equals(java.lang.Object o)
abstract boolean	exists(Path path)	Tests if a path exists.
static FileSystemAdaptorDescription	getAdaptorDescription(java.lang.String adaptorName)	Gives the description of the adaptor with the given name.
static FileSystemAdaptorDescription[]	getAdaptorDescriptions()	Gives a list of the descriptions of the available adaptors.
java.lang.String	getAdaptorName()	Get the name of the adaptor that created this FileSystem.
static java.lang.String[]	getAdaptorNames()	Gives a list names of the available adaptors.
abstract PathAttributes	getAttributes(Path path)	Get the PathAttributes of an existing path.
Credential	getCredential()	Get the credential that this FileSystem is using.
java.lang.String	getLocation()	Get the location of the FileSystem.
java.lang.String	getPathSeparator()	Get the path separator used by this file system.
java.util.Map<java.lang.String,java.lang.String>	getProperties()	Get the properties used to create this FileSystem.
CopyStatus	getStatus(java.lang.String copyIdentifier)	Retrieve the status of an copy.
Path	getWorkingDirectory()	Get the current working directory of this file system.
int	hashCode()
abstract boolean	isOpen()	Return if the connection to the FileSystem is open.
java.lang.Iterable<PathAttributes>	list(Path dir, boolean recursive)	List all entries in the directory dir.
abstract java.io.InputStream	readFromFile(Path file)	Open an existing file and return an InputStream to read from this file.
abstract Path	readSymbolicLink(Path link)	Reads the target of a symbolic link (optional operation).
abstract void	rename(Path source, Path target)	Rename an existing source path to a non-existing target path (optional operation).
abstract void	setPosixFilePermissions(Path path, java.util.Set<PosixFilePermission> permissions)	Sets the POSIX permissions of a path (optional operation).
void	setWorkingDirectory(Path directory)	Set the current working directory of this file system to directory.
CopyStatus	waitUntilDone(java.lang.String copyIdentifier, long timeout)	Wait until a copy operation is done or until a timeout expires.
abstract java.io.OutputStream	writeToFile(Path file)	Open a file and return an OutputStream to write to this file.
abstract java.io.OutputStream	writeToFile(Path path, long size)	Open a file and return an OutputStream to write to this file.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

getAdaptorNames

public static java.lang.String[] getAdaptorNames()

Gives a list names of the available adaptors.

Returns:

the list

getAdaptorDescription

public static FileSystemAdaptorDescription getAdaptorDescription(java.lang.String adaptorName)
                                                          throws UnknownAdaptorException

Gives the description of the adaptor with the given name.

Parameters:

adaptorName - the type of file system to connect to (e.g. "sftp" or "webdav")

Returns:

the description

Throws:

UnknownAdaptorException - If the adaptor name is absent in getAdaptorNames().

getAdaptorDescriptions

public static FileSystemAdaptorDescription[] getAdaptorDescriptions()

Gives a list of the descriptions of the available adaptors.

Returns:

the list

create

public static FileSystem create(java.lang.String adaptor,
                                java.lang.String location,
                                Credential credential,
                                java.util.Map<java.lang.String,java.lang.String> properties)
                         throws XenonException

Create a new FileSystem using the adaptor that connects to a data store at location using the credentials to get access. Use properties to (optionally) configure the FileSystem when it is created. Make sure to always close FileSystem instances by calling close(FileSystem) when you no longer need them, otherwise their associated resources remain allocated.

Parameters:

adaptor - the type of file system to connect to (e.g. "sftp" or "webdav")

location - the location of the FileSystem.

credential - the Credentials to use to get access to the FileSystem.

properties - optional properties to use when creating the FileSystem.

Returns:

the new FileSystem.

Throws:

UnknownPropertyException - If a unknown property was provided.

InvalidPropertyException - If a known property was provided with an invalid value.

UnknownAdaptorException - If the adaptor was invalid.

InvalidLocationException - If the location was invalid.

InvalidCredentialException - If the credential is invalid to access the location.

XenonException - If the creation of the FileSystem failed.

java.lang.IllegalArgumentException - If adaptor is null.

See Also:

Documentation on the supported adaptors and locations.

create

public static FileSystem create(java.lang.String adaptor,
                                java.lang.String location,
                                Credential credential)
                         throws XenonException

Create a new FileSystem using the adaptor that connects to a data store at location using the credentials to get access. Make sure to always close FileSystem instances by calling close(FileSystem) when you no longer need them, otherwise their associated resources remain allocated.

Parameters:

adaptor - the type of file system to connect to (e.g. "sftp" or "webdav")

location - the location of the FileSystem.

credential - the Credentials to use to get access to the FileSystem.

Returns:

the new FileSystem.

Throws:

UnknownPropertyException - If a unknown property was provided.

InvalidPropertyException - If a known property was provided with an invalid value.

UnknownAdaptorException - If the adaptor was invalid.

InvalidLocationException - If the location was invalid.

InvalidCredentialException - If the credential is invalid to access the location.

XenonException - If the creation of the FileSystem failed.

java.lang.IllegalArgumentException - If adaptor is null.

See Also:

Documentation on the supported adaptors and locations.

create

public static FileSystem create(java.lang.String adaptor,
                                java.lang.String location)
                         throws XenonException

Create a new FileSystem using the adaptor that connects to a data store at location using the default credentials to get access. Make sure to always close FileSystem instances by calling close(FileSystem) when you no longer need them, otherwise their associated resources remain allocated.

Parameters:

adaptor - the type of file system to connect to (e.g. "sftp" or "webdav")

location - the location of the FileSystem.

Returns:

the new FileSystem.

Throws:

UnknownPropertyException - If a unknown property was provided.

InvalidPropertyException - If a known property was provided with an invalid value.

UnknownAdaptorException - If the adaptor was invalid.

InvalidLocationException - If the location was invalid.

InvalidCredentialException - If the credential is invalid to access the location.

XenonException - If the creation of the FileSystem failed.

java.lang.IllegalArgumentException - If adaptor is null.

See Also:

Documentation on the supported adaptors and locations.

create

public static FileSystem create(java.lang.String adaptor)
                         throws XenonException

Create a new FileSystem using the adaptor that connects to a data store at the default location using the default credentials to get access. Note that there are very few filesystem adaptors that support a default location. The local filesystem adaptor is the prime example. Make sure to always close FileSystem instances by calling close(FileSystem) when you no longer need them, otherwise their associated resources remain allocated.

Parameters:

adaptor - the type of file system to connect to (e.g. "sftp" or "webdav")

Returns:

the new FileSystem.

Throws:

UnknownPropertyException - If a unknown property was provided.

InvalidPropertyException - If a known property was provided with an invalid value.

UnknownAdaptorException - If the adaptor was invalid.

InvalidLocationException - If the location was invalid.

InvalidCredentialException - If the credential is invalid to access the location.

XenonException - If the creation of the FileSystem failed.

java.lang.IllegalArgumentException - If adaptor is null.

See Also:

Documentation on the supported adaptors and locations.

getAdaptorName

public java.lang.String getAdaptorName()

Get the name of the adaptor that created this FileSystem.

Returns:

the name of the adaptor.

getLocation

public java.lang.String getLocation()

Get the location of the FileSystem.

Returns:

the location of the FileSystem.

getCredential

public Credential getCredential()

Get the credential that this FileSystem is using.

Returns:

the credential this FileSystem is using.

getProperties

public java.util.Map<java.lang.String,java.lang.String> getProperties()

Get the properties used to create this FileSystem.

Returns:

the properties used to create this FileSystem.

getWorkingDirectory

public Path getWorkingDirectory()

Get the current working directory of this file system. All relative paths provided to FileSystem methods are resolved against this current working directory. The current working directory is set when a FileSystem is created using the path specified in the location. If no path is specified in the location, an adaptor specific default path is used, for example "/home/username".

Returns:

the current working directory of this file system.

getPathSeparator

public java.lang.String getPathSeparator()

Get the path separator used by this file system. The path separator is set when a FileSystem is created.

Returns:

the path separator used by this file system.

setWorkingDirectory

public void setWorkingDirectory(Path directory)
                         throws XenonException

Set the current working directory of this file system to directory. The provided directory must exist and be a directory. Both an absolute or relative path may be provided. In the latter case, the path will be resolved against the current working directory.

Parameters:

directory - a path to which the current working directory must be set.

Throws:

NoSuchPathException - if the directory does not exist

InvalidPathException - if directory is not a directory

nl.esciencecenter.xenon.adaptors.NotConnectedException - if file system is closed.

java.lang.IllegalArgumentException - if the argument is null.

XenonException - if an I/O error occurred

close

public void close()
           throws XenonException

Close this FileSystem. If the adaptor does not support closing this is a no-op.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

XenonException - If the FileSystem failed to close or if an I/O error occurred.

isOpen

public abstract boolean isOpen()
                        throws XenonException

Return if the connection to the FileSystem is open. An adaptor which does not support closing is always open.

Returns:

if the connection to the FileSystem is open.

Throws:

XenonException - if the test failed or an I/O error occurred.

rename

public abstract void rename(Path source,
                            Path target)
                     throws XenonException

Rename an existing source path to a non-existing target path (optional operation).

This method only implements a rename operation, not a move operation. Hence, this method will not copy files and should return (almost) instantaneously. The parent of the target path (e.g. target.getParent) must exist. If the target is equal to the source this method has no effect. If the source is a link, the link itself will be renamed, not the path to which it refers. If the source is a directory, it will be renamed to the target. This implies that a moving a directory between physical locations may fail.

Parameters:

source - the existing source path.

target - the non existing target path.

Throws:

UnsupportedOperationException - If the adapter does not support renaming.

NoSuchPathException - If the source file does not exist or the target parent directory does not exist.

PathAlreadyExistsException - If the target file already exists.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - If the move failed.

java.lang.IllegalArgumentException - If one or both of the arguments are null.

createDirectories

public void createDirectories(Path dir)
                       throws XenonException

Creates a new directory, failing if the directory already exists. All nonexistent parent directories are also created.

Parameters:

dir - the directory to create.

Throws:

PathAlreadyExistsException - If the directory already exists or if a parent directory could not be created because a file with the same name already exists.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - If an I/O error occurred.

java.lang.IllegalArgumentException - If one or both of the arguments are null.

createDirectory

public abstract void createDirectory(Path dir)
                              throws XenonException

Creates a new directory, failing if the directory already exists. The parent directory of the file must already exists.

Parameters:

dir - the directory to create.

Throws:

PathAlreadyExistsException - If the directory already exists.

NoSuchPathException - If the parent directory does not exist.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - If an I/O error occurred.

java.lang.IllegalArgumentException - If the argument is null.

createFile

public abstract void createFile(Path file)
                         throws XenonException

Creates a new empty file, failing if the file already exists. The parent directory of the file must already exists.

Parameters:

file - a path referring to the file to create.

Throws:

PathAlreadyExistsException - If the file already exists.

NoSuchPathException - If the parent directory does not exist.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - If an I/O error occurred.

java.lang.IllegalArgumentException - If one or both of the arguments are null.

createSymbolicLink

public abstract void createSymbolicLink(Path link,
                                        Path target)
                                 throws XenonException

Creates a new symbolic link, failing if the link already exists (optional operation). The target is taken as is. It may be absolute, relative path and/or non-normalized path and may or may not exist.

Parameters:

link - the symbolic link to create.

target - the target the symbolic link should refer to.

Throws:

PathAlreadyExistsException - If the link already exists.

NoSuchPathException - If the target or parent directory of link does not exist

InvalidPathException - If parent of link is not a directory

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - If an I/O error occurred.

java.lang.IllegalArgumentException - If one or both of the arguments are null.

delete

public void delete(Path path,
                   boolean recursive)
            throws XenonException

Deletes an existing path. If path is a symbolic link the symbolic link is removed and the symbolic link's target is not deleted. If the path is a directory and recursive is set to true, the contents of the directory will also be deleted. If recursive is set to false, a directory will only be removed if it is empty.

Parameters:

path - the path to delete.

recursive - if the delete must be done recursively

Throws:

DirectoryNotEmptyException - if the directory was not empty (and the delete was not recursive).

NoSuchPathException - if the provided path does not exist.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

exists

public abstract boolean exists(Path path)
                        throws XenonException

Tests if a path exists.

Parameters:

path - the path to test.

Returns:

If the path exists.

Throws:

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

list

public java.lang.Iterable<PathAttributes> list(Path dir,
                                               boolean recursive)
                                        throws XenonException

List all entries in the directory dir. All entries in the directory are returned, but subdirectories will not be traversed by default. Set recursive to true, include the listing of all subdirectories. Symbolic links are not followed.

Parameters:

dir - the target directory.

recursive - should the list recursively traverse the subdirectories ?

Returns:

a List of PathAttributes that iterates over all entries in the directory dir.

Throws:

NoSuchPathException - If a directory does not exists.

InvalidPathException - If dir is not a directory.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

readFromFile

public abstract java.io.InputStream readFromFile(Path file)
                                          throws XenonException

Open an existing file and return an InputStream to read from this file.

Parameters:

file - the to read.

Returns:

the InputStream to read from the file.

Throws:

NoSuchPathException - If the file does not exists.

InvalidPathException - If the file is not regular file.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

writeToFile

public abstract java.io.OutputStream writeToFile(Path path,
                                                 long size)
                                          throws XenonException

Open a file and return an OutputStream to write to this file.

The size of the file (once all data has been written) must be specified using the size parameter. This is required by some implementations (typically blob-stores).

Parameters:

path - the target file for the OutputStream.

size - the size of the file once fully written.

Returns:

the OutputStream to write to the file.

Throws:

PathAlreadyExistsException - If the target existed.

NoSuchPathException - if a parent directory does not exist.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

writeToFile

public abstract java.io.OutputStream writeToFile(Path file)
                                          throws XenonException

Open a file and return an OutputStream to write to this file. (optional operation)

If the file already exists it will be replaced and its data will be lost. The amount of data that will be written to the file is not specified in advance. This operation may not be supported by all implementations.

Parameters:

file - the target file for the OutputStream.

Returns:

the OutputStream to write to the file.

Throws:

PathAlreadyExistsException - If the target existed.

NoSuchPathException - if a parent directory does not exist.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

appendToFile

public abstract java.io.OutputStream appendToFile(Path file)
                                           throws XenonException

Open an existing file and return an OutputStream to append data to this file. (optional operation)

If the file does not exist, an exception will be thrown. This operation may not be supported by all implementations.

Parameters:

file - the target file for the OutputStream.

Returns:

the OutputStream to write to the file.

Throws:

PathAlreadyExistsException - If the target existed.

NoSuchPathException - if a parent directory does not exist.

InvalidPathException - if not a regular file

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

UnsupportedOperationException - if the adaptor does not support appending

getAttributes

public abstract PathAttributes getAttributes(Path path)
                                      throws XenonException

Get the PathAttributes of an existing path.

Parameters:

path - the existing path.

Returns:

the FileAttributes of the path.

Throws:

NoSuchPathException - If the file does not exists.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

readSymbolicLink

public abstract Path readSymbolicLink(Path link)
                               throws XenonException

Reads the target of a symbolic link (optional operation).

Parameters:

link - the link to read.

Returns:

a Path representing the target of the link.

Throws:

NoSuchPathException - If the link does not exists.

InvalidPathException - If the source is not a link.

UnsupportedOperationException - If this FileSystem does not support symbolic links.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

setPosixFilePermissions

public abstract void setPosixFilePermissions(Path path,
                                             java.util.Set<PosixFilePermission> permissions)
                                      throws XenonException

Sets the POSIX permissions of a path (optional operation).

Parameters:

path - the target path.

permissions - the permissions to set.

Throws:

NoSuchPathException - If the target path does not exists.

UnsupportedOperationException - If this FileSystem does not support symbolic links.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If path is null.

copy

public java.lang.String copy(Path source,
                             FileSystem destinationFS,
                             Path destination,
                             CopyMode mode,
                             boolean recursive)

Asynchronously Copy an existing source path to a target path on a different file system. If the source path is a file, it will be copied to the destination file on the target file system. If the source path is a directory, it will only be copied if recursive is set to true. Otherwise, an exception will be thrown. When copying recursively, the directory and its content (both files and subdirectories with content), will be copied to destination. Exceptions that occur during copying will not be thrown by this function, but instead are contained in a CopyStatus object which can be obtained with getStatus(String)

Parameters:

source - the source path (on this filesystem) to copy from.

destinationFS - the destination filesystem to copy to.

destination - the destination path (on the destination filesystem) to copy to.

mode - how to react if the destination already exists.

recursive - if the copy should be recursive.

Returns:

a String that identifies this copy and be used to inspect its progress.

Throws:

java.lang.IllegalArgumentException - If source, destinationFS, destination or mode is null.

cancel

public CopyStatus cancel(java.lang.String copyIdentifier)
                  throws XenonException

Cancel a copy operation. Afterwards, the copy is forgotten and subsequent queries with this copy string will lead to NoSuchCopyException

Parameters:

copyIdentifier - the identifier of the copy operation which to cancel.

Returns:

a CopyStatus containing the status of the copy.

Throws:

NoSuchCopyException - If the copy is not known.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If the copyIdentifier is null.

waitUntilDone

public CopyStatus waitUntilDone(java.lang.String copyIdentifier,
                                long timeout)
                         throws XenonException

Wait until a copy operation is done or until a timeout expires.

This method will wait until a copy operation is done (either gracefully or by producing an error), or until the timeout expires, whichever comes first. If the timeout expires, the copy operation will continue to run.

The timeout is in milliseconds and must be >= 0. When timeout is 0, it will be ignored and this method will wait until the copy operation is done.

After this operation, the copy is forgotten and subsequent queries with this copy string will lead to NoSuchCopyException

A CopyStatus is returned that can be used to determine why the call returned.

Parameters:

copyIdentifier - the identifier of the copy operation to wait for.

timeout - the maximum time to wait for the copy operation in milliseconds.

Returns:

a CopyStatus containing the status of the copy.

Throws:

java.lang.IllegalArgumentException - If argument is illegal.

NoSuchCopyException - If the copy handle is not known.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If the copyIdentifier is null or if the value of timeout is negative.

getStatus

public CopyStatus getStatus(java.lang.String copyIdentifier)
                     throws XenonException

Retrieve the status of an copy. After obtaining the status of a completed copy, the copy is forgotten and subsequent queries with this copy string will lead to NoSuchCopyException.

Parameters:

copyIdentifier - the identifier of the copy for which to retrieve the status.

Returns:

a CopyStatus containing the status of the asynchronous copy.

Throws:

NoSuchCopyException - If the copy is not known.

nl.esciencecenter.xenon.adaptors.NotConnectedException - If file system is closed.

XenonException - if an I/O error occurred.

java.lang.IllegalArgumentException - If the copyIdentifier is null.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object