Bug 40811: Implement dual API for file transports with simplified auto-management
This patch implements a dual API design for Koha::File::Transport, providing
both a simplified auto-managing API and a traditional explicit API for maximum
flexibility and ease of use.
DUAL API DESIGN
===============
Simplified API (Recommended):
- Automatic connection management (no connect/disconnect needed)
- Flexible per-operation directory control via options hashref
- Stateless operations safe for concurrent usage
Example:
$transport->upload_file($local, $remote, { path => '/custom/' });
$transport->download_file($remote, $local); # Uses download_directory
$transport->list_files({ path => '/incoming/' });
Traditional API (Explicit Control):
- Manual connection/directory management when needed
- Stateful directory operations via change_directory()
- Ideal for multiple operations in the same directory
Example:
$transport->change_directory('/work/');
$transport->upload_file($local, 'file1.txt');
$transport->upload_file($local, 'file2.txt');
my $files = $transport->list_files();
The APIs can be mixed - calling change_directory() explicitly switches to
manual mode and disables auto-management for subsequent operations.
STANDARDIZED TEMPLATE METHOD PATTERN
=====================================
All transport methods now follow a consistent pattern with clear separation
between public API (parent class) and protocol implementation (subclasses).
Public methods in Koha::File::Transport:
- connect() â Resets directory state, calls _connect()
- disconnect() â Resets directory state, calls _disconnect()
- change_directory() â Sets manual mode flag, calls _change_directory()
- upload_file() â Manages connection/directory, calls _upload_file()
- download_file() â Manages connection/directory, calls _download_file()
- list_files() â Manages connection/directory, calls _list_files()
- rename_file() â Ensures connection, calls _rename_file()
Subclass responsibilities (SFTP/FTP/Local):
- Implement _connect() - Protocol-specific connection logic
- Implement _disconnect() - Protocol-specific disconnection logic
- Implement _change_directory() - Protocol-specific directory change
- Implement _upload_file() - Protocol-specific upload logic
- Implement _download_file() - Protocol-specific download logic
- Implement _list_files() - Protocol-specific listing logic
- Implement _rename_file() - Protocol-specific rename logic
- Implement _is_connected() - Protocol-specific connection check
Test plan:
prove t/db_dependent/Koha/File/Transports.t
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomás Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
b75d07acd5