Module Overview

This module provides an FTP client and an FTP server listener implementation to facilitate an FTP connection 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 parameters protocol and host, and optionally the port and secureSocket. Authentication configuration can be configured using the secureSocket parameter for basicAuth, private key, or TrustStore/Keystore.

Creating a client

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

1import ballerina/ftp;
3// Define FTP client configuration
4ftp:ClientEndpointConfig ftpConfig = {
5 protocol: ftp:FTP,
6 host: "<The FTP host>",
7 port: <The FTP port>,
8 secureSocket: {
9 basicAuth: {
10 username: "<The FTP username>",
11 password: "<The FTP passowrd>"
12 }
13 }
16// Create FTP client
17ftp: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>");
2if (mkdirResponse is ftp:Error) {
3 log:printError("Error occured in creating directory", err = mkdirResponse);
4 return;
Uploading file to a remote server

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

1io:ReadableByteChannel|error summaryChannel
2 = io:openReadableFile("<The local data source path>");
3if(summaryChannel is io:ReadableByteChannel){
4 ftp:Error? putResponse = ftpClient->put("<The resource path>", summaryChannel);
5 if(putResponse is ftp:Error) {
6 log:printError("Error occured in uploading content", err = putResponse);
7 return;
8 }
Compressing and uploading a file to a remote server

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

1io:ReadableByteChannel|error inputChannel
2 = io:openReadableFile("<Local data source path>");
3if (inputChannel is io:ReadableByteChannel) {
4 // Set the optional boolean flag as 'true' to compress before uploading
5 ftp:Error? compressedPutResponse = ftpClient->put("<Resource path>",
6 inputChannel, true);
7 if (compressedPutResponse is ftp:Error) {
8 log:printError("Error occured in uploading content",
9 err = compressedPutResponse);
10 return;
11 }
Getting the size of a remote file

The following code get and size of a file of a file in remote FTP server.

1var sizeResponse = ftpClient->size("<The resource path>");
2if (sizeResponse is int) {
3 log:print("File size: " + sizeResponse.toString());
4} else {
5 log:printError("Error occured in retrieving size", err = sizeResponse);
6 return;
Reading the content of a remote file

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

1var getResponse = ftpClient->get("<The file path>");
2if (getResponse is io:ReadableByteChannel) {
3 io:ReadableCharacterChannel? characters
4 = new io:ReadableCharacterChannel(getResponse, "utf-8");
5 if (characters is io:ReadableCharacterChannel) {
6 var output =<No of characters to read>);
7 if (output is string) {
8 log:print("File content: " + output);
9 } else {
10 log:printError("Error occured in retrieving content", err = output);
11 return;
12 }
13 var closeResult = characters.close();
14 if (closeResult is error) {
15 log:printError("Error occurred while closing the channel",
16 err = closeResult);
17 return;
18 }
19 }
20} else {
21 log:printError("Error occured in retrieving content", err = getResponse);
22 return;
Renaming or moving a remote file to another remote location in a same FTP server

The following rename or move remote 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>");
3if (renameResponse is ftp:Error) {
4 log:printError("Error occurred while renaming the file", err = renameResponse);
5 return;
Deleting a remote file

The following delete a remote file in a remote FTP server.

1ftp:Error? deleteResponse = ftpClient->delete("<The resource path>");
2if (deleteResponse is ftp:Error) {
3 log:printError("Error occurred while deleting a file", err = deleteResponse);
4 return;
Removing a directory from a remote server

The following remove a directory in a remote FTP server.

1var rmdirResponse = ftpClient->rmdir("<The directory path>");
2if (rmdirResponse is ftp:Error) {
3 io:println("Error occured in removing directory.", rmdirResponse);
4 return;

###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 parameters protocol, host and path. Authentication configuration can be done using secureSocket and polling interval can be configured using pollingInterval. 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 periodically notify on file addition and deletion.

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




Represents a service listener that monitors the FTP location.




Represents an FTP client that intracts with an FTP server




A record for providing BasicAuth related configurations


Configuration for FTP client endpoint.


This provides metadata information for newly added files.


Provides configuration for the input given for FTP put and append operations


A record for providing Keystore related configurations


Configuration for FTP listener endpoint.


A record for providing PrivateKey related configurations


Provides configurations for facilitating secure communication with a remote FTP server


A record for providing Truststore related configurations


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




Underlying communication happens using FTP


Underlying communication happens using FTPS


Underlying communication happens using SFTP




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




Defines the common error type for the module