Interface SftpClient

    • Method Detail

      • getVersion

        int getVersion()
        Returns:
        The negotiated SFTP protocol version
      • getName

        default java.lang.String getName()
        Specified by:
        getName in interface NamedResource
        Returns:
        The resource name
      • setNameDecodingCharset

        void setNameDecodingCharset​(java.nio.charset.Charset cs)
      • getServerExtensions

        java.util.NavigableMap<java.lang.String,​byte[]> getServerExtensions()
        Returns:
        An (unmodifiable) NavigableMap of the reported server extensions. where key=extension name (case insensitive)
      • isClosing

        boolean isClosing()
      • close

        void close​(SftpClient.Handle handle)
            throws java.io.IOException
        Close the handle obtained from one of the open methods
        Parameters:
        handle - The Handle to close
        Throws:
        java.io.IOException - If failed to execute
      • remove

        void remove​(java.lang.String path)
             throws java.io.IOException
        Parameters:
        path - The remote path to remove
        Throws:
        java.io.IOException - If failed to execute
      • rename

        default void rename​(java.lang.String oldPath,
                            java.lang.String newPath)
                     throws java.io.IOException
        Throws:
        java.io.IOException
      • rename

        default void rename​(java.lang.String oldPath,
                            java.lang.String newPath,
                            SftpClient.CopyMode... options)
                     throws java.io.IOException
        Throws:
        java.io.IOException
      • rename

        void rename​(java.lang.String oldPath,
                    java.lang.String newPath,
                    java.util.Collection<SftpClient.CopyMode> options)
             throws java.io.IOException
        Throws:
        java.io.IOException
      • read

        default int read​(SftpClient.Handle handle,
                         long fileOffset,
                         byte[] dst)
                  throws java.io.IOException
        Reads data from the open (file) handle
        Parameters:
        handle - The file SftpClient.Handle to read from
        fileOffset - The file offset to read from
        dst - The destination buffer
        Returns:
        Number of read bytes - -1 if EOF reached
        Throws:
        java.io.IOException - If failed to read the data
        See Also:
        read(Handle, long, byte[], int, int)
      • read

        default int read​(SftpClient.Handle handle,
                         long fileOffset,
                         byte[] dst,
                         java.util.concurrent.atomic.AtomicReference<java.lang.Boolean> eofSignalled)
                  throws java.io.IOException
        Reads data from the open (file) handle
        Parameters:
        handle - The file SftpClient.Handle to read from
        fileOffset - The file offset to read from
        dst - The destination buffer
        eofSignalled - If not null then upon return holds a value indicating whether EOF was reached due to the read. If null indicator value then this indication is not available
        Returns:
        Number of read bytes - -1 if EOF reached
        Throws:
        java.io.IOException - If failed to read the data
        See Also:
        read(Handle, long, byte[], int, int, AtomicReference), SFTP v6 - section 9.3
      • read

        default int read​(SftpClient.Handle handle,
                         long fileOffset,
                         byte[] dst,
                         int dstOffset,
                         int len)
                  throws java.io.IOException
        Throws:
        java.io.IOException
      • read

        int read​(SftpClient.Handle handle,
                 long fileOffset,
                 byte[] dst,
                 int dstOffset,
                 int len,
                 java.util.concurrent.atomic.AtomicReference<java.lang.Boolean> eofSignalled)
          throws java.io.IOException
        Reads data from the open (file) handle
        Parameters:
        handle - The file SftpClient.Handle to read from
        fileOffset - The file offset to read from
        dst - The destination buffer
        dstOffset - Offset in destination buffer to place the read data
        len - Available destination buffer size to read
        eofSignalled - If not null then upon return holds a value indicating whether EOF was reached due to the read. If null indicator value then this indication is not available
        Returns:
        Number of read bytes - -1 if EOF reached
        Throws:
        java.io.IOException - If failed to read the data
        See Also:
        SFTP v6 - section 9.3
      • write

        default void write​(SftpClient.Handle handle,
                           long fileOffset,
                           byte[] src)
                    throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        void write​(SftpClient.Handle handle,
                   long fileOffset,
                   byte[] src,
                   int srcOffset,
                   int len)
            throws java.io.IOException
        Write data to (open) file handle
        Parameters:
        handle - The file SftpClient.Handle
        fileOffset - Zero-based offset to write in file
        src - Data buffer
        srcOffset - Offset of valid data in buffer
        len - Number of bytes to write
        Throws:
        java.io.IOException - If failed to write the data
      • mkdir

        void mkdir​(java.lang.String path)
            throws java.io.IOException
        Create remote directory
        Parameters:
        path - Remote directory path
        Throws:
        java.io.IOException - If failed to execute
      • rmdir

        void rmdir​(java.lang.String path)
            throws java.io.IOException
        Remove remote directory
        Parameters:
        path - Remote directory path
        Throws:
        java.io.IOException - If failed to execute
      • openDir

        SftpClient.CloseableHandle openDir​(java.lang.String path)
                                    throws java.io.IOException
        Obtain a handle for a directory
        Parameters:
        path - Remote directory path
        Returns:
        The associated directory SftpClient.Handle
        Throws:
        java.io.IOException - If failed to execute
      • readDir

        default java.util.List<SftpClient.DirEntry> readDir​(SftpClient.Handle handle)
                                                     throws java.io.IOException
        Parameters:
        handle - Directory SftpClient.Handle to read from
        Returns:
        A List of entries - null to indicate no more entries Note: the list may be incomplete since the client and server have some internal imposed limit on the number of entries they can process. Therefore several calls to this method may be required (until null). In order to iterate over all the entries use readDir(String)
        Throws:
        java.io.IOException - If failed to access the remote site
      • readDir

        java.util.List<SftpClient.DirEntry> readDir​(SftpClient.Handle handle,
                                                    java.util.concurrent.atomic.AtomicReference<java.lang.Boolean> eolIndicator)
                                             throws java.io.IOException
        Parameters:
        handle - Directory SftpClient.Handle to read from
        eolIndicator - An indicator that can be used to get information whether end of list has been reached - ignored if null. Upon return, set value indicates whether all entries have been exhausted - a null value means that this information cannot be provided and another call to readDir is necessary in order to verify that no more entries are pending
        Returns:
        A List of entries - null to indicate no more entries
        Throws:
        java.io.IOException - If failed to access the remote site
        See Also:
        SFTP v6 - section 9.4
      • listDir

        java.lang.Iterable<SftpClient.DirEntry> listDir​(SftpClient.Handle handle)
                                                 throws java.io.IOException
        Parameters:
        handle - A directory SftpClient.Handle
        Returns:
        An Iterable that can be used to iterate over all the directory entries (like readDir(String)). Note: the iterable instance is not re-usable - i.e., files can be iterated only once
        Throws:
        java.io.IOException - If failed to access the directory
      • canonicalPath

        java.lang.String canonicalPath​(java.lang.String path)
                                throws java.io.IOException
        The effective "normalized" remote path
        Parameters:
        path - The requested path - may be relative, and/or contain dots - e.g., ".", "..", "./foo", "../bar"
        Returns:
        The effective "normalized" remote path
        Throws:
        java.io.IOException - If failed to execute
      • stat

        SftpClient.Attributes stat​(java.lang.String path)
                            throws java.io.IOException
        Retrieve remote path meta-data - follow symbolic links if encountered
        Parameters:
        path - The remote path
        Returns:
        The associated SftpClient.Attributes
        Throws:
        java.io.IOException - If failed to execute
      • lstat

        SftpClient.Attributes lstat​(java.lang.String path)
                             throws java.io.IOException
        Retrieve remote path meta-data - do not follow symbolic links
        Parameters:
        path - The remote path
        Returns:
        The associated SftpClient.Attributes
        Throws:
        java.io.IOException - If failed to execute
      • setStat

        void setStat​(java.lang.String path,
                     SftpClient.Attributes attributes)
              throws java.io.IOException
        Update remote node meta-data
        Parameters:
        path - The remote path
        attributes - The SftpClient.Attributes to update
        Throws:
        java.io.IOException - If failed to execute
      • readLink

        java.lang.String readLink​(java.lang.String path)
                           throws java.io.IOException
        Retrieve target of a link
        Parameters:
        path - Remote path that represents a link
        Returns:
        The link target
        Throws:
        java.io.IOException - If failed to execute
      • symLink

        default void symLink​(java.lang.String linkPath,
                             java.lang.String targetPath)
                      throws java.io.IOException
        Create symbolic link
        Parameters:
        linkPath - The link location
        targetPath - The referenced target by the link
        Throws:
        java.io.IOException - If failed to execute
        See Also:
        link(String, String, boolean)
      • link

        void link​(java.lang.String linkPath,
                  java.lang.String targetPath,
                  boolean symbolic)
           throws java.io.IOException
        Create a link
        Parameters:
        linkPath - The link location
        targetPath - The referenced target by the link
        symbolic - If true then make this a symbolic link, otherwise a hard one
        Throws:
        java.io.IOException - If failed to execute
      • lock

        void lock​(SftpClient.Handle handle,
                  long offset,
                  long length,
                  int mask)
           throws java.io.IOException
        Throws:
        java.io.IOException
      • unlock

        void unlock​(SftpClient.Handle handle,
                    long offset,
                    long length)
             throws java.io.IOException
        Throws:
        java.io.IOException
      • openRemotePathChannel

        default java.nio.channels.FileChannel openRemotePathChannel​(java.lang.String path,
                                                                    java.nio.file.OpenOption... options)
                                                             throws java.io.IOException
        Throws:
        java.io.IOException
      • openRemotePathChannel

        default java.nio.channels.FileChannel openRemotePathChannel​(java.lang.String path,
                                                                    java.util.Collection<? extends java.nio.file.OpenOption> options)
                                                             throws java.io.IOException
        Throws:
        java.io.IOException
      • openRemoteFileChannel

        default java.nio.channels.FileChannel openRemoteFileChannel​(java.lang.String path,
                                                                    SftpClient.OpenMode... modes)
                                                             throws java.io.IOException
        Throws:
        java.io.IOException
      • openRemoteFileChannel

        java.nio.channels.FileChannel openRemoteFileChannel​(java.lang.String path,
                                                            java.util.Collection<SftpClient.OpenMode> modes)
                                                     throws java.io.IOException
        Opens an FileChannel on the specified remote path
        Parameters:
        path - The remote path
        modes - The access mode(s) - if null/empty then the DEFAULT_CHANNEL_MODES are used
        Returns:
        The open FileChannel - Note: do not close this owner client instance until the channel is no longer needed since it uses the client for providing the channel's functionality.
        Throws:
        java.io.IOException - If failed to open the channel
        See Also:
        Channels.newInputStream(java.nio.channels.ReadableByteChannel), Channels.newOutputStream(java.nio.channels.WritableByteChannel)
      • readDir

        java.lang.Iterable<SftpClient.DirEntry> readDir​(java.lang.String path)
                                                 throws java.io.IOException
        Parameters:
        path - The remote directory path
        Returns:
        An Iterable that can be used to iterate over all the directory entries (unlike readDir(Handle))
        Throws:
        java.io.IOException - If failed to access the remote site
        See Also:
        readDir(Handle)
      • readEntries

        default java.util.Collection<SftpClient.DirEntry> readEntries​(java.lang.String path)
                                                               throws java.io.IOException
        Reads all entries available for a directory
        Parameters:
        path - Remote directory path
        Returns:
        A Collection of all the entries in the remote directory
        Throws:
        java.io.IOException - If failed to retrieve the entries
        See Also:
        readDir(String)
      • read

        default java.io.InputStream read​(java.lang.String path)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
      • read

        default java.io.InputStream read​(java.lang.String path,
                                         int bufferSize)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
      • read

        default java.io.InputStream read​(java.lang.String path,
                                         SftpClient.OpenMode... mode)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
      • read

        default java.io.InputStream read​(java.lang.String path,
                                         int bufferSize,
                                         SftpClient.OpenMode... mode)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
      • read

        default java.io.InputStream read​(java.lang.String path,
                                         java.util.Collection<SftpClient.OpenMode> mode)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
      • read

        java.io.InputStream read​(java.lang.String path,
                                 int bufferSize,
                                 java.util.Collection<SftpClient.OpenMode> mode)
                          throws java.io.IOException
        Read a remote file's data via an input stream
        Parameters:
        path - The remote file path
        bufferSize - The internal read buffer size
        mode - The remote file SftpClient.OpenModes
        Returns:
        An InputStream for reading the remote file data
        Throws:
        java.io.IOException - If failed to execute
      • write

        default java.io.OutputStream write​(java.lang.String path)
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        default java.io.OutputStream write​(java.lang.String path,
                                           int bufferSize)
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        default java.io.OutputStream write​(java.lang.String path,
                                           SftpClient.OpenMode... mode)
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        default java.io.OutputStream write​(java.lang.String path,
                                           int bufferSize,
                                           SftpClient.OpenMode... mode)
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        default java.io.OutputStream write​(java.lang.String path,
                                           java.util.Collection<SftpClient.OpenMode> mode)
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        java.io.OutputStream write​(java.lang.String path,
                                   int bufferSize,
                                   java.util.Collection<SftpClient.OpenMode> mode)
                            throws java.io.IOException
        Write to a remote file via an output stream
        Parameters:
        path - The remote file path
        bufferSize - The internal write buffer size
        mode - The remote file SftpClient.OpenModes
        Returns:
        An OutputStream for writing the data
        Throws:
        java.io.IOException - If failed to execute
      • getExtension

        default <E extends SftpClientExtension> E getExtension​(java.lang.Class<? extends E> extensionType)
        Type Parameters:
        E - The generic extension type
        Parameters:
        extensionType - The extension type
        Returns:
        The extension instance - Note: it is up to the caller to invoke OptionalFeature.isSupported() - null if this extension type is not implemented by the client
        See Also:
        getServerExtensions()
      • singleSessionInstance

        default SftpClient singleSessionInstance()
        Creates an SftpClient instance that also closes the underlying client session when the client instance is closed.
        Returns:
        The wrapper instance