Interface SftpFileSystemAccessor


  • public interface SftpFileSystemAccessor
    • Method Summary

      All Methods Instance Methods Default Methods 
      Modifier and Type Method 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
    • 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