org.apache.sshd.sftp.server

Interface SftpFileSystemAccessor

public interface SftpFileSystemAccessor

Field Summary

Fields

Modifier and Type	Field and Description
static SftpFileSystemAccessor	DEFAULT
static boolean	DEFAULT_AUTO_SYNC_FILE_ON_CLOSE Default value for "sftp-auto-fsync-on-close" if none set
static java.util.List<java.lang.String>	DEFAULT_UNIX_VIEW
static java.util.NavigableMap<java.lang.String,FileInfoExtractor<?>>	FILEATTRS_RESOLVERS A case insensitive NavigableMap of FileInfoExtractors to be used to complete attributes that are deemed important enough to warrant an extra effort if not accessible via the file system attributes views
static java.lang.String	PROP_AUTO_SYNC_FILE_ON_CLOSE Whether to invoke FileChannel.force(boolean) on files open for write when closing

Method Summary

Modifier and Type	Method and Description
default void	applyExtensionFileAttributes(SftpSubsystemProxy subsystem, java.nio.file.Path file, java.util.Map<java.lang.String,byte[]> extensions, java.nio.file.LinkOption... options) Invoked in order to allow processing of custom file attributes
default void	closeDirectory(SftpSubsystemProxy subsystem, DirectoryHandle dirHandle, java.nio.file.Path dir, java.lang.String handle, java.nio.file.DirectoryStream<java.nio.file.Path> ds) Called when a directory stream is no longer required
default void	closeFile(SftpSubsystemProxy subsystem, FileHandle fileHandle, java.nio.file.Path file, java.lang.String handle, java.nio.channels.Channel channel, java.util.Set<? extends java.nio.file.OpenOption> options) Called to inform the accessor that it should close the file
default void	copyFile(SftpSubsystemProxy subsystem, java.nio.file.Path src, java.nio.file.Path dst, java.util.Collection<java.nio.file.CopyOption> opts)
default void	createDirectory(SftpSubsystemProxy subsystem, java.nio.file.Path path)
default void	createLink(SftpSubsystemProxy subsystem, java.nio.file.Path link, java.nio.file.Path existing, boolean symLink) Invoked in order to create a link to a path
default java.nio.file.DirectoryStream<java.nio.file.Path>	openDirectory(SftpSubsystemProxy subsystem, DirectoryHandle dirHandle, java.nio.file.Path dir, java.lang.String handle) Called when a new directory stream is requested
default java.nio.channels.SeekableByteChannel	openFile(SftpSubsystemProxy subsystem, FileHandle fileHandle, java.nio.file.Path file, java.lang.String handle, java.util.Set<? extends java.nio.file.OpenOption> options, java.nio.file.attribute.FileAttribute<?>... attrs) Called whenever a new file is opened
default void	putRemoteFileName(SftpSubsystemProxy subsystem, java.nio.file.Path path, Buffer buf, java.lang.String name, boolean shortName) Invoked in order to encode the outgoing referenced file name/path
default java.util.Map<java.lang.String,?>	readFileAttributes(SftpSubsystemProxy subsystem, java.nio.file.Path file, java.lang.String view, java.nio.file.LinkOption... options) Invoked when required to retrieve file attributes for a specific file system view
default void	removeFile(SftpSubsystemProxy subsystem, java.nio.file.Path path, boolean isDirectory)
default void	renameFile(SftpSubsystemProxy subsystem, java.nio.file.Path oldPath, java.nio.file.Path newPath, java.util.Collection<java.nio.file.CopyOption> opts)
default java.nio.file.LinkOption[]	resolveFileAccessLinkOptions(SftpSubsystemProxy subsystem, java.nio.file.Path file, int cmd, java.lang.String extension, boolean followLinks) Invoked in order to determine the symbolic link follow options
default java.nio.file.attribute.UserPrincipal	resolveFileOwner(SftpSubsystemProxy subsystem, java.nio.file.Path file, java.nio.file.attribute.UserPrincipal name)
default java.nio.file.attribute.GroupPrincipal	resolveGroupOwner(SftpSubsystemProxy subsystem, java.nio.file.Path file, java.nio.file.attribute.GroupPrincipal name)
default java.lang.String	resolveLinkTarget(SftpSubsystemProxy subsystem, java.nio.file.Path link)
default java.nio.file.Path	resolveLocalFilePath(SftpSubsystemProxy subsystem, java.nio.file.Path rootDir, java.lang.String remotePath) Invoked in order to resolve remote file paths reference by the client into ones accessible by the server
default java.util.NavigableMap<java.lang.String,java.lang.Object>	resolveReportedFileAttributes(SftpSubsystemProxy subsystem, java.nio.file.Path file, int flags, java.util.NavigableMap<java.lang.String,java.lang.Object> attrs, java.nio.file.LinkOption... options) Invoked in order to allow intervention to the reported file attributes - e.g., add custom/extended properties
default void	setFileAccessControl(SftpSubsystemProxy subsystem, java.nio.file.Path file, java.util.List<java.nio.file.attribute.AclEntry> acl, java.nio.file.LinkOption... options)
default void	setFileAttribute(SftpSubsystemProxy subsystem, java.nio.file.Path file, java.lang.String view, java.lang.String attribute, java.lang.Object value, java.nio.file.LinkOption... options) Sets a view attribute for a local file
default void	setFileOwner(SftpSubsystemProxy subsystem, java.nio.file.Path file, java.security.Principal value, java.nio.file.LinkOption... options)
default void	setFilePermissions(SftpSubsystemProxy subsystem, java.nio.file.Path file, java.util.Set<java.nio.file.attribute.PosixFilePermission> perms, java.nio.file.LinkOption... options)
default void	setGroupOwner(SftpSubsystemProxy subsystem, java.nio.file.Path file, java.security.Principal value, java.nio.file.LinkOption... options)
default void	syncFileData(SftpSubsystemProxy subsystem, FileHandle fileHandle, java.nio.file.Path file, java.lang.String handle, java.nio.channels.Channel channel) Called when file meta-data re-synchronization is required
default java.nio.channels.FileLock	tryLock(SftpSubsystemProxy subsystem, FileHandle fileHandle, java.nio.file.Path file, java.lang.String handle, java.nio.channels.Channel channel, long position, long size, boolean shared) Called when locking a section of a file is requested

Field Detail

DEFAULT_UNIX_VIEW

static final java.util.List<java.lang.String> DEFAULT_UNIX_VIEW

FILEATTRS_RESOLVERS

static final java.util.NavigableMap<java.lang.String,FileInfoExtractor<?>> FILEATTRS_RESOLVERS

A case insensitive NavigableMap of FileInfoExtractors to be used to complete attributes that are deemed important enough to warrant an extra effort if not accessible via the file system attributes views

PROP_AUTO_SYNC_FILE_ON_CLOSE

static final java.lang.String PROP_AUTO_SYNC_FILE_ON_CLOSE

Whether to invoke FileChannel.force(boolean) on files open for write when closing

See Also:

Constant Field Values

DEFAULT_AUTO_SYNC_FILE_ON_CLOSE

static final boolean DEFAULT_AUTO_SYNC_FILE_ON_CLOSE

Default value for "sftp-auto-fsync-on-close" if none set

See Also:

Constant Field Values

DEFAULT

static final SftpFileSystemAccessor DEFAULT

Method Detail

resolveLocalFilePath

default java.nio.file.Path resolveLocalFilePath(SftpSubsystemProxy subsystem,
                                                java.nio.file.Path rootDir,
                                                java.lang.String remotePath)
                                         throws java.io.IOException,
                                                java.nio.file.InvalidPathException

Invoked in order to resolve remote file paths reference by the client into ones accessible by the server

Parameters:

subsystem - The SFTP subsystem instance that manages the session

rootDir - The default root directory used to resolve relative paths - a.k.a. the chroot location

remotePath - The remote path - separated by '/'

Returns:

The local Path

Throws:

java.io.IOException - If failed to resolve the local path

java.nio.file.InvalidPathException - If bad local path specification

See Also:

SftpSubsystemEnvironment#getDefaultDirectory()

resolveFileAccessLinkOptions

default java.nio.file.LinkOption[] resolveFileAccessLinkOptions(SftpSubsystemProxy subsystem,
                                                                java.nio.file.Path file,
                                                                int cmd,
                                                                java.lang.String extension,
                                                                boolean followLinks)
                                                         throws java.io.IOException

Invoked in order to determine the symbolic link follow options

Parameters:

subsystem - The SFTP subsystem instance that manages the session

file - The referenced file

cmd - The SFTP command that triggered this access

extension - The SFTP extension that triggered this access - non-empty only for {SSH_FXP_EXTENDED} command

followLinks - Whether to follow symbolic links

Returns:

The LinkOption-s to use - invokes IoUtils.getLinkOptions(boolean) by default

Throws:

java.io.IOException - if failed to resolve the required options

See Also:

SSHD-1137

resolveReportedFileAttributes

default java.util.NavigableMap<java.lang.String,java.lang.Object> resolveReportedFileAttributes(SftpSubsystemProxy subsystem,
                                                                                                java.nio.file.Path file,
                                                                                                int flags,
                                                                                                java.util.NavigableMap<java.lang.String,java.lang.Object> attrs,
                                                                                                java.nio.file.LinkOption... options)
                                                                                         throws java.io.IOException

Invoked in order to allow intervention to the reported file attributes - e.g., add custom/extended properties

Parameters:

subsystem - The SFTP subsystem instance that manages the session

file - The referenced file

flags - A mask of the original required attributes

attrs - The default resolved attributes map

options - The LinkOption-s that were used to access the file's attributes

Returns:

The updated attributes map

Throws:

java.io.IOException - If failed to resolve the attributes

See Also:

SSHD-1226

applyExtensionFileAttributes

default void applyExtensionFileAttributes(SftpSubsystemProxy subsystem,
                                          java.nio.file.Path file,
                                          java.util.Map<java.lang.String,byte[]> extensions,
                                          java.nio.file.LinkOption... options)
                                   throws java.io.IOException

Invoked in order to allow processing of custom file attributes

Parameters:

subsystem - The SFTP subsystem instance that manages the session

file - The referenced file

extensions - The received extensions - may be null/empty

options - The LinkOption-s that were used to access the file's standard attributes

Throws:

java.io.IOException - If failed to apply the attributes

putRemoteFileName

default void putRemoteFileName(SftpSubsystemProxy subsystem,
                               java.nio.file.Path path,
                               Buffer buf,
                               java.lang.String name,
                               boolean shortName)
                        throws java.io.IOException

Invoked in order to encode the outgoing referenced file name/path

Parameters:

subsystem - The SFTP subsystem instance that manages the session

path - The associated file Path - Note: might be a symbolic link container

buf - The target Buffer for the encoded string

name - The string to send

shortName - If true then this is the "pure" file name/path, otherwise it also contains user/group/size/last-modified-time/etc.

Throws:

java.io.IOException - If failed to resolve the remote name

See Also:

SSHD-1132

openFile

default java.nio.channels.SeekableByteChannel openFile(SftpSubsystemProxy subsystem,
                                                       FileHandle fileHandle,
                                                       java.nio.file.Path file,
                                                       java.lang.String handle,
                                                       java.util.Set<? extends java.nio.file.OpenOption> options,
                                                       java.nio.file.attribute.FileAttribute<?>... attrs)
                                                throws java.io.IOException

Called whenever a new file is opened

Parameters:

subsystem - The SFTP subsystem instance that manages the session

fileHandle - The FileHandle representing the created channel - may be null if not invoked within the context of such a handle (special cases)

file - The requested local file Path - same one returned by resolveLocalFilePath

handle - The assigned file handle through which the remote peer references this file. May be null/empty if the request is due to some internal functionality instead of due to peer requesting a handle to a file.

options - The requested OpenOptions

attrs - The requested FileAttributes

Returns:

The opened SeekableByteChannel

Throws:

java.io.IOException - If failed to open

tryLock

default java.nio.channels.FileLock tryLock(SftpSubsystemProxy subsystem,
                                           FileHandle fileHandle,
                                           java.nio.file.Path file,
                                           java.lang.String handle,
                                           java.nio.channels.Channel channel,
                                           long position,
                                           long size,
                                           boolean shared)
                                    throws java.io.IOException

Called when locking a section of a file is requested

Parameters:

subsystem - The SFTP subsystem instance that manages the session

fileHandle - The FileHandle representing the created channel

file - The requested local file Path - same one returned by resolveLocalFilePath

handle - The assigned file handle through which the remote peer references this file

channel - The original Channel that was returned by openFile(SftpSubsystemProxy, FileHandle, Path, String, Set, FileAttribute...)

position - The position at which the locked region is to start - must be non-negative

size - The size of the locked region; must be non-negative, and the sum position + size must be non-negative

shared - true to request a shared lock, false to request an exclusive lock

Returns:

A lock object representing the newly-acquired lock, or null if the lock could not be acquired because another program holds an overlapping lock

Throws:

java.io.IOException - If failed to honor the request

See Also:

FileChannel.tryLock(long, long, boolean)

syncFileData

default void syncFileData(SftpSubsystemProxy subsystem,
                          FileHandle fileHandle,
                          java.nio.file.Path file,
                          java.lang.String handle,
                          java.nio.channels.Channel channel)
                   throws java.io.IOException

Called when file meta-data re-synchronization is required

Parameters:

subsystem - The SFTP subsystem instance that manages the session

fileHandle - The FileHandle representing the created channel

file - The requested local file Path - same one returned by resolveLocalFilePath

handle - The assigned file handle through which the remote peer references this file

channel - The original Channel that was returned by openFile(SftpSubsystemProxy, FileHandle, Path, String, Set, FileAttribute...)

Throws:

java.io.IOException - If failed to execute the request

See Also:

FileChannel.force(boolean), OpenSSH - section 10

closeFile

default void closeFile(SftpSubsystemProxy subsystem,
                       FileHandle fileHandle,
                       java.nio.file.Path file,
                       java.lang.String handle,
                       java.nio.channels.Channel channel,
                       java.util.Set<? extends java.nio.file.OpenOption> options)
                throws java.io.IOException

Called to inform the accessor that it should close the file

Parameters:

subsystem - The SFTP subsystem instance that manages the session

fileHandle - The FileHandle representing the created channel - may be null if not invoked within the context of such a handle (special cases)

file - The requested local file Path - same one returned by resolveLocalFilePath

handle - The assigned file handle through which the remote peer references this file

channel - The original Channel that was returned by openFile(SftpSubsystemProxy, FileHandle, Path, String, Set, FileAttribute...)

options - The original options used to open the channel

Throws:

java.io.IOException - If failed to execute the request

openDirectory

default java.nio.file.DirectoryStream<java.nio.file.Path> openDirectory(SftpSubsystemProxy subsystem,
                                                                        DirectoryHandle dirHandle,
                                                                        java.nio.file.Path dir,
                                                                        java.lang.String handle)
                                                                 throws java.io.IOException

Called when a new directory stream is requested

Parameters:

subsystem - The SFTP subsystem instance that manages the session

dirHandle - The DirectoryHandle representing the stream

dir - The requested local directory Path - same one returned by resolveLocalFilePath

handle - The assigned directory handle through which the remote peer references this directory

Returns:

The opened DirectoryStream

Throws:

java.io.IOException - If failed to open

closeDirectory

default void closeDirectory(SftpSubsystemProxy subsystem,
                            DirectoryHandle dirHandle,
                            java.nio.file.Path dir,
                            java.lang.String handle,
                            java.nio.file.DirectoryStream<java.nio.file.Path> ds)
                     throws java.io.IOException

Called when a directory stream is no longer required

Parameters:

subsystem - The SFTP subsystem instance that manages the session

dirHandle - The DirectoryHandle representing the stream - may be null if not invoked within the context of such a handle (special cases)

dir - The requested local directory Path - same one returned by resolveLocalFilePath

handle - The assigned directory handle through which the remote peer references this directory

ds - The disposed DirectoryStream

Throws:

java.io.IOException - If failed to open

readFileAttributes

default java.util.Map<java.lang.String,?> readFileAttributes(SftpSubsystemProxy subsystem,
                                                             java.nio.file.Path file,
                                                             java.lang.String view,
                                                             java.nio.file.LinkOption... options)
                                                      throws java.io.IOException

Invoked when required to retrieve file attributes for a specific file system view

Parameters:

subsystem - The SFTP subsystem instance that manages the session

file - The requested local file Path - same one returned by resolveLocalFilePath

view - The required view name

options - The access LinkOption-s

Returns:

A Map of all the attributes available for the file in the view

Throws:

java.io.IOException - If failed to read the attributes

See Also:

Files.readAttributes(Path, String, LinkOption...)

setFileAttribute

default void setFileAttribute(SftpSubsystemProxy subsystem,
                              java.nio.file.Path file,
                              java.lang.String view,
                              java.lang.String attribute,
                              java.lang.Object value,
                              java.nio.file.LinkOption... options)
                       throws java.io.IOException

Sets a view attribute for a local file

Parameters:

subsystem - The SFTP subsystem instance that manages the session

file - The requested local file Path - same one returned by resolveLocalFilePath

view - The required view name

attribute - The attribute name

value - The attribute value

options - The access LinkOption-s

Throws:

java.io.IOException - If failed to set the attribute

resolveFileOwner

default java.nio.file.attribute.UserPrincipal resolveFileOwner(SftpSubsystemProxy subsystem,
                                                               java.nio.file.Path file,
                                                               java.nio.file.attribute.UserPrincipal name)
                                                        throws java.io.IOException

Throws:

java.io.IOException

setFileOwner

default void setFileOwner(SftpSubsystemProxy subsystem,
                          java.nio.file.Path file,
                          java.security.Principal value,
                          java.nio.file.LinkOption... options)
                   throws java.io.IOException

Throws:

java.io.IOException

resolveGroupOwner

default java.nio.file.attribute.GroupPrincipal resolveGroupOwner(SftpSubsystemProxy subsystem,
                                                                 java.nio.file.Path file,
                                                                 java.nio.file.attribute.GroupPrincipal name)
                                                          throws java.io.IOException

Throws:

java.io.IOException

setGroupOwner

default void setGroupOwner(SftpSubsystemProxy subsystem,
                           java.nio.file.Path file,
                           java.security.Principal value,
                           java.nio.file.LinkOption... options)
                    throws java.io.IOException

Throws:

java.io.IOException

setFilePermissions

default void setFilePermissions(SftpSubsystemProxy subsystem,
                                java.nio.file.Path file,
                                java.util.Set<java.nio.file.attribute.PosixFilePermission> perms,
                                java.nio.file.LinkOption... options)
                         throws java.io.IOException

Throws:

java.io.IOException

setFileAccessControl

default void setFileAccessControl(SftpSubsystemProxy subsystem,
                                  java.nio.file.Path file,
                                  java.util.List<java.nio.file.attribute.AclEntry> acl,
                                  java.nio.file.LinkOption... options)
                           throws java.io.IOException

Throws:

java.io.IOException

createDirectory

default void createDirectory(SftpSubsystemProxy subsystem,
                             java.nio.file.Path path)
                      throws java.io.IOException

Throws:

java.io.IOException

createLink

default void createLink(SftpSubsystemProxy subsystem,
                        java.nio.file.Path link,
                        java.nio.file.Path existing,
                        boolean symLink)
                 throws java.io.IOException

Invoked in order to create a link to a path

Parameters:

subsystem - The SFTP subsystem instance that manages the session

link - The requested link Path - same one returned by resolveLocalFilePath

existing - The existing Path that the link should reference

symLink - true if this should be a symbolic link

Throws:

java.io.IOException - If failed to create the link

See Also:

Files.createLink(Path, Path), Files.createSymbolicLink(Path, Path, FileAttribute...)

resolveLinkTarget

default java.lang.String resolveLinkTarget(SftpSubsystemProxy subsystem,
                                           java.nio.file.Path link)
                                    throws java.io.IOException

Throws:

java.io.IOException

renameFile

default void renameFile(SftpSubsystemProxy subsystem,
                        java.nio.file.Path oldPath,
                        java.nio.file.Path newPath,
                        java.util.Collection<java.nio.file.CopyOption> opts)
                 throws java.io.IOException

Throws:

java.io.IOException

copyFile

default void copyFile(SftpSubsystemProxy subsystem,
                      java.nio.file.Path src,
                      java.nio.file.Path dst,
                      java.util.Collection<java.nio.file.CopyOption> opts)
               throws java.io.IOException

Throws:

java.io.IOException

removeFile

default void removeFile(SftpSubsystemProxy subsystem,
                        java.nio.file.Path path,
                        boolean isDirectory)
                 throws java.io.IOException

Throws:

java.io.IOException