Module bus.extra
Package org.miaixz.bus.extra.ssh.provider.jsch

Class JschSftp

java.lang.Object
org.miaixz.bus.extra.ftp.AbstractFtp
org.miaixz.bus.extra.ssh.provider.jsch.JschSftp
All Implemented Interfaces:
Closeable, AutoCloseable, Ftp
public class JschSftp extends AbstractFtp
SFTP (Secure File Transfer Protocol) client implementation based on JSch. SFTP provides a secure, encrypted method for file transfer over SSH, making it a robust alternative to traditional FTP. Due to encryption and decryption overhead, its transfer efficiency is generally lower than standard FTP. This class is suitable for scenarios with high network security requirements.

Reference: https://www.cnblogs.com/longyg/archive/2012/06/25/2556576.html

Since:
Java 17+
Author:
Kimi Liu

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    JschSftp.Mode
    Enumeration of file transfer modes supported by JSch.

  • Field Summary

    Fields inherited from class org.miaixz.bus.extra.ftp.AbstractFtp

    ftpConfig

    Fields inherited from interface org.miaixz.bus.extra.ftp.Ftp

    DEFAULT_CHARSET

  • Constructor Summary

    Constructors
    Constructor
    Description
    JschSftp(com.jcraft.jsch.ChannelSftp channel, Charset charset, long timeOut)
    Constructs a JschSftp instance with an existing JSch ChannelSftp, character set, and timeout.
    JschSftp(com.jcraft.jsch.Session session, Charset charset, long timeOut)
    Constructs a JschSftp instance with an existing JSch Session, character set, and timeout.
    JschSftp(FtpConfig config)
    Constructs a JschSftp instance with the given FTP configuration and initializes it immediately.
    JschSftp(FtpConfig config, boolean init)
    Constructs a JschSftp instance with the given FTP configuration and an option to initialize immediately.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    cd(String directory)
    Changes the current working directory on the remote FTP server to the specified directory.
    void
    close()
     
    boolean
    delDir(String dirPath)
    Deletes a directory and all its contents (files and subdirectories) recursively on the remote FTP server.
    boolean
    delFile(String filePath)
    Deletes a specified file on the remote FTP server.
    void
    download(String remotePath, File destFile)
    Downloads a file from the remote FTP server to a specified local file or directory.
    void
    download(String src, OutputStream out)
    Downloads a file to an OutputStream.
    JschSftp
    get(String src, OutputStream out)
    Retrieves a remote file and writes it to an output stream.
    JschSftp
    get(String src, String dest)
    Retrieves a remote file and saves it to a local path.
    com.jcraft.jsch.ChannelSftp
    getClient()
    Retrieves the underlying SFTP channel client.
    InputStream
    getFileStream(String path)
    Reads a file from the FTP server and provides its content as an InputStream.
    String
    home()
    Retrieves the HOME directory on the SFTP server.
    void
    init()
    Initializes the SFTP connection.
    boolean
    isDir(String dir)
    Determines if the given path on the remote server refers to a directory.
    List<String>
    ls(String path)
    Lists all file and directory names within a specified remote directory (non-recursive).
    List<String>
    ls(String path, Predicate<com.jcraft.jsch.ChannelSftp.LsEntry> predicate)
    Lists all files or directories in a given path, without recursion, applying a filter.
    List<String>
    lsDirs(String path)
    Lists all directories in a given path, without recursion.
    List<com.jcraft.jsch.ChannelSftp.LsEntry>
    lsEntries(String path)
    Lists all files or directories in a given path, generating a list of ChannelSftp.LsEntry objects, without recursion.
    List<com.jcraft.jsch.ChannelSftp.LsEntry>
    lsEntries(String path, Predicate<com.jcraft.jsch.ChannelSftp.LsEntry> predicate)
    Lists all files or directories in a given path, generating a list of ChannelSftp.LsEntry objects, without recursion, applying a filter.
    List<String>
    lsFiles(String path)
    Lists all files in a given path, without recursion.
    boolean
    mkdir(String dir)
    Creates a new directory in the current remote working directory.
    static JschSftp
    of(String sshHost, int sshPort, String sshUser, String sshPass)
    Creates a JschSftp instance with the specified SSH connection details.
    static JschSftp
    of(String sshHost, int sshPort, String sshUser, String sshPass, Charset charset)
    Creates a JschSftp instance with the specified SSH connection details and character set.
    JschSftp
    put(InputStream srcStream, String destPath, com.jcraft.jsch.SftpProgressMonitor monitor, JschSftp.Mode mode)
    Uploads a local data stream to the target server.
    JschSftp
    put(String srcFilePath, String destPath)
    Uploads a local file to the target server, overwriting existing files.
    JschSftp
    put(String srcFilePath, String destPath, com.jcraft.jsch.SftpProgressMonitor monitor, JschSftp.Mode mode)
    Uploads a local file to the target server with a progress monitor and transfer mode.
    JschSftp
    put(String srcFilePath, String destPath, JschSftp.Mode mode)
    Uploads a local file to the target server with a specified transfer mode.
    String
    pwd()
    Retrieves the current remote directory (working directory) on the FTP server.
    JschSftp
    reconnectIfTimeout()
    Reconnects to the FTP server if the current connection has timed out or become stale.
    void
    recursiveDownloadFolder(String remotePath, File targetDir)
    Recursively downloads files and directories from the FTP server to the local machine, synchronizing the file structures.
    boolean
    rename(String oldPath, String newPath)
    Renames a file or directory on the remote FTP server.
    String
    toString()
     
    void
    upload(String remotePath, File file)
    Recursively uploads a local file or folder to a remote path, overwriting existing files.
    boolean
    uploadFile(String destPath, File file)
    Uploads a local file to the target server.
    void
    uploadFile(String destPath, String fileName, InputStream fileStream)
    Uploads a file from an InputStream to the specified remote directory.

    Methods inherited from class org.miaixz.bus.extra.ftp.AbstractFtp

    download, exist, getConfig, mkDirs

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.miaixz.bus.extra.ftp.Ftp

    toParent

  • Constructor Details

    • JschSftp

      public JschSftp(FtpConfig config)
      Constructs a JschSftp instance with the given FTP configuration and initializes it immediately.
      Parameters:
      config - The FtpConfig containing connection details.

    • JschSftp

      public JschSftp(FtpConfig config, boolean init)
      Constructs a JschSftp instance with the given FTP configuration and an option to initialize immediately.
      Parameters:
      config - The FtpConfig containing connection details.
      init - If true, the SFTP connection is initialized immediately.

    • JschSftp

      public JschSftp(com.jcraft.jsch.Session session, Charset charset, long timeOut)
      Constructs a JschSftp instance with an existing JSch Session, character set, and timeout.
      Parameters:
      session - The pre-existing JSch Session.
      charset - The character set for file names.
      timeOut - The connection timeout duration in milliseconds.

    • JschSftp

      public JschSftp(com.jcraft.jsch.ChannelSftp channel, Charset charset, long timeOut)
      Constructs a JschSftp instance with an existing JSch ChannelSftp, character set, and timeout.
      Parameters:
      channel - The pre-existing JSch ChannelSftp.
      charset - The character set for file names.
      timeOut - The connection timeout duration in milliseconds.

  • Method Details

    • of

      public static JschSftp of(String sshHost, int sshPort, String sshUser, String sshPass)
      Creates a JschSftp instance with the specified SSH connection details.
      Parameters:
      sshHost - The remote host address.
      sshPort - The remote host port.
      sshUser - The username for authentication.
      sshPass - The password for authentication.
      Returns:
      A new JschSftp instance.

    • of

      public static JschSftp of(String sshHost, int sshPort, String sshUser, String sshPass, Charset charset)
      Creates a JschSftp instance with the specified SSH connection details and character set.
      Parameters:
      sshHost - The remote host address.
      sshPort - The remote host port.
      sshUser - The username for authentication.
      sshPass - The password for authentication.
      charset - The character set for file names.
      Returns:
      A new JschSftp instance.

    • init

      public void init()
      Initializes the SFTP connection. If the session or channel is not yet established, it will be created and connected. The filename encoding will be set based on the FTP configuration.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if a JSch or SftpException occurs during initialization.

    • reconnectIfTimeout

      public JschSftp reconnectIfTimeout()
      Description copied from interface: Ftp
      Reconnects to the FTP server if the current connection has timed out or become stale. Implementations should handle the logic for checking connection validity and re-establishing it.
      Returns:
      This Ftp instance, allowing for method chaining.

    • getClient

      public com.jcraft.jsch.ChannelSftp getClient()
      Retrieves the underlying SFTP channel client.
      Returns:
      The ChannelSftp client.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an error occurs during initialization or connection.

    • pwd

      public String pwd()
      Description copied from interface: Ftp
      Retrieves the current remote directory (working directory) on the FTP server.
      Returns:
      The absolute path of the current working directory as a String.

    • home

      public String home()
      Retrieves the HOME directory on the SFTP server.
      Returns:
      The HOME directory path.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs.

    • ls

      public List<String> ls(String path)
      Description copied from interface: Ftp
      Lists all file and directory names within a specified remote directory (non-recursive).
      Parameters:
      path - The path to the directory to list.
      Returns:
      A List of Strings, where each string is the name of a file or directory.

    • lsDirs

      public List<String> lsDirs(String path)
      Lists all directories in a given path, without recursion.
      Parameters:
      path - The path to list directories from.
      Returns:
      A list of directory names.

    • lsFiles

      public List<String> lsFiles(String path)
      Lists all files in a given path, without recursion.
      Parameters:
      path - The path to list files from.
      Returns:
      A list of file names.

    • ls

      public List<String> ls(String path, Predicate<com.jcraft.jsch.ChannelSftp.LsEntry> predicate)
      Lists all files or directories in a given path, without recursion, applying a filter. This method automatically filters out "." and ".." directories.
      Parameters:
      path - The path to list files or directories from.
      predicate - A file or directory filter. Predicate.test(Object) returning true keeps the entry.
      Returns:
      A list of directory or file names.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs other than "No such file".

    • lsEntries

      public List<com.jcraft.jsch.ChannelSftp.LsEntry> lsEntries(String path)
      Lists all files or directories in a given path, generating a list of ChannelSftp.LsEntry objects, without recursion. This method automatically filters out "." and ".." directories.
      Parameters:
      path - The path to list files or directories from.
      Returns:
      A list of ChannelSftp.LsEntry objects.

    • lsEntries

      public List<com.jcraft.jsch.ChannelSftp.LsEntry> lsEntries(String path, Predicate<com.jcraft.jsch.ChannelSftp.LsEntry> predicate)
      Lists all files or directories in a given path, generating a list of ChannelSftp.LsEntry objects, without recursion, applying a filter. This method automatically filters out "." and ".." directories.
      Parameters:
      path - The path to list files or directories from.
      predicate - A file or directory filter. Predicate.test(Object) returning true keeps the entry.
      Returns:
      A list of ChannelSftp.LsEntry objects.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs other than "No such file".

    • rename

      public boolean rename(String oldPath, String newPath)
      Description copied from interface: Ftp
      Renames a file or directory on the remote FTP server.
      Parameters:
      oldPath - The current path or name of the file/directory to rename.
      newPath - The new path or name for the file/directory.
      Returns:
      true if the rename operation was successful; false otherwise.

    • mkdir

      public boolean mkdir(String dir)
      Description copied from interface: Ftp
      Creates a new directory in the current remote working directory.
      Parameters:
      dir - The name of the directory to create.
      Returns:
      true if the directory was created successfully; false otherwise.

    • isDir

      public boolean isDir(String dir)
      Description copied from interface: Ftp
      Determines if the given path on the remote server refers to a directory. This method temporarily changes the directory to the given path to verify if it's a directory, then reverts to the original working directory.
      Parameters:
      dir - The path to check.
      Returns:
      true if the path is a directory; false otherwise.

    • cd

      public boolean cd(String directory) throws org.miaixz.bus.core.lang.exception.InternalException
      Description copied from interface: Ftp
      Changes the current working directory on the remote FTP server to the specified directory. The behavior for invalid directories (e.g., non-existent) may vary between implementations.
      Parameters:
      directory - The path to the directory to change to.
      Returns:
      true if the directory was successfully changed; false otherwise.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException

    • delFile

      public boolean delFile(String filePath)
      Description copied from interface: Ftp
      Deletes a specified file on the remote FTP server.
      Parameters:
      filePath - The path to the file to delete.
      Returns:
      true if the file was deleted successfully; false otherwise.

    • delDir

      public boolean delDir(String dirPath)
      Description copied from interface: Ftp
      Deletes a directory and all its contents (files and subdirectories) recursively on the remote FTP server.
      Parameters:
      dirPath - The path to the directory to delete.
      Returns:
      true if the directory and its contents were deleted successfully; false otherwise.

    • upload

      public void upload(String remotePath, File file)
      Recursively uploads a local file or folder to a remote path, overwriting existing files.
      Parameters:
      remotePath - The remote path.
      file - The local file or folder to upload.

    • uploadFile

      public boolean uploadFile(String destPath, File file)
      Description copied from interface: Ftp
      Uploads a local file to the target server. The destination path on the server can be specified. If destPath is a directory, the file will be uploaded with its original name into that directory. This operation typically overwrites existing files with the same name.
      Parameters:
      destPath - The destination path on the server. Can be null (uploads to current working directory), a relative path, or an absolute path. If it's a directory, the file's original name is used.
      file - The local File object to upload.
      Returns:
      true if the upload was successful; false otherwise.

    • uploadFile

      public void uploadFile(String destPath, String fileName, InputStream fileStream)
      Uploads a file from an InputStream to the specified remote directory.
      Parameters:
      destPath - The destination path on the server.
      fileName - The filename.
      fileStream - The file input stream.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs.

    • put

      public JschSftp put(String srcFilePath, String destPath)
      Uploads a local file to the target server, overwriting existing files.
      Parameters:
      srcFilePath - The local file path.
      destPath - The target path.
      Returns:
      This JschSftp instance.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs.

    • put

      public JschSftp put(String srcFilePath, String destPath, JschSftp.Mode mode)
      Uploads a local file to the target server with a specified transfer mode.
      Parameters:
      srcFilePath - The local file path.
      destPath - The target path.
      mode - The JschSftp.Mode for file transfer.
      Returns:
      This JschSftp instance.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs.

    • put

      public JschSftp put(String srcFilePath, String destPath, com.jcraft.jsch.SftpProgressMonitor monitor, JschSftp.Mode mode)
      Uploads a local file to the target server with a progress monitor and transfer mode.
      Parameters:
      srcFilePath - The local file path.
      destPath - The target path.
      monitor - The upload progress monitor.
      mode - The JschSftp.Mode for file transfer.
      Returns:
      This JschSftp instance.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs.

    • put

      public JschSftp put(InputStream srcStream, String destPath, com.jcraft.jsch.SftpProgressMonitor monitor, JschSftp.Mode mode)
      Uploads a local data stream to the target server.
      Parameters:
      srcStream - The local data stream.
      destPath - The target path.
      monitor - The upload progress monitor.
      mode - The JschSftp.Mode for file transfer.
      Returns:
      This JschSftp instance.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs.

    • download

      public void download(String remotePath, File destFile)
      Description copied from interface: Ftp
      Downloads a file from the remote FTP server to a specified local file or directory. If outFile is a directory, the downloaded file will be saved into it with its original name.
      Parameters:
      remotePath - The path to the file on the remote FTP server.
      destFile - The local File or directory where the downloaded file should be saved.

    • download

      public void download(String src, OutputStream out)
      Downloads a file to an OutputStream.
      Parameters:
      src - The source file path on the remote server.
      out - The target output stream.

    • recursiveDownloadFolder

      public void recursiveDownloadFolder(String remotePath, File targetDir)
      Description copied from interface: Ftp
      Recursively downloads files and directories from the FTP server to the local machine, synchronizing the file structures. Existing local files will be overwritten by newer files from the server.
      Parameters:
      remotePath - The source directory on the FTP server to download from.
      targetDir - The target directory on the local machine where files will be saved.

    • get

      public JschSftp get(String src, String dest)
      Retrieves a remote file and saves it to a local path.
      Parameters:
      src - The remote file path.
      dest - The target file path.
      Returns:
      This JschSftp instance.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs.

    • get

      public JschSftp get(String src, OutputStream out)
      Retrieves a remote file and writes it to an output stream.
      Parameters:
      src - The remote file path.
      out - The target output stream.
      Returns:
      This JschSftp instance.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an SftpException occurs.

    • getFileStream

      public InputStream getFileStream(String path)
      Description copied from interface: Ftp
      Reads a file from the FTP server and provides its content as an InputStream. This allows for streaming processing of remote file content.
      Parameters:
      path - The path to the file on the FTP server.
      Returns:
      An InputStream providing access to the file's content.

    • close

      public void close()

    • toString

      public String toString()
      Overrides:
      toString in class Object