Skip to content

Commit e9daf1f

Browse files
javaqueryjavaquery
committed
Refactor JFTPClient and update README with library features and usage examples
1 parent 3ad09b6 commit e9daf1f

File tree

2 files changed

+175
-10
lines changed

2 files changed

+175
-10
lines changed

‎README.md‎

Lines changed: 165 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,165 @@
1-
# ftpclient
2-
Java FTP Client
1+
# FTP Client Library
2+
3+
A lightweight and easy-to-use Java FTP client library that provides a unified interface for FTP, FTPS, and SFTP file transfers.
4+
5+
## Features
6+
7+
- **Unified Interface**: Single API for FTP, FTPS, and SFTP protocols
8+
- **Simple Integration**: Easy to integrate with minimal configuration
9+
- **File Operations**: Upload, download, delete, and list files
10+
- **File Filtering**: Filter files based on custom criteria
11+
- **Timeout Configuration**: Configurable connection and socket timeouts
12+
- **Secure Connections**: Support for FTPS (FTP over SSL/TLS) and SFTP (SSH File Transfer Protocol)
13+
14+
## Dependencies
15+
16+
This library uses the following dependencies:
17+
- Apache Commons Net (for FTP/FTPS)
18+
- JSch (for SFTP)
19+
- Lombok (for cleaner code)
20+
- SLF4J (for logging)
21+
22+
## Installation
23+
24+
### Gradle
25+
26+
```gradle
27+
dependencies {
28+
implementation 'com.javaquery:ftpclient:1.0.0'
29+
}
30+
```
31+
32+
### Maven
33+
34+
```xml
35+
<dependency>
36+
<groupId>com.javaquery</groupId>
37+
<artifactId>ftpclient</artifactId>
38+
<version>1.0.0</version>
39+
</dependency>
40+
```
41+
42+
## Quick Start
43+
44+
```java
45+
import com.javaquery.ftp.Credentials;
46+
import com.javaquery.ftp.FTPType;
47+
import com.javaquery.ftp.JFTPClient;
48+
49+
public class FTPExample {
50+
public static void main(String[] args) {
51+
// Create credentials
52+
Credentials credentials = Credentials.builder()
53+
.host("ftp.example.com")
54+
.port(21)
55+
.username("your-username")
56+
.password("your-password")
57+
.build();
58+
59+
// Create FTP client (use FTPType.FTPS or FTPType.SFTP for secure connections)
60+
JFTPClient ftpClient = new JFTPClient(FTPType.FTP);
61+
62+
try {
63+
// Connect to server
64+
ftpClient.connect(credentials);
65+
System.out.println("Connected successfully!");
66+
67+
// Perform file operations here
68+
69+
} catch (Exception e) {
70+
e.printStackTrace();
71+
} finally {
72+
// Disconnect
73+
ftpClient.disconnect();
74+
}
75+
}
76+
}
77+
```
78+
79+
## API Reference
80+
81+
### JFTPClient
82+
83+
Main client class for FTP operations.
84+
85+
#### Constructor
86+
- `JFTPClient(FTPType ftpType)` - Creates a new client instance for the specified protocol type
87+
88+
#### Methods
89+
- `void connect(Credentials credentials)` - Establishes connection to the FTP server
90+
- `void disconnect()` - Closes the connection to the FTP server
91+
- `List<RemoteFile> listFiles(String directoryPath, FileFilter<RemoteFile> fileFilter)` - Lists files in the specified directory with optional filtering
92+
- `boolean uploadFile(String localFilePath, String remoteFilePath)` - Uploads a file to the server
93+
- `boolean downloadFile(String remoteFilePath, String localFilePath)` - Downloads a file from the server
94+
- `boolean deleteFile(String remoteFilePath)` - Deletes a file from the server
95+
96+
### FTPType
97+
98+
Enum for specifying the protocol type.
99+
100+
**Values:**
101+
- `FTP` - Standard FTP protocol
102+
- `FTPS` - FTP over SSL/TLS
103+
- `SFTP` - SSH File Transfer Protocol
104+
105+
### Credentials
106+
107+
Builder class for connection credentials.
108+
109+
**Properties:**
110+
- `host` - FTP server hostname or IP address
111+
- `port` - FTP server port (default: 21 for FTP/FTPS, 22 for SFTP)
112+
- `username` - Username for authentication
113+
- `password` - Password for authentication
114+
- `connectTimeout` - Connection timeout in milliseconds (default: 15000)
115+
- `socketTimeout` - Socket timeout in milliseconds (default: 60000)
116+
- `isImplicit` - Use implicit FTPS mode (default: false)
117+
118+
### RemoteFile
119+
120+
Represents a file or directory on the remote server.
121+
122+
**Properties:**
123+
- `name` - File or directory name
124+
- `isFile` - Whether this is a file
125+
- `isDirectory` - Whether this is a directory
126+
- `size` - File size in bytes
127+
- `timestamp` - Last modified timestamp
128+
- `path` - Full path on the server
129+
130+
### FileFilter
131+
132+
Functional interface for filtering files.
133+
134+
**Method:**
135+
- `boolean accept(RemoteFile file)` - Returns true if the file should be included in the results
136+
137+
## Error Handling
138+
139+
The library throws `FTPException` for all FTP-related errors. Always wrap operations in try-catch blocks:
140+
141+
```java
142+
try {
143+
ftpClient.connect(credentials);
144+
// Perform operations
145+
} catch (FTPException e) {
146+
System.err.println("FTP Error: " + e.getMessage());
147+
e.printStackTrace();
148+
} finally {
149+
ftpClient.disconnect();
150+
}
151+
```
152+
153+
## Best Practices
154+
155+
1. **Always disconnect**: Use try-finally blocks to ensure disconnection
156+
2. **Configure timeouts**: Set appropriate timeout values based on your network conditions
157+
3. **Handle exceptions**: Properly handle `FTPException` in your code
158+
4. **Use filters**: Leverage `FileFilter` for efficient file listing
159+
5. **Validate paths**: Ensure file paths are valid before operations
160+
6. **Logging**: Configure SLF4J for proper logging support
161+
162+
## Requirements
163+
164+
- Java 8 or higher
165+
- Internet connectivity to FTP server

‎src/main/java/com/javaquery/ftp/JFTPClient.java‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,15 @@
88
/**
99
* @author javaquery
1010
* @since 2025-10-30
11+
* <p>
12+
* Client for handling FTP, SFTP, and FTPS file transfers using a unified interface.
1113
*/
1214
public class JFTPClient {
1315

1416
private final FileTransferClient fileTransferClient;
1517

16-
public JFTPClient(FTPType ftpType){
17-
switch (ftpType){
18+
public JFTPClient(FTPType ftpType) {
19+
switch (ftpType) {
1820
case FTP:
1921
this.fileTransferClient = new FTPClientImpl();
2022
break;
@@ -29,27 +31,27 @@ public JFTPClient(FTPType ftpType){
2931
}
3032
}
3133

32-
public void connect(Credentials credentials) throws FTPException{
34+
public void connect(Credentials credentials) throws FTPException {
3335
fileTransferClient.connect(credentials);
3436
}
3537

36-
public void disconnect() throws FTPException{
38+
public void disconnect() throws FTPException {
3739
fileTransferClient.disconnect();
3840
}
3941

40-
public List<RemoteFile> listFiles(String directoryPath, FileFilter<RemoteFile> fileFilter) throws FTPException{
42+
public List<RemoteFile> listFiles(String directoryPath, FileFilter<RemoteFile> fileFilter) throws FTPException {
4143
return fileTransferClient.listFiles(directoryPath, fileFilter);
4244
}
4345

44-
public boolean uploadFile(String localFilePath, String remoteFilePath) throws FTPException{
46+
public boolean uploadFile(String localFilePath, String remoteFilePath) throws FTPException {
4547
return fileTransferClient.uploadFile(localFilePath, remoteFilePath);
4648
}
4749

48-
public boolean downloadFile(String remoteFilePath, String localFilePath) throws FTPException{
50+
public boolean downloadFile(String remoteFilePath, String localFilePath) throws FTPException {
4951
return fileTransferClient.downloadFile(remoteFilePath, localFilePath);
5052
}
5153

52-
public boolean deleteFile(String remoteFilePath) throws FTPException{
54+
public boolean deleteFile(String remoteFilePath) throws FTPException {
5355
return fileTransferClient.deleteFile(remoteFilePath);
5456
}
5557
}

0 commit comments

Comments
 (0)