Introduction

This page shows how to do simple uploads and downloads over different standard protocols.

Following are examples for all supported protocols


Provide parameters specific for some protocol

Each protocol sometimes needs more configuration options besides the regular host, port and user credentials.

For such cases the FileTransferClient provides the addCustomProperty method which accepts a key and value.

The key always starts with the name of the protocol - for example FTPS_CONNNECTION_TYPE. The possible values start with the name of the key - for example FTPS_CONNNECTION_TYPE__IMPLICIT, FTPS_CONNNECTION_TYPE__AUTH_SSL and FTPS_CONNNECTION_TYPE__AUTH_TLS. Using this key you can change the connection type.


Connect using multi-factor authentication (by username-password and private-public key)

All of the available secure connection (HTTPS, FTPS, SFTP) can be created via multi-factor authentication (by providing private-public key pair, along with username and password)

The key pair can be obtained from either JKS (.jks) or PKCS12 (.p12) key stores.

The method for providing key store is setKeystore and the methods providing trust store/certificate are setTruststore and setTrustServerSSLCertificate.

Specifying key store and or trusted certificates are not allowed for FTP and HTTP connections, since they are not secured and any call to such methods will result in an exception.



Provide trust store or trusted server certificate

Optionally, the client can set trust server certificate/s, which will validate if the remote host is trusted or not.

The trust store can be obtained from either JKS (.jks) or PKCS12 (.p12) key stores, while the trust certificate can be obtained from a PEM (.pem) file.


If you specify trust store and than trust certificate, only the trust certificate will be used for validation and if the order is reversed, then the trust store will be used.

FTP/FTPS client


import com.axway.ats.action.filetransfer.FileTransferClient;

// Instantiate the File Transfer client by providing the protocol to use
FileTransferClient transferClient = new FileTransferClient( TransferProtocol.FTPS );
// set a custom port(if not using the default one)
transferClient.setPort( 121 );

// the next method can be used to set some custom properties, for example to set the FTP connection type
transferClient.addCustomProperty( FileTransferClient.FTPS_CONNNECTION_TYPE, FileTransferClient.FTPS_CONNNECTION_TYPE__IMPLICIT);


// set key-pair (e.g. enable multi-factor authentication)
// note that the last argument is required only when working with SFTP connections
transferClient.setKeystore( KEY_STORE_LOCATION, KEY_STORE_PASSWORD, KEY_ALIAS );


// specify trusted server certificates (this step is optional)
// provide trust store
transferClient.setTruststore( TRUST_STORE_LOCATION, TRUST_STORE_PASSWORD );
// or provide PEM certificate
transferClient.setTrustedServerSSLCertificate( TRUSTED_SERVER_CERTIFICATE );
 
// connect using appropriate parameters
transferClient.connect( SERVER_IP, USER_NAME, USER_PASSWORD );
 
// upload a local file to the remote root folder of our user
transferClient.uploadFile( LOCAL_FILE_LOCATION + FILE_NAME, "/" );
 
// disconnect the File Transfer client
transferClient.disconnect();

In order to use FTP you need to provide TransferProtocol.FTP argument in the FileTransferClient constructor

Here is the list of options specific for this protocol only:

custom properties for FTPS

accepted value

default value

FTPS_CONNNECTION_TYPE

FTPS_CONNNECTION_TYPE__IMPLICIT
FTPS_CONNNECTION_TYPE__AUTH_SSL
FTPS_CONNNECTION_TYPE__AUTH_TLS

FTPS_CONNNECTION_TYPE__IMPLICIT

FTPS_ENCRYPTION_PROTOCOLS

SSL, TLSv1.2

TLSv1.2


Running any FTP command

This is rarely used, but it is possible to run any FTP/FTPS command with code like the following

// execute some FTP command
ftpClient.executeCommand( "mdir some_remote_directory" );

// execute some FTP command ...
String commandReturnCode = ftpClient.executeCommand( "mdir some_remote_directory" );
// and analyze the return code as needed

Of course you still need to take care of connecting and disconnecting as the other examples show.

It is important to know that the list of supported commands is specific to the remote FTP server


HTTP/HTTPS client

FileTransferClient httpClient = new FileTransferClient( TransferProtocol.HTTP );

// example how to set custom property supported for HTTP or HTTPS transfers
httpClient.addCustomProperty( FileTransferClient.HTTP_HTTPS_UPLOAD_CONTENT_TYPE, "text/plain");
httpClient.addCustomProperty( FileTransferClient.HTTP_HTTPS_SOCKET_READ_TIMEOUT, "10000");


// set key-pair (e.g. enable multi-factor authentication)
// note that the last argument is required only when working with SFTP connections
httpClient.setKeystore( KEY_STORE_LOCATION, KEY_STORE_PASSWORD, KEY_ALIAS );

// specify trusted server certificates (this step is optional)
// provide trust store
httpClient.setTruststore( TRUST_STORE_LOCATION, TRUST_STORE_PASSWORD );
// or provide PEM certificate
httpClient.setTrustedServerSSLCertificate( TRUSTED_SERVER_CERTIFICATE );

// do something real
httpClient.connect( SERVER_IP, USER_NAME, USER_PASSWORD );

// upload a local file to the remote root folder of our user
httpClient.uploadFile( LOCAL_FILE_LOCATION + FILE_NAME, "/" );

httpClient.disconnect();

In order to use FTP you need to provide TransferProtocol.FTP argument in the FileTransferClient constructor


Here is the list of options specific for this protocol only:

custom properties for HTTP/HTTPS

accepted value

default value

description

HTTP_HTTPS_SOCKET_BUFFER_SIZE

number of bytes

8196

HTTP_HTTPS_UPLOAD_METHOD

HTTP_HTTPS_UPLOAD_METHOD__PUT
HTTP_HTTPS_UPLOAD_METHOD__POST

HTTP_HTTPS_UPLOAD_METHOD__
PUT

HTTP_HTTPS_
PREEMPTIVE_BASIC_AUTHENTICATION

HTTP_HTTPS_
PREEMPTIVE_BASIC_AUTHENTICATION__
TRUE

not used by default

By default when username and user password are provided for HTTP Basic Authentication, these credentials are not sent with the first request. The server replies back requesting the credentials and then they are given to the server in order to authenticate. This custom property is used in case when the authentication must happen with the very first request.

HTTP_HTTPS_UPLOAD_CONTENT_TYPE

Any valid value for the content type header

application/octet-stream

HTTP_HTTPS_SOCKET_READ_TIMEOUT

Number of milliseconds for socket read timeout

0 (wait indefinitely)

Specify socket read timeout. This is the maximum time the client waits to read new data from server.
HTTP_HTTPS_TRANSFER_ENCODING_MODE HTTP_HTTPS_TRANSFER_ENCODING_MODE__CHUNKED chunked request mode not used by default Specify whether the file upload will be performed in chunks (Transfer-Encoding: chunked) or in one part.
Currently chunk size is hardcoded in underlying library to 4096 bytes and could not be changed.

SFTP client

FileTransferClient sftpClient = new FileTransferClient( TransferProtocol.SFTP );

// set key-pair (e.g. enable multi-factor authentication)
// note that the last argument is required only when working with SFTP connections
sftpClient.setKeystore( KEY_STORE_LOCATION, KEY_STORE_PASSWORD, KEY_ALIAS );
// specify trusted server certificates (this step is optional)
// provide trust store
sftpClient.setTruststore( TRUST_STORE_LOCATION, TRUST_STORE_PASSWORD );
// or provide PEM certificate 
sftpClient.setTrustedServerSSLCertificate( TRUSTED_SERVER_CERTIFICATE );

// do something real
sftpClient.connect( SERVER_IP, USER_NAME, USER_PASSWORD );

// upload a local file to the remote root folder of our user
sftpClient.uploadFile( LOCAL_FILE_LOCATION + FILE_NAME, "/" );

sftpClient.disconnect();

Here is the list of options specific for this protocol only:

custom properties for SFTP accepted value default value description
SFTP_USERNAME some user name

Username when authenticating over SFTP.

If not specified, the public key alias name is used instead of a user name
SFTP_CIPHERS

One or many(as array) constants of

com.axway.ats.common.filetransfer.SshCipher

For example AES128_CBC, BLOWFISH_CBC etc.
A cipher suite - this could be com.axway.ats.common.filetransfer.SshCipher instance or array of such instances.


Back to parent page

Go to Table of Contents