Module com.github.robtimus.filesystems.sftp

Package com.github.robtimus.filesystems.sftp

Class SFTPFileSystemProvider

java.lang.Object

java.nio.file.spi.FileSystemProvider

com.github.robtimus.filesystems.sftp.SFTPFileSystemProvider

public class SFTPFileSystemProvider
extends FileSystemProvider

A provider for SFTP file systems.

Author:

Rob Spoor

Constructor Summary

Constructors

Constructor	Description
SFTPFileSystemProvider()

Method Summary

Modifier and Type	Method	Description
void	checkAccess(Path path, AccessMode... modes)
void	copy(Path source, Path target, CopyOption... options)	Copy a file to a target file.
void	createDirectory(Path dir, FileAttribute<?>... attrs)	Creates a new directory.
void	delete(Path path)
<V extends FileAttributeView> V	getFileAttributeView(Path path, Class<V> type, LinkOption... options)	Returns a file attribute view of a given type.
FileStore	getFileStore(Path path)
FileSystem	getFileSystem(URI uri)	Returns an existing FileSystem created by this provider.
Path	getPath(URI uri)	Return a Path object by converting the given URI.
String	getScheme()	Returns the URI scheme that identifies this provider: sftp.
boolean	isHidden(Path path)
boolean	isSameFile(Path path, Path path2)
static void	keepAlive(FileSystem fs)	Send a keep-alive signal for an SFTP file system.
void	move(Path source, Path target, CopyOption... options)	Move or rename a file to a target file.
SeekableByteChannel	newByteChannel(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs)	Opens or creates a file, returning a seekable byte channel to access the file.
DirectoryStream<Path>	newDirectoryStream(Path dir, DirectoryStream.Filter<? super Path> filter)
FileSystem	newFileSystem(URI uri, Map<String,?> env)	Constructs a new FileSystem object identified by a URI.
InputStream	newInputStream(Path path, OpenOption... options)	Opens a file, returning an input stream to read from the file.
OutputStream	newOutputStream(Path path, OpenOption... options)	Opens or creates a file, returning an output stream that may be used to write bytes to the file.
<A extends BasicFileAttributes> A	readAttributes(Path path, Class<A> type, LinkOption... options)	Reads a file's attributes as a bulk operation.
Map<String,Object>	readAttributes(Path path, String attributes, LinkOption... options)	Reads a set of file attributes as a bulk operation.
Path	readSymbolicLink(Path link)
void	setAttribute(Path path, String attribute, Object value, LinkOption... options)	Sets the value of a file attribute.

Methods inherited from class java.nio.file.spi.FileSystemProvider

createLink, createSymbolicLink, deleteIfExists, installedProviders, newAsynchronousFileChannel, newFileChannel, newFileSystem

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SFTPFileSystemProvider

public SFTPFileSystemProvider()

Method Detail

getScheme

public String getScheme()

Returns the URI scheme that identifies this provider: sftp.

Specified by:

getScheme in class FileSystemProvider

newFileSystem

public FileSystem newFileSystem(URI uri,
                                Map<String,?> env)
                         throws IOException

Constructs a new FileSystem object identified by a URI.

The URI must have a scheme equal to getScheme(), and no query or fragment. Authentication credentials can be set either through the URI's user information, or through the given environment map, preferably through SFTPEnvironment. The default directory can be set either through the URI's path or through the given environment map, preferably through SFTPEnvironment.

This provider allows multiple file systems per host, but only one file system per user on a host. Once a file system is closed, this provider allows a new file system to be created with the same URI and credentials as the closed file system.

Specified by:

newFileSystem in class FileSystemProvider

Throws:

IOException

getFileSystem

public FileSystem getFileSystem(URI uri)

Returns an existing FileSystem created by this provider.

The URI must have a scheme equal to getScheme(), and no non-empty path, query or fragment. Because the original credentials were possibly provided through an environment map, the URI can contain user information, although this should not contain a password for security reasons.

Once a file system is closed, this provider will throw a FileSystemNotFoundException.

Specified by:

getFileSystem in class FileSystemProvider

getPath

public Path getPath(URI uri)

Return a Path object by converting the given URI. The resulting Path is associated with a FileSystem that already exists or is constructed automatically.

The URI must have a scheme equal to getScheme(), and no fragment. Because the original credentials were possibly provided through an environment map, the URI can contain user information, although for security reasons this should only contain a password to support automatically creating file systems.

If no matching file system existed yet, a new one is created. The default environment is used for this, to allow configuring the resulting file system. URI specific settings can also be provided through the query; see usages of SFTPEnvironment.QueryParam and SFTPEnvironment.QueryParams for the possible query parameters.

Remember to close any newly created file system.

Specified by:

getPath in class FileSystemProvider

newInputStream

public InputStream newInputStream(Path path,
                                  OpenOption... options)
                           throws IOException

Opens a file, returning an input stream to read from the file. This method works in exactly the manner specified by the Files.newInputStream(Path, OpenOption...) method.

Note: while the returned input stream is not closed, the path's file system will have one available connection fewer. It is therefore essential that the input stream is closed as soon as possible.

Overrides:

newInputStream in class FileSystemProvider

Throws:

IOException

newOutputStream

public OutputStream newOutputStream(Path path,
                                    OpenOption... options)
                             throws IOException

Opens or creates a file, returning an output stream that may be used to write bytes to the file. This method works in exactly the manner specified by the Files.newOutputStream(Path, OpenOption...) method.

Note: while the returned output stream is not closed, the path's file system will have one available connection fewer. It is therefore essential that the output stream is closed as soon as possible.

Overrides:

newOutputStream in class FileSystemProvider

Throws:

IOException

newByteChannel

public SeekableByteChannel newByteChannel(Path path,
                                          Set<? extends OpenOption> options,
                                          FileAttribute<?>... attrs)
                                   throws IOException

Opens or creates a file, returning a seekable byte channel to access the file. This method works in exactly the manner specified by the Files.newByteChannel(Path, Set, FileAttribute...) method.

This method does not support any file attributes to be set. If any file attributes are given, an UnsupportedOperationException will be thrown.

Note: while the returned channel is not closed, the path's file system will have one available connection fewer. It is therefore essential that the channel is closed as soon as possible.

Specified by:

newByteChannel in class FileSystemProvider

Throws:

IOException

newDirectoryStream

public DirectoryStream<Path> newDirectoryStream(Path dir,
                                                DirectoryStream.Filter<? super Path> filter)
                                         throws IOException

Specified by:

newDirectoryStream in class FileSystemProvider

Throws:

IOException

createDirectory

public void createDirectory(Path dir,
                            FileAttribute<?>... attrs)
                     throws IOException

Creates a new directory. This method works in exactly the manner specified by the Files.createDirectory(Path, FileAttribute...) method.

This method does not support any file attributes to be set. If any file attributes are given, an UnsupportedOperationException will be thrown.

Specified by:

createDirectory in class FileSystemProvider

Throws:

IOException

delete

public void delete(Path path)
            throws IOException

Specified by:

delete in class FileSystemProvider

Throws:

IOException

readSymbolicLink

public Path readSymbolicLink(Path link)
                      throws IOException

Overrides:

readSymbolicLink in class FileSystemProvider

Throws:

IOException

copy

public void copy(Path source,
                 Path target,
                 CopyOption... options)
          throws IOException

Copy a file to a target file. This method works in exactly the manner specified by the Files.copy(Path, Path, CopyOption...) method except that both the source and target paths must be associated with this provider.

Most of the standard copy options are supported. StandardCopyOption.COPY_ATTRIBUTES and StandardCopyOption.ATOMIC_MOVE are not supported though.

Specified by:

copy in class FileSystemProvider

Throws:

IOException

move

public void move(Path source,
                 Path target,
                 CopyOption... options)
          throws IOException

Move or rename a file to a target file. This method works in exactly the manner specified by the Files.move(Path, Path, CopyOption...) method except that both the source and target paths must be associated with this provider.

Most of the standard copy options are supported. StandardCopyOption.COPY_ATTRIBUTES is not supported though. StandardCopyOption.ATOMIC_MOVE is only supported if the paths have the same file system.

Specified by:

move in class FileSystemProvider

Throws:

IOException

isSameFile

public boolean isSameFile(Path path,
                          Path path2)
                   throws IOException

Specified by:

isSameFile in class FileSystemProvider

Throws:

IOException

isHidden

public boolean isHidden(Path path)
                 throws IOException

Specified by:

isHidden in class FileSystemProvider

Throws:

IOException

getFileStore

public FileStore getFileStore(Path path)
                       throws IOException

Specified by:

getFileStore in class FileSystemProvider

Throws:

IOException

checkAccess

public void checkAccess(Path path,
                        AccessMode... modes)
                 throws IOException

Specified by:

checkAccess in class FileSystemProvider

Throws:

IOException

getFileAttributeView

public <V extends FileAttributeView> V getFileAttributeView(Path path,
                                                            Class<V> type,
                                                            LinkOption... options)

Returns a file attribute view of a given type. This method works in exactly the manner specified by the Files.getFileAttributeView(Path, Class, LinkOption...) method.

This provider supports BasicFileAttributeView, FileOwnerAttributeView and PosixFileAttributeView. All other classes will result in a null return value.

Note: if the type is BasicFileAttributeView or a sub type, the last access time and creation time must be null when calling BasicFileAttributeView.setTimes(FileTime, FileTime, FileTime), otherwise an exception will be thrown. When setting the owner or group for the path, the name must be the UID/GID of the owner/group.

Specified by:

getFileAttributeView in class FileSystemProvider

readAttributes

public <A extends BasicFileAttributes> A readAttributes(Path path,
                                                        Class<A> type,
                                                        LinkOption... options)
                                                 throws IOException

Reads a file's attributes as a bulk operation. This method works in exactly the manner specified by the Files.readAttributes(Path, Class, LinkOption...) method.

This provider supports BasicFileAttributes and PosixFileAttributes (there is no FileOwnerFileAttributes). All other classes will result in an UnsupportedOperationException to be thrown.

Specified by:

readAttributes in class FileSystemProvider

Throws:

IOException

readAttributes

public Map<String,Object> readAttributes(Path path,
                                               String attributes,
                                               LinkOption... options)
                                        throws IOException

Reads a set of file attributes as a bulk operation. This method works in exactly the manner specified by the Files.readAttributes(Path, String, LinkOption...) method.

This provider supports views basic, owner and posix, where basic will be used if no view is given. All other views will result in an UnsupportedOperationException to be thrown.

Specified by:

readAttributes in class FileSystemProvider

Throws:

IOException

setAttribute

public void setAttribute(Path path,
                         String attribute,
                         Object value,
                         LinkOption... options)
                  throws IOException

Sets the value of a file attribute. This method works in exactly the manner specified by the Files.setAttribute(Path, String, Object, LinkOption...) method.

This provider supports views basic, owner and posix, where basic will be used if no view is given. All other views will result in an UnsupportedOperationException to be thrown.

Note: updating the last access time or creation time is not supported. When setting the owner or group for the path, the name must be the UID/GID of the owner/group.

Specified by:

setAttribute in class FileSystemProvider

Throws:

IOException

keepAlive

public static void keepAlive(FileSystem fs)
                      throws IOException

Send a keep-alive signal for an SFTP file system.

Parameters:

fs - The SFTP file system to send a keep-alive signal for.

Throws:

ProviderMismatchException - If the given file system is not an SFTP file system (not created by an SFTPFileSystemProvider).

IOException - If an I/O error occurred.