Module bus.extra
Package org.miaixz.bus.extra.ftp

Interface Ftp

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
AbstractFtp, CommonsFtp, JschSftp, SshjSftp
public interface Ftp extends Closeable
Unified interface for FTP (File Transfer Protocol) operations. This interface defines a set of common file transfer and management operations that can be performed on a remote FTP server, abstracting away the specifics of different FTP client implementations.
Since:
Java 17+
Author:
Kimi Liu

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Charset
    DEFAULT_CHARSET
    The default character set used for FTP operations, typically UTF-8.

  • 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.
    boolean
    delDir(String dirPath)
    Deletes a directory and all its contents (files and subdirectories) recursively on the remote FTP server.
    boolean
    delFile(String path)
    Deletes a specified file on the remote FTP server.
    void
    download(String path, File outFile)
    Downloads a file from the remote FTP server to a specified local file or directory.
    boolean
    exist(String path)
    Checks if a file or directory exists at the specified path on the remote server.
    FtpConfig
    getConfig()
    Retrieves the FTP configuration associated with this FTP client instance.
    InputStream
    getFileStream(String path)
    Reads a file from the FTP server and provides its content as an InputStream.
    default 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).
    boolean
    mkdir(String dir)
    Creates a new directory in the current remote working directory.
    void
    mkDirs(String dir)
    Creates the specified folder and any necessary parent directories on the remote server.
    String
    pwd()
    Retrieves the current remote directory (working directory) on the FTP server.
    Ftp
    reconnectIfTimeout()
    Reconnects to the FTP server if the current connection has timed out or become stale.
    void
    recursiveDownloadFolder(String sourceDir, 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.
    default boolean
    toParent()
    Changes the current working directory to the parent directory.
    boolean
    uploadFile(String destPath, File file)
    Uploads a local file to the target server.

    Methods inherited from interface java.io.Closeable

    close

  • Field Details

    • DEFAULT_CHARSET

      static final Charset DEFAULT_CHARSET
      The default character set used for FTP operations, typically UTF-8.

  • Method Details

    • getConfig

      FtpConfig getConfig()
      Retrieves the FTP configuration associated with this FTP client instance.
      Returns:
      The FtpConfig object containing connection and operational settings.

    • reconnectIfTimeout

      Ftp reconnectIfTimeout()
      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.

    • pwd

      String pwd()
      Retrieves the current remote directory (working directory) on the FTP server.
      Returns:
      The absolute path of the current working directory as a String.

    • cd

      boolean cd(String directory)
      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.

    • toParent

      default boolean toParent()
      Changes the current working directory to the parent directory. This is a convenience method that calls cd(String) with Symbol.DOUBLE_DOT.
      Returns:
      true if the parent directory was successfully changed; false otherwise.

    • exist

      boolean exist(String path)
      Checks if a file or directory exists at the specified path on the remote server. Special handling is provided for empty paths, and paths ending with directory separators but not representing actual directories, or special directory names like "." or "..".
      Parameters:
      path - The path to the file or directory to check.
      Returns:
      true if the file or directory exists; false otherwise.

    • isDir

      default boolean isDir(String dir)
      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.

    • rename

      boolean rename(String oldPath, String newPath)
      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

      boolean mkdir(String dir)
      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.

    • mkDirs

      void mkDirs(String dir)
      Creates the specified folder and any necessary parent directories on the remote server. This method ensures that the full path exists. After creation, the working directory is reset to its default or initial state.
      Parameters:
      dir - The absolute path of the folder to create.

    • ls

      List<String> ls(String path)
      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.

    • delFile

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

    • delDir

      boolean delDir(String dirPath)
      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.

    • uploadFile

      boolean uploadFile(String destPath, File file)
      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.

    • download

      void download(String path, File outFile)
      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:
      path - The path to the file on the remote FTP server.
      outFile - The local File or directory where the downloaded file should be saved.

    • recursiveDownloadFolder

      void recursiveDownloadFolder(String sourceDir, File targetDir)
      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:
      sourceDir - The source directory on the FTP server to download from.
      targetDir - The target directory on the local machine where files will be saved.

    • getFileStream

      InputStream getFileStream(String path)
      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.