Interface ScpFileOpener

  • All Known Implementing Classes:
    DefaultScpFileOpener

    public interface ScpFileOpener
    Plug-in mechanism for users to intervene in the SCP process - e.g., apply some kind of traffic shaping mechanism, display upload/download progress, etc...
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default void closeRead​(Session session, java.nio.file.Path file, long size, java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions, java.io.InputStream stream)
      Called when the stream obtained from openRead is no longer required since data has been successfully copied.
      default void closeWrite​(Session session, java.nio.file.Path file, long size, java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions, java.io.OutputStream os)
      Called when output stream obtained from openWrite is no longer needed since data copying has been successfully completed.
      ScpSourceStreamResolver createScpSourceStreamResolver​(Session session, java.nio.file.Path path)  
      ScpTargetStreamResolver createScpTargetStreamResolver​(Session session, java.nio.file.Path path)  
      default java.nio.file.attribute.BasicFileAttributes getLocalBasicFileAttributes​(Session session, java.nio.file.Path path, java.nio.file.LinkOption... options)  
      default java.util.Set<java.nio.file.attribute.PosixFilePermission> getLocalFilePermissions​(Session session, java.nio.file.Path path, java.nio.file.LinkOption... options)  
      default java.nio.file.DirectoryStream<java.nio.file.Path> getLocalFolderChildren​(Session session, java.nio.file.Path path)
      Invoked when required to send all children of a local directory
      default java.lang.Iterable<java.nio.file.Path> getMatchingFilesToSend​(Session session, java.nio.file.Path basedir, java.lang.String pattern)
      Invoked when required to send a pattern of files
      java.io.InputStream openRead​(Session session, java.nio.file.Path file, long size, java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions, java.nio.file.OpenOption... options)
      Create an input stream to read from a file
      java.io.OutputStream openWrite​(Session session, java.nio.file.Path file, long size, java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions, java.nio.file.OpenOption... options)
      Create an output stream to write to a file
      default java.nio.file.Path resolveIncomingFilePath​(Session session, java.nio.file.Path localPath, java.lang.String name, boolean preserve, java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions, ScpTimestampCommandDetails time)
      Invoked when receiving a new file to via a directory command
      default java.nio.file.Path resolveIncomingReceiveLocation​(Session session, java.nio.file.Path path, boolean recursive, boolean shouldBeDir, boolean preserve)
      Invoked when a request to receive something is processed
      default java.nio.file.Path resolveLocalPath​(Session session, java.nio.file.FileSystem fileSystem, java.lang.String commandPath)  
      default java.nio.file.Path resolveOutgoingFilePath​(Session session, java.nio.file.Path localPath, java.nio.file.LinkOption... options)
      Called when there is a candidate file/folder for sending
      default boolean sendAsDirectory​(Session session, java.nio.file.Path path, java.nio.file.LinkOption... options)
      Invoked on a local path in order to decide whether it should be sent as a file or as a directory
      default boolean sendAsRegularFile​(Session session, java.nio.file.Path path, java.nio.file.LinkOption... options)
      Invoked on a local path in order to decide whether it should be sent as a file or as a directory
      static void updateFileProperties​(java.nio.file.Path file, java.util.Set<java.nio.file.attribute.PosixFilePermission> perms, ScpTimestampCommandDetails time)  
    • Method Detail

      • resolveIncomingFilePath

        default java.nio.file.Path resolveIncomingFilePath​(Session session,
                                                           java.nio.file.Path localPath,
                                                           java.lang.String name,
                                                           boolean preserve,
                                                           java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions,
                                                           ScpTimestampCommandDetails time)
                                                    throws java.io.IOException
        Invoked when receiving a new file to via a directory command
        Parameters:
        session - The client/server Session through which the transfer is being executed
        localPath - The target local path
        name - The target file name
        preserve - Whether requested to preserve the permissions and timestamp
        permissions - The requested file permissions
        time - The requested ScpTimestampCommandDetails - may be null if nothing to update
        Returns:
        The actual target file path for the incoming file/directory
        Throws:
        java.io.IOException - If failed to resolve the file path
        See Also:
        updateFileProperties
      • getMatchingFilesToSend

        default java.lang.Iterable<java.nio.file.Path> getMatchingFilesToSend​(Session session,
                                                                              java.nio.file.Path basedir,
                                                                              java.lang.String pattern)
                                                                       throws java.io.IOException
        Invoked when required to send a pattern of files
        Parameters:
        session - The client/server Session through which the transfer is being executed
        basedir - The base directory - may be null/empty to indicate CWD
        pattern - The required pattern - ignored if null/empty - returns empty result
        Returns:
        The matching relative paths of the children to send
        Throws:
        java.io.IOException - If failed to scan the directory
      • sendAsRegularFile

        default boolean sendAsRegularFile​(Session session,
                                          java.nio.file.Path path,
                                          java.nio.file.LinkOption... options)
                                   throws java.io.IOException
        Invoked on a local path in order to decide whether it should be sent as a file or as a directory
        Parameters:
        session - The client/server Session through which the transfer is being executed
        path - The local Path
        options - The LinkOption-s
        Returns:
        Whether to send the file as a regular one - Note: if false then the sendAsDirectory(Session, Path, LinkOption...) is consulted.
        Throws:
        java.io.IOException - If failed to decide
      • sendAsDirectory

        default boolean sendAsDirectory​(Session session,
                                        java.nio.file.Path path,
                                        java.nio.file.LinkOption... options)
                                 throws java.io.IOException
        Invoked on a local path in order to decide whether it should be sent as a file or as a directory
        Parameters:
        session - The client/server Session through which the transfer is being executed
        path - The local Path
        options - The LinkOption-s
        Returns:
        Whether to send the file as a directory - Note: if true then getLocalFolderChildren(Session, Path) is consulted
        Throws:
        java.io.IOException - If failed to decide
      • getLocalFolderChildren

        default java.nio.file.DirectoryStream<java.nio.file.Path> getLocalFolderChildren​(Session session,
                                                                                         java.nio.file.Path path)
                                                                                  throws java.io.IOException
        Invoked when required to send all children of a local directory
        Parameters:
        session - The client/server Session through which the transfer is being executed
        path - The local folder Path
        Returns:
        The DirectoryStream of children to send - Note: for each child the decision whether to send it as a file or a directory will be reached by consulting the respective sendAsRegularFile and sendAsDirectory methods
        Throws:
        java.io.IOException - If failed to provide the children stream
        See Also:
        sendAsDirectory
      • getLocalBasicFileAttributes

        default java.nio.file.attribute.BasicFileAttributes getLocalBasicFileAttributes​(Session session,
                                                                                        java.nio.file.Path path,
                                                                                        java.nio.file.LinkOption... options)
                                                                                 throws java.io.IOException
        Throws:
        java.io.IOException
      • getLocalFilePermissions

        default java.util.Set<java.nio.file.attribute.PosixFilePermission> getLocalFilePermissions​(Session session,
                                                                                                   java.nio.file.Path path,
                                                                                                   java.nio.file.LinkOption... options)
                                                                                            throws java.io.IOException
        Throws:
        java.io.IOException
      • resolveLocalPath

        default java.nio.file.Path resolveLocalPath​(Session session,
                                                    java.nio.file.FileSystem fileSystem,
                                                    java.lang.String commandPath)
                                             throws java.io.IOException,
                                                    java.nio.file.InvalidPathException
        Parameters:
        session - The client/server Session through which the transfer is being executed
        fileSystem - The local FileSystem on which local file should reside
        commandPath - The command path using the local file separator
        Returns:
        The resolved absolute and normalized local Path
        Throws:
        java.io.IOException - If failed to resolve the path
        java.nio.file.InvalidPathException - If invalid local path value
      • resolveIncomingReceiveLocation

        default java.nio.file.Path resolveIncomingReceiveLocation​(Session session,
                                                                  java.nio.file.Path path,
                                                                  boolean recursive,
                                                                  boolean shouldBeDir,
                                                                  boolean preserve)
                                                           throws java.io.IOException
        Invoked when a request to receive something is processed
        Parameters:
        session - The client/server Session through which the transfer is being executed
        path - The local target Path of the request
        recursive - Whether the request is recursive
        shouldBeDir - Whether target path is expected to be a directory
        preserve - Whether target path is expected to preserve attributes (permissions, times)
        Returns:
        The effective target path - default=same as input
        Throws:
        java.io.IOException - If failed to resolve target location
      • resolveOutgoingFilePath

        default java.nio.file.Path resolveOutgoingFilePath​(Session session,
                                                           java.nio.file.Path localPath,
                                                           java.nio.file.LinkOption... options)
                                                    throws java.io.IOException
        Called when there is a candidate file/folder for sending
        Parameters:
        session - The client/server Session through which the transfer is being executed
        localPath - The original file/folder Path for sending
        options - The LinkOption-s to use for validation
        Returns:
        The effective outgoing file path (default=same as input)
        Throws:
        java.io.IOException - If failed to resolve
      • openRead

        java.io.InputStream openRead​(Session session,
                                     java.nio.file.Path file,
                                     long size,
                                     java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions,
                                     java.nio.file.OpenOption... options)
                              throws java.io.IOException
        Create an input stream to read from a file
        Parameters:
        session - The Session requesting the access
        file - The requested local file Path
        size - The expected transfer bytes count
        permissions - The requested file permissions
        options - The OpenOptions - may be null/empty
        Returns:
        The open InputStream never null
        Throws:
        java.io.IOException - If failed to open the file
      • closeRead

        default void closeRead​(Session session,
                               java.nio.file.Path file,
                               long size,
                               java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions,
                               java.io.InputStream stream)
                        throws java.io.IOException
        Called when the stream obtained from openRead is no longer required since data has been successfully copied.
        Parameters:
        session - The Session requesting the access
        file - The requested local file Path
        size - The expected transfer bytes count
        permissions - The requested file permissions
        stream - The InputStream to close
        Throws:
        java.io.IOException - If failed to close the stream - Note: stream will be closed regardless of whether this method throws an exception or not.
      • createScpSourceStreamResolver

        ScpSourceStreamResolver createScpSourceStreamResolver​(Session session,
                                                              java.nio.file.Path path)
                                                       throws java.io.IOException
        Throws:
        java.io.IOException
      • openWrite

        java.io.OutputStream openWrite​(Session session,
                                       java.nio.file.Path file,
                                       long size,
                                       java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions,
                                       java.nio.file.OpenOption... options)
                                throws java.io.IOException
        Create an output stream to write to a file
        Parameters:
        session - The Session requesting the access
        file - The requested local file Path
        size - The expected transfer byte count
        permissions - The requested file permissions
        options - The OpenOptions - may be null/empty
        Returns:
        The open OutputStream never null
        Throws:
        java.io.IOException - If failed to open the file
      • closeWrite

        default void closeWrite​(Session session,
                                java.nio.file.Path file,
                                long size,
                                java.util.Set<java.nio.file.attribute.PosixFilePermission> permissions,
                                java.io.OutputStream os)
                         throws java.io.IOException
        Called when output stream obtained from openWrite is no longer needed since data copying has been successfully completed.
        Parameters:
        session - The Session requesting the access
        file - The requested local file Path
        size - The expected transfer byte count
        permissions - The requested file permissions
        os - The opened OutputStream
        Throws:
        java.io.IOException - If failed to close the stream - Note: stream will be closed regardless of whether this method throws an exception or not.
      • createScpTargetStreamResolver

        ScpTargetStreamResolver createScpTargetStreamResolver​(Session session,
                                                              java.nio.file.Path path)
                                                       throws java.io.IOException
        Throws:
        java.io.IOException
      • updateFileProperties

        static void updateFileProperties​(java.nio.file.Path file,
                                         java.util.Set<java.nio.file.attribute.PosixFilePermission> perms,
                                         ScpTimestampCommandDetails time)
                                  throws java.io.IOException
        Throws:
        java.io.IOException