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

Class CommonsFtp

java.lang.Object
org.miaixz.bus.extra.ftp.AbstractFtp
org.miaixz.bus.extra.ftp.CommonsFtp
All Implemented Interfaces:
Closeable, AutoCloseable, Ftp
public class CommonsFtp extends AbstractFtp
FTP client wrapper based on Apache Commons Net. Common tools for setting up FTP servers include:
  • FileZilla Server: The root directory is generally empty.
  • Linux vsftpd: Uses the system user's directory, which is often not the root directory, e.g., /home/bus/ftp.
Since:
Java 17+
Author:
Kimi Liu

  • Constructor Details

    • CommonsFtp

      public CommonsFtp(FtpConfig config, org.miaixz.bus.core.lang.EnumValue.Lifecycle lifecycle)
      Constructor.
      Parameters:
      config - The FTP configuration.
      lifecycle - The connection lifecycle (ACTIVE or PASSIVE).

    • CommonsFtp

      public CommonsFtp(org.apache.commons.net.ftp.FTPClient client)
      Constructor with a custom-instantiated FTPClient.
      Parameters:
      client - The pre-configured FTPClient.

  • Method Details

    • of

      public static CommonsFtp of(String host)
      Creates a CommonsFtp instance with anonymous login.
      Parameters:
      host - The domain name or IP address.
      Returns:
      A new CommonsFtp instance.

    • of

      public static CommonsFtp of(String host, int port)
      Creates a CommonsFtp instance with anonymous login.
      Parameters:
      host - The domain name or IP address.
      port - The port number.
      Returns:
      A new CommonsFtp instance.

    • of

      public static CommonsFtp of(String host, int port, String user, String password)
      Creates a CommonsFtp instance.
      Parameters:
      host - The domain name or IP address.
      port - The port number.
      user - The username.
      password - The password.
      Returns:
      A new CommonsFtp instance.

    • of

      public static CommonsFtp of(Connector connector, Charset charset)
      Creates a CommonsFtp instance.
      Parameters:
      connector - The connection information, including host, port, user, password, etc.
      charset - The character encoding.
      Returns:
      A new CommonsFtp instance.

    • of

      public static CommonsFtp of(Connector connector, Charset charset, String serverLanguageCode, String systemKey)
      Creates a CommonsFtp instance.
      Parameters:
      connector - The connection information, including host, port, user, password, etc.
      charset - The character encoding.
      serverLanguageCode - The server language code (e.g., "zh").
      systemKey - The server system key (e.g., org.apache.commons.net.ftp.FTPClientConfig.SYST_NT).
      Returns:
      A new CommonsFtp instance.

    • of

      public static CommonsFtp of(Connector connector, Charset charset, String serverLanguageCode, String systemKey, org.miaixz.bus.core.lang.EnumValue.Lifecycle lifecycle)
      Creates a CommonsFtp instance.
      Parameters:
      connector - The connection information, including host, port, user, password, etc.
      charset - The character encoding.
      serverLanguageCode - The server language code.
      systemKey - The system key.
      lifecycle - The connection lifecycle.
      Returns:
      A new CommonsFtp instance.

    • init

      public CommonsFtp init()
      Initializes the connection.
      Returns:
      this

    • init

      public CommonsFtp init(FtpConfig config, org.miaixz.bus.core.lang.EnumValue.Lifecycle lifecycle)
      Initializes the connection.
      Parameters:
      config - The FTP configuration.
      lifecycle - The connection lifecycle.
      Returns:
      this

    • setMode

      public CommonsFtp setMode(org.miaixz.bus.core.lang.EnumValue.Lifecycle lifecycle)
      Sets the FTP connection lifecycle (ACTIVE or PASSIVE).
      Parameters:
      lifecycle - The lifecycle enumeration.
      Returns:
      this

    • isBackToPwd

      public boolean isBackToPwd()
      Gets whether to return to the current directory after an operation.
      Returns:
      True if it returns to the current directory, false otherwise.

    • setBackToPwd

      public CommonsFtp setBackToPwd(boolean backToPwd)
      Sets whether to return to the current directory after an operation.
      Parameters:
      backToPwd - True to return to the current directory, false otherwise.
      Returns:
      this

    • reconnectIfTimeout

      public CommonsFtp reconnectIfTimeout()
      Reconnects if the connection has timed out. It has been tested that when the connection times out, client.isConnected() still returns true, so it is not possible to determine if the connection has timed out. Therefore, the connection status is checked by sending a PWD command.
      Returns:
      this

    • cd

      public boolean cd(String directory)
      Changes the current directory.
      Parameters:
      directory - The target directory.
      Returns:
      True if successful, false otherwise.

    • pwd

      public String pwd()
      Gets the current remote directory.
      Returns:
      The current remote directory path.

    • 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.

    • ls

      public List<String> ls(String path, Predicate<org.apache.commons.net.ftp.FTPFile> predicate)
      Lists all files and directories in a given path without recursion. This method automatically filters out "." and "..".
      Parameters:
      path - The directory path.
      predicate - A filter for the files. If null, no filtering is applied (besides removing "." and "..").
      Returns:
      A list of file or directory names.

    • lsFiles

      public List<org.apache.commons.net.ftp.FTPFile> lsFiles(String path, Predicate<org.apache.commons.net.ftp.FTPFile> predicate)
      Lists all files and directories in a given path without recursion. This method automatically filters out "." and "..".
      Parameters:
      path - The directory path.
      predicate - A filter for the files. If null, no filtering is applied (besides removing "." and "..").
      Returns:
      A list of files or directories.

    • lsFiles

      public org.apache.commons.net.ftp.FTPFile[] lsFiles(String path) throws org.miaixz.bus.core.lang.exception.InternalException
      Lists all files and directories in a given path without recursion.
      Parameters:
      path - The directory path. If the directory does not exist, an exception is thrown.
      Returns:
      An array of files or directories.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an I/O error occurs.

    • 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) throws org.miaixz.bus.core.lang.exception.InternalException
      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.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException

    • stat

      public int stat(String path) throws org.miaixz.bus.core.lang.exception.InternalException
      Gets the status of a directory on the server.
      Parameters:
      path - The path.
      Returns:
      An integer status code, which varies by server.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an I/O error occurs.

    • existFile

      public boolean existFile(String path) throws org.miaixz.bus.core.lang.exception.InternalException
      Checks if a directory on the FTP server has any sub-elements (directories or files).
      Parameters:
      path - The file path.
      Returns:
      True if it exists, false otherwise.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an I/O error occurs.

    • delFile

      public boolean delFile(String path) throws org.miaixz.bus.core.lang.exception.InternalException
      Description copied from interface: Ftp
      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.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException

    • delDir

      public boolean delDir(String dirPath) throws org.miaixz.bus.core.lang.exception.InternalException
      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.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException

    • uploadFile

      public boolean uploadFile(String remotePath, File file)
      Uploads a file to the specified directory. Options: 
       1. If remotePath is null or "", upload to the current path.
 2. If remotePath is a relative path, upload to a sub-path of the current path.
 3. If remotePath is an absolute path, upload to that path.
      Parameters:
      remotePath - The server path, which can be null, a relative path, or an absolute path.
      file - The file to upload.
      Returns:
      True if the upload is successful, false otherwise.

    • uploadFile

      public boolean uploadFile(String remotePath, String fileName, File file) throws org.miaixz.bus.core.lang.exception.InternalException
      Uploads a file to the specified directory. Options are the same as above.
      Parameters:
      remotePath - The server path, which can be null, a relative path, or an absolute path.
      fileName - A custom file name to save on the server.
      file - The file to upload.
      Returns:
      True if the upload is successful, false otherwise.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an I/O error occurs.

    • uploadFile

      public boolean uploadFile(String remotePath, String fileName, InputStream fileStream) throws org.miaixz.bus.core.lang.exception.InternalException
      Uploads a file to the specified directory. Options are the same as above.
      Parameters:
      remotePath - The server path, which can be null, a relative path, or an absolute path.
      fileName - The file name.
      fileStream - The file stream.
      Returns:
      True if the upload is successful, false otherwise.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an I/O error occurs.

    • upload

      public void upload(String remotePath, File uploadFile)
      Recursively uploads files (including directories). When uploading, if uploadFile is a directory, only its contents (subdirectories and files) are copied to the target path, not the directory itself. Parent directories are created automatically during upload.
      Parameters:
      remotePath - The directory path.
      uploadFile - The file or directory to upload.

    • download

      public void download(String path, File outFile)
      Downloads a file.
      Parameters:
      path - The file path, including the file name.
      outFile - The output file or directory. If a directory, the server's file name is used.

    • recursiveDownloadFolder

      public void recursiveDownloadFolder(String sourceDir, File targetDir)
      Recursively downloads files from an FTP server to a local directory, syncing the structure.
      Parameters:
      sourceDir - The source directory on the FTP server.
      targetDir - The target local directory.

    • download

      public boolean download(String path, String fileName, File outFile) throws org.miaixz.bus.core.lang.exception.InternalException
      Downloads a file.
      Parameters:
      path - The file's path (remote directory), excluding the file name.
      fileName - The file name.
      outFile - The output file or directory. If a directory, the server's file name is used.
      Returns:
      True if the download is successful, false otherwise.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an I/O error occurs.

    • download

      public boolean download(String path, String fileName, OutputStream out)
      Downloads a file to an output stream.
      Parameters:
      path - The file path.
      fileName - The file name.
      out - The output location.
      Returns:
      True if the download is successful, false otherwise.

    • download

      public boolean download(String path, String fileName, OutputStream out, Charset fileNameCharset) throws org.miaixz.bus.core.lang.exception.InternalException
      Downloads a file to an output stream.
      Parameters:
      path - The server's file path.
      fileName - The server's file name.
      out - The output stream to write the downloaded file to.
      fileNameCharset - The character set for the file name.
      Returns:
      True if the download is successful, false otherwise.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an I/O error 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.

    • getFileStream

      public InputStream getFileStream(String dir, String fileName) throws org.miaixz.bus.core.lang.exception.InternalException
      Reads a file as an input stream.
      Parameters:
      dir - The server's file directory.
      fileName - The server's file name.
      Returns:
      An InputStream.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if an I/O error occurs.

    • getClient

      public org.apache.commons.net.ftp.FTPClient getClient()
      Gets the FTPClient object.
      Returns:
      The FTPClient.

    • close

      public void close() throws IOException
      Throws:
      IOException