ballerina/ftp

Overview

This module provides an FTP client and an FTP server listener implementation to facilitate an FTP connection connected to a remote location.

FTP Client

The ftp:Client connects to an FTP server and performs various operations on the files. Currently, it supports the generic FTP operations; get, delete, put, append, mkdir, rmdir, isDirectory, rename, size, and list.

An FTP client endpoint is defined using the protocol and host parameters and optionally the port and secureSocket. Authentication configuration can be configured using the secureSocket parameter for Basic Auth, private key, or TrustStore/Keystore.

Creating a Client

The following code creates an FTP client and performs the I/O operations, which connect to the FTP server with Basic Auth.

1// Define the FTP client configuration.
2ftp:ClientEndpointConfig ftpConfig = {
3 protocol: ftp:FTP,
4 host: "<The FTP host>",
5 port: <The FTP port>,
6 secureSocket: {
7 basicAuth: {
8 username: "<The FTP username>",
9 password: "<The FTP passowrd>"
10 }
11 }
12};
13
14// Create the FTP client.
15ftp:Client ftpClient = new(ftpConfig);
Creating a Directory

The following code creates a directory in the remote FTP server.

1ftp:Error? mkdirResponse = ftpClient->mkdir("<The directory path>");
Uploading File to a Remote Server

The following code uploads a file to a remote FTP server.

1stream<io:Block, io:Error?> fileByteStream
2 = check io:fileReadBlocksAsStream(putFilePath, <Block size>);
3ftp:Error? putResponse = ftpClient->put("<The resource path>", fileByteStream);
Compressing and Uploading a File to a Remote Server

The following code compresses and uploads a file to a remote FTP server.

1// Set the optional boolean flag as 'true' to compress before uploading
2stream<io:Block, io:Error?> fileByteStream
3 = check io:fileReadBlocksAsStream(putFilePath, <Block size>);
4ftp:Error? compressedPutResponse = ftpClient->put("<Resource path>",
5 fileByteStream, true);
Getting the Size of a Remote File

The following code gets the size of a file in a remote FTP server.

1int|ftp:Error sizeResponse = ftpClient->size("<The resource path>");
Reading the Content of a Remote File

The following code reads the content of a file in a remote FTP server.

1stream<byte[], io:Error?>|Error str = clientEP -> get("<The file path>", <Block size>);
2if (str is stream<byte[], io:Error?>) {
3 record {|byte[] value;|}|io:Error? arr1 = str.next();
4 if (arr1 is record {|byte[] value;|}) {
5 string fileContent = check strings:fromBytes(arr1.value);
6 // `fileContent` is the `string` value of first byte array
7 record {|byte[] value;|}|io:Error? arr2 = str.next();
8 // Similarly following content chunks can be iteratively read with `next` method.
9 // Final chunk will contain the terminal value which is `()`.
10 }
11 io:Error? closeResult = str.close();
12}
Renaming or Moving a Remote file to Another Remote Location in the Same FTP Server

The following code renames or moves a file to another location in the same remote FTP server.

1ftp:Error? renameResponse = ftpClient->rename("<The source file path>",
2 "<The destination file path>");
Deleting a Remote File

The following code deletes a remote file in a remote FTP server.

1ftp:Error? deleteResponse = ftpClient->delete("<The resource path>");
Removing a Directory From a Remote Server

The following code removes a directory in a remote FTP server.

1ftp:Error? rmdirResponse = ftpClient->rmdir("<The directory path>");

###FTP Listener

The ftp:Listener is used to listen to a remote FTP location and trigger a WatchEvent type of event when new files are added to or deleted from the directory. The fileResource function is invoked when a new file is added and/or deleted.

An FTP listener endpoint is defined using the mandatory protocol, host, and path parameters. The authentication configuration can be done using a secureSocket and the polling interval can be configured using the pollingInterval parameter. The default polling interval is 60 seconds.

The fileNamePattern parameter can be used to define the type of files the FTP listener endpoint will listen to. For instance, if the listener gets invoked for text files, the value (.*).txt can be given for the config.

Creating a Listener

The FTP Listener can be used to listen to a remote directory. It will keep listening to the specified directory and notify on file addition and deletion periodically.

1listener ftp:Listener remoteServer = new({
2 protocol: ftp:FTP,
3 host: "<The FTP host>",
4 secureSocket: {
5 basicAuth: {
6 username: "<The FTP username>",
7 password: "<The FTP passowrd>"
8 }
9 },
10 port: <The FTP port>,
11 path: "<The remote FTP direcotry location>",
12 pollingInterval: <Polling interval>,
13 fileNamePattern: "<File type>"
14});
15
16service ftpServerConnector on remoteServer {
17 resource function onFileChange(ftp:WatchEvent fileEvent) {
18
19 foreach ftp:FileInfo addedFile in fileEvent.addedFiles {
20 log:print("Added file path: " + addedFile.path);
21 }
22 foreach string deletedFile in fileEvent.deletedFiles {
23 log:print("Deleted file path: " + deletedFile);
24 }
25 }
26}

Listeners

[1]

Listener

Represents a service listener that monitors the FTP location.

Clients

[1]

Client

Represents an FTP client that intracts with an FTP server

Records

[10]

BasicAuth

Basic Auth related configurations.

ClientEndpointConfig

Configuration for FTP client endpoint.

FileInfo

Metadata for newly-added files.

InputContent

Configuration for the input given for put and append operations of the FTP module.

KeyStore

Configuration to connect to a key store.

ListenerConfig

Configuration for FTP listener endpoint.

PrivateKey

Configuration to read a privte key.

SecureSocket

Configurations for facilitating secure communication with a remote FTP server.

TrustStore

Configuration to connect to a trust store.

WatchEvent

This represents the latest status change of the server from the last status change.

Constants

[3]

FTP

Underlying communication happens using FTP

FTPS

Underlying communication happens using FTPS.

SFTP

Underlying communication happens using SFTP

Types

[1]

Protocol

Represents the set of protocols supported by the FTP listener and client

Errors

[1]

Error

Defines the common error type for the module