Package org.bluezoo.gumdrop.ftp.file

Class BasicFTPFileSystem

java.lang.Object
org.bluezoo.gumdrop.ftp.file.BasicFTPFileSystem
All Implemented Interfaces:
FTPFileSystem
public class BasicFTPFileSystem extends Object implements FTPFileSystem
Concrete FTPFileSystem backed by the local OS file system. Implements the NVFS (RFC 959 section 2.2) and TVFS (RFC 3659 section 6) semantics with a chrooted root directory.

Security Features:

  • Path normalization prevents ../ directory traversal
  • Symbolic links are resolved securely
  • Access is limited to the configured root directory tree
  • File permissions are checked before operations

Performance Features:

  • Uses NIO for file metadata operations
  • Efficient directory listing with lazy loading
  • Stream-based file I/O for memory efficiency
  • Skip-ahead support for resumed downloads
Author:
Chris Burdess

  • Constructor Details

    • BasicFTPFileSystem

      public BasicFTPFileSystem(String rootDirectory, boolean readOnly)
      Creates a new BasicFTPFileSystem with the specified root directory.
      Parameters:
      rootDirectory - the root directory for this file system
      readOnly - true to make this file system read-only
      Throws:
      IllegalArgumentException - if rootDirectory doesn't exist or isn't a directory

    • BasicFTPFileSystem

      public BasicFTPFileSystem(Path rootDirectory, boolean readOnly)
      Creates a new BasicFTPFileSystem with the specified root directory.
      Parameters:
      rootDirectory - the root directory path for this file system
      readOnly - true to make this file system read-only
      Throws:
      IllegalArgumentException - if rootDirectory doesn't exist or isn't a directory

    • BasicFTPFileSystem

      public BasicFTPFileSystem(String rootDirectory)
      Creates a read-write BasicFTPFileSystem.

  • Method Details

    • resolveSecurePath

      protected Path resolveSecurePath(String ftpPath)
      Converts an FTP path to a secure local file system path. Prevents directory traversal attacks and ensures the path stays within the root.
      Parameters:
      ftpPath - FTP path (Unix-style, starting with /)
      Returns:
      resolved local path within the root directory
      Throws:
      SecurityException - if path tries to escape the root directory

    • listDirectory

      public List<FTPFileInfo> listDirectory(String path, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Lists the contents of a directory. Used for FTP LIST and NLST commands.
      Specified by:
      listDirectory in interface FTPFileSystem
      Parameters:
      path - the directory path to list (Unix-style, starting with "/")
      metadata - connection metadata for authorization context
      Returns:
      list of file information, or null if the operation failed

    • changeDirectory

      public FTPFileSystem.DirectoryChangeResult changeDirectory(String path, String currentDirectory, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Changes the current working directory. Used for FTP CWD command.
      Specified by:
      changeDirectory in interface FTPFileSystem
      Parameters:
      path - the new directory path (can be relative or absolute)
      currentDirectory - the current directory before the change
      metadata - connection metadata for authorization context
      Returns:
      operation result and the new absolute directory path

    • getFileInfo

      public FTPFileInfo getFileInfo(String path, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Gets information about a specific file or directory. Used for various FTP commands that need to check file existence/properties.
      Specified by:
      getFileInfo in interface FTPFileSystem
      Parameters:
      path - the file or directory path
      metadata - connection metadata for authorization context
      Returns:
      file information, or null if the file/directory does not exist

    • createDirectory

      public FTPFileOperationResult createDirectory(String path, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Creates a new directory. Used for FTP MKD command.
      Specified by:
      createDirectory in interface FTPFileSystem
      Parameters:
      path - the directory path to create
      metadata - connection metadata for authorization context
      Returns:
      operation result

    • removeDirectory

      public FTPFileOperationResult removeDirectory(String path, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Removes an empty directory. Used for FTP RMD command.
      Specified by:
      removeDirectory in interface FTPFileSystem
      Parameters:
      path - the directory path to remove
      metadata - connection metadata for authorization context
      Returns:
      operation result

    • deleteFile

      public FTPFileOperationResult deleteFile(String path, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Deletes a file. Used for FTP DELE command.
      Specified by:
      deleteFile in interface FTPFileSystem
      Parameters:
      path - the file path to delete
      metadata - connection metadata for authorization context
      Returns:
      operation result

    • rename

      public FTPFileOperationResult rename(String fromPath, String toPath, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Renames or moves a file or directory. Used for FTP RNFR/RNTO command sequence.
      Specified by:
      rename in interface FTPFileSystem
      Parameters:
      fromPath - the current path of the file/directory
      toPath - the new path for the file/directory
      metadata - connection metadata for authorization context
      Returns:
      operation result

    • openForReading

      public ReadableByteChannel openForReading(String path, long restartOffset, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Opens a file for reading (download) using NIO channels. Used for FTP RETR command.

      This method provides high-performance file reading with:

      • Zero-copy transfers when possible
      • Direct integration with SocketChannel
      • Memory-efficient streaming for large files
      • Restart offset support for resumed downloads
      Specified by:
      openForReading in interface FTPFileSystem
      Parameters:
      path - the file path to read
      restartOffset - byte offset to start reading from (for REST command)
      metadata - connection metadata for authorization context
      Returns:
      readable channel for the file data, or null if the operation failed

    • openForWriting

      public WritableByteChannel openForWriting(String path, boolean append, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Opens a file for writing (upload) using NIO channels. Used for FTP STOR command.

      This method provides high-performance file writing with:

      • Zero-copy transfers when possible
      • Direct integration with SocketChannel
      • Memory-efficient streaming for large files
      • Append mode support
      Specified by:
      openForWriting in interface FTPFileSystem
      Parameters:
      path - the file path to write
      append - true to append to existing file, false to overwrite
      metadata - connection metadata for authorization context
      Returns:
      writable channel for writing file data, or null if the operation failed

    • generateUniqueName

      public FTPFileSystem.UniqueNameResult generateUniqueName(String basePath, String suggestedName, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Generates a unique file name for store-unique operations. Used for FTP STOU command.
      Specified by:
      generateUniqueName in interface FTPFileSystem
      Parameters:
      basePath - the base directory path
      suggestedName - suggested file name (can be null)
      metadata - connection metadata for authorization context
      Returns:
      unique file name result

    • allocateSpace

      public FTPFileOperationResult allocateSpace(String path, long size, FTPConnectionMetadata metadata)
      Description copied from interface: FTPFileSystem
      Allocates space for a file (optional operation). Used for FTP ALLO command - many implementations can ignore this.
      Specified by:
      allocateSpace in interface FTPFileSystem
      Parameters:
      path - the file path that will need space
      size - the number of bytes to allocate
      metadata - connection metadata for authorization context
      Returns:
      operation result

    • getRootPath

      public Path getRootPath()
      Gets the root directory path for this file system.

    • isReadOnly

      public boolean isReadOnly()
      Checks if this file system is read-only.