com.enterprisedt.net.ftp

Class SecureFileTransferClient

java.lang.Object

com.enterprisedt.net.ftp.SecureFileTransferClient

All Implemented Interfaces:

FileTransferClientInterface

Direct Known Subclasses:

AsyncFileTransferClient

public class SecureFileTransferClient
extends java.lang.Object
implements FileTransferClientInterface

File transfer client class that supports multiple protocols and permits concurrent FTP operations. A configurable connection pool provides the ability to perform multiple transfers simultaneously from different threads.

Multiple protocols are supported, including 'plain' FTP, SFTP (FTP over SSH), and FTPS (FTP over SSL - both implicit and explicit modes). The protocol can be changed with a single method call.

A simple example is shown below:

 SecureFileTransferClient client = new SecureFileTransferClient();
 client.setRemoteHost(host);
 client.setUserName(user);
 client.setPassword(password);
 client.setProtocol(Protocol.FTP); // FTP is the default
 
 // connect
 client.connect();
 
 // perform a transfer, uploading the local file as 'remote.txt'
 client.uploadFile("local.txt", "remote.txt");
 
 // disconnect from server
 client.disconnect();
 

Users should note that calling connect() starts a pool of worker threads and the connection pool. This means that disconnect() must be called to stop the worker threads, otherwise applications will hang on exit as threads will still be alive.

Version:

$Revision: 1.25 $

Author:

Bruce Blackshaw

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.HashMap	activeTransferTasks Active transfer tasks, hashed on id
protected AdvancedFTPSettings	advancedFTPSettings Advanced configuration parameters that often aren't used
protected AdvancedGeneralSettings	advancedSettings
protected AdvancedSSHSettings	advancedSSHSettings
protected AdvancedSSLSettings	advancedSSLSettings
protected com.enterprisedt.net.ftp.async.internal.AsyncFileTransferClientImpl	asyncImpl
protected EventListener	eventListener Notifies of various events
protected com.enterprisedt.net.ftp.async.internal.SecureConnectionContext	masterContext Connection context
protected MultipleTransferSettings	multiSettings
protected ProxySettings	proxySettings

Constructor Summary

Constructors

Constructor and Description
SecureFileTransferClient() Constructor.
SecureFileTransferClient(int initialPoolSize, int maxPoolSize) Constructor.

Method Summary

Modifier and Type	Method and Description
void	addErrorListener(ErrorListener listener) Add an error listener to the list of listeners
void	cancelAllTransfers() Cancel all transfers that are either pending or currently under way
void	changeDirectory(java.lang.String directoryName) Change directory on the FTP server.
boolean	changeIntoPathDirectory() If true (the default), when paths are supplied as part of filenames, the directory is changed into before transferring the file,e.g.
void	changeToParentDirectory() Change to parent directory on the FTP server.
protected void	checkConnection(boolean shouldBeConnected) Checks if the client has connected to the server and throws an exception if it hasn't.
void	connect() Make a connection to the FTP server.
void	createDirectory(java.lang.String directoryName) Create directory on the FTP server.
void	deleteDirectory(java.lang.String directoryName) Delete a directory on the FTP server.
void	deleteDirectory(java.lang.String directoryName, boolean recursive) Delete a directory on the FTP server, and optionally sub-directories.
void	deleteFile(java.lang.String remoteFileName) Deletes a remote file.
void	deleteMultipleFiles(java.io.FileFilter filter) Deletes remote files in the current directory that match the supplied filename filter
void	deleteMultipleFiles(java.lang.String wildcard) Deletes remote files in the current directory that match the supplied wildcard
void	deleteMultipleFiles(java.lang.String remoteDirectory, java.io.FileFilter filter, boolean recursive) Deletes remote files in the current directory.
void	deleteMultipleFiles(java.lang.String remoteDirectory, java.lang.String wildcard, boolean recursive) Deletes remote files in the current directory.
FTPFile[]	directoryList() List the current directory on the FTP server.
FTPFile[]	directoryList(java.lang.String directoryName) List a directory on the FTP server.
void	directoryList(java.lang.String directoryName, DirectoryListCallback lister) List a directory on the FTP server, calling the user-supplied callback for each entry.
java.lang.String[]	directoryNameList() List the names of files and directories in the current directory on the FTP server.
java.lang.String[]	directoryNameList(java.lang.String directoryName, boolean isLongListing) List a directory on the FTP server.
void	disconnect() Disconnect from the FTP server.
void	disconnect(boolean immediate) Disconnect from the FTP server immediately.
byte[]	downloadByteArray(java.lang.String remoteFileName) Download a file from the FTP server into a byte array.
void	downloadFile(java.lang.String localFileName, java.lang.String remoteFileName) Download a file from the FTP server .
void	downloadFile(java.lang.String localFileName, java.lang.String remoteFileName, WriteMode writeMode) Download a file from the FTP server .
void	downloadMultiple(java.lang.String localDir, java.io.FileFilter filter) Downloads remote files to the supplied local directory that match the supplied wildcard from the current remote directory.
void	downloadMultiple(java.lang.String localDir, java.lang.String wildcard) Downloads remote files to the supplied local directory that match the supplied wildcard from the current remote directory.
void	downloadMultiple(java.lang.String localDir, java.lang.String remoteDir, java.io.FileFilter filter, boolean recursive) Downloads remote files to the supplied local directory that match the supplied FileFilter from the current remote directory.
void	downloadMultiple(java.lang.String localDir, java.lang.String remoteDir, java.lang.String wildcard, boolean recursive) Downloads remote files to the supplied local directory that match the supplied wildcard from the current remote directory.
FileTransferInputStream	downloadStream(java.lang.String remoteFileName) Download a file from the FTP server as a stream.
static void	downloadURLFile(java.lang.String localFileName, java.lang.String ftpURL) Downloads the given file to the given FTP URL.
static FileTransferInputStream	downloadURLStream(java.lang.String ftpURL) Open an InputStream for the given FTP URL.
java.lang.String	executeCommand(java.lang.String command) Request that the remote server execute the literal command supplied.
boolean	exists(java.lang.String remoteFileName) Determine if a remote file exists.
boolean	existsDirectory(java.lang.String remoteDir) Determine if a remote directory exists.
void	finalize() Finalize this instance by shutting down its threads
AdvancedFTPSettings	getAdvancedFTPSettings() Get the advanced FTP configuration parameters object
AdvancedGeneralSettings	getAdvancedSettings() Get the advanced general configuration parameters object, for none protocol specific parameters
AdvancedSSHSettings	getAdvancedSSHSettings() Get the advanced SSH configuration parameters object
AdvancedSSLSettings	getAdvancedSSLSettings() Get the advanced SSL configuration parameters object
FTPTransferType	getContentType() Get the current content type for all connections.
java.lang.String	getInitialRemoteDirectory() Returns the initial remote directory that all connections change to immediately on connection.
FTPReply	getLastReply() Gets the last FTP reply from the server, whether valid or not.
int	getMaxTransferRate() Get the maximum bandwidth for transfers
java.util.Date	getModifiedTime(java.lang.String remoteFileName) Get the modified-time of a remote file.
MultipleTransferSettings	getMultipleTransferSettings() Get the configuration object that controls the settings used for multiple transfers
int	getNetworkBufferSize() Get the size of the network buffers (SO_SNDBUF and SO_RCVBUF).
java.lang.String	getPassword() Get the current user password.
Protocol	getProtocol() Get the current protocol being used
ProxySettings	getProxySettings() Get the proxy settings instance.
java.lang.String	getRemoteDirectory() Get the current remote directory of the master context.
java.lang.String	getRemoteHost() Returns the IP address or name of the remote host.
int	getRemotePort() Returns the port being connected to on the remote server.
long	getSize(java.lang.String remoteFileName) Get the size of a remote file.
FileStatistics	getStatistics() Get statistics on file transfers and deletions.
java.lang.String	getSystemType() Get a string that represents the remote system that the client is logged into.
int	getTimeout() Returns the timeout for socket connections.
java.lang.String	getUserName() Get the current user name.
boolean	isCompressionPreferred() Is compression enabled?
boolean	isConnected() Is this client currently connected to the server?
boolean	isDetectContentType() Get the detect content type flag
boolean	isKeepAliveEnabled() Is the connection pool's keep alive thread enabled, i.e.
boolean	isServerValidationEnabled() Is server validation switched on, i.e.
boolean	isTransferIntegrityCheck() Is integrity checking of transfers enabled?
void	loadSSHServerValidation(java.lang.String knownHosts) Load the public keys that the server public key will be validated against.
void	loadSSLServerValidation(java.lang.String rootCertificatesPath) Load the root certificates that the server certificate will be validated against.
void	rename(java.lang.String renameFromName, java.lang.String renameToName) Rename a remote file or directory.
void	setChangeIntoPathDirectory(boolean changeIntoPathDirectory) Determine if when a path is supplied as part of a filename, whether the directory is changed into before transferring the file, e.g.
void	setCompressionPreferred(boolean enabled) Set compression flag on or off.
void	setContentType(FTPTransferType type) Set the transfer type for all connections, either ASCII or binary.
void	setDetectContentType(boolean detectContentType) Set auto detect of filetypes on or off.
void	setEventListener(EventListener listener) Set the event listener for transfer event notification
void	setInitialRemoteDirectory(java.lang.String directory) Set the initial remote directory that all connections change to immediately on connection.
void	setKeepAliveEnabled(boolean enabled) Change the connection pool keep alive setting, switching it on or off.
void	setMaxTransferRate(int thresholdBytesPerSecond) Set the maximum transfer rates in bytes per sec
void	setModifiedTime(java.lang.String remoteFileName, java.util.Date modifiedTime) Set the modified-time of a remote file.
void	setNetworkBufferSize(int networkBufferSize) Set the size of the network buffers (SO_SNDBUF and SO_RCVBUF).
void	setPassword(java.lang.String password) Set the password of the user to log in with.
void	setPermissions(java.lang.String remotePath, int permissions) Set the permissions of the supplied file or directory.
void	setProtocol(Protocol protocol) Set the current protocol to be used.
void	setRemoteHost(java.lang.String remoteHost) Set the IP address or name of the remote host This may only be done if the client is not already connected to the server.
void	setRemotePort(int remotePort) Set the port to connect to on the remote server.
void	setServerValidationEnabled(boolean enabled) Change the server validation setting, switching it on or off.
void	setTimeout(int timeout) Set the timeout for socket connections.
void	setTransferIntegrityCheck(boolean enabled) Enable or disable integrity checks on transfers.
void	setUserName(java.lang.String userName) Set the name of the user to log in with.
protected void	shutdown(boolean immediate) Shutdown all the worker threads in the task processor.
java.lang.String	uploadByteArray(byte[] bytes, java.lang.String remoteFileName, WriteMode writeMode) Upload a byte array to the FTP server.
java.lang.String	uploadFile(java.lang.String localFileName, java.lang.String remoteFileName) Upload a file to the FTP server.
java.lang.String	uploadFile(java.lang.String localFileName, java.lang.String remoteFileName, WriteMode writeMode) Upload a file to the FTP server.
void	uploadMultiple(java.lang.String localDir, java.io.FileFilter filter) Uploads local files from the supplied local directory that match the supplied FileFilter into the current remote directory.
void	uploadMultiple(java.lang.String localDir, java.lang.String wildcard) Uploads local files from the supplied local directory that match the supplied wildcard into the current remote directory.
void	uploadMultiple(java.lang.String localDir, java.lang.String remoteDir, java.io.FileFilter filter, boolean recursive) Uploads local files from the supplied local directory that match the supplied wildcard into the supplied remote directory.
void	uploadMultiple(java.lang.String localDir, java.lang.String remoteDir, java.lang.String wildcard, boolean recursive) Uploads local files from the supplied local directory that match the supplied wildcard into the supplied remote directory.
FileTransferOutputStream	uploadStream(java.lang.String remoteFileName) Upload a file to the FTP server by writing to a stream.
FileTransferOutputStream	uploadStream(java.lang.String remoteFileName, WriteMode writeMode) Upload a file to the FTP server by writing to a stream.
static void	uploadURLFile(java.lang.String localFileName, java.lang.String ftpURL) Uploads the given file to the given FTP URL.
static FileTransferOutputStream	uploadURLStream(java.lang.String ftpURL) Open an OutputStream for the given FTP URL.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

asyncImpl

protected com.enterprisedt.net.ftp.async.internal.AsyncFileTransferClientImpl asyncImpl

masterContext

protected com.enterprisedt.net.ftp.async.internal.SecureConnectionContext masterContext

Connection context

activeTransferTasks

protected java.util.HashMap activeTransferTasks

Active transfer tasks, hashed on id

eventListener

protected EventListener eventListener

Notifies of various events

multiSettings

protected MultipleTransferSettings multiSettings

proxySettings

protected ProxySettings proxySettings

advancedFTPSettings

protected AdvancedFTPSettings advancedFTPSettings

Advanced configuration parameters that often aren't used

advancedSettings

protected AdvancedGeneralSettings advancedSettings

advancedSSLSettings

protected AdvancedSSLSettings advancedSSLSettings

advancedSSHSettings

protected AdvancedSSHSettings advancedSSHSettings

Constructor Detail

SecureFileTransferClient

public SecureFileTransferClient(int initialPoolSize,
                                int maxPoolSize)

Constructor. Initialises the class.

Parameters:

initialPoolSize - initial size of connection pool (i.e. number of managed connections).

maxPoolSize - maximum size of pool.

SecureFileTransferClient

public SecureFileTransferClient()

Constructor. Initialises the class. Uses a default initial and maximum pool size.

Method Detail

checkConnection

protected void checkConnection(boolean shouldBeConnected)
                        throws FTPException

Checks if the client has connected to the server and throws an exception if it hasn't. This is only intended to be used by subclasses

Throws:

FTPException - Thrown if the client has not connected to the server.

getRemoteHost

public java.lang.String getRemoteHost()

Returns the IP address or name of the remote host.

Specified by:

getRemoteHost in interface FileTransferClientInterface

Returns:

Returns the remote host.

setRemoteHost

public void setRemoteHost(java.lang.String remoteHost)
                   throws FTPException

Set the IP address or name of the remote host This may only be done if the client is not already connected to the server.

Specified by:

setRemoteHost in interface FileTransferClientInterface

Parameters:

remoteHost - The IP address or name of the remote host

Throws:

FTPException - Thrown if the client is already connected to the server.

getProtocol

public Protocol getProtocol()

Get the current protocol being used

Returns:

Protocol

setProtocol

public void setProtocol(Protocol protocol)
                 throws FTPException

Set the current protocol to be used. Cannot be connected. The port number is automatically reset to the default for the new protocol, and so setRemotePort should be called after this method if a different port is required.

Parameters:

protocol - protocol to use

Throws:

FTPException

getProxySettings

public ProxySettings getProxySettings()

Get the proxy settings instance. Its properties can be set to use proxies.

Returns:

ProxySettings

getTimeout

public int getTimeout()

Returns the timeout for socket connections.

Specified by:

getTimeout in interface FileTransferClientInterface

Returns:

Returns the connection timeout in milliseconds

setTimeout

public void setTimeout(int timeout)
                throws FTPException

Set the timeout for socket connections. Can only do this if not already connected.

Specified by:

setTimeout in interface FileTransferClientInterface

Parameters:

timeout - the timeout to use in milliseconds

Throws:

FTPException - Thrown if the client is already connected to the server.

getNetworkBufferSize

public int getNetworkBufferSize()

Get the size of the network buffers (SO_SNDBUF and SO_RCVBUF).

Specified by:

getNetworkBufferSize in interface FileTransferClientInterface

Returns:

network buffer size

setNetworkBufferSize

public void setNetworkBufferSize(int networkBufferSize)
                          throws FTPException

Set the size of the network buffers (SO_SNDBUF and SO_RCVBUF).

Specified by:

setNetworkBufferSize in interface FileTransferClientInterface

Parameters:

networkBufferSize - new buffer size to set

Throws:

FTPException

getRemotePort

public int getRemotePort()

Returns the port being connected to on the remote server.

Specified by:

getRemotePort in interface FileTransferClientInterface

Returns:

Returns the port being connected to on the remote server.

setRemotePort

public void setRemotePort(int remotePort)
                   throws FTPException

Set the port to connect to on the remote server. Can only do this if not already connected. This should be done after setting the protocol, as setting the protocol sets the port to the default value for that protocol.

Specified by:

setRemotePort in interface FileTransferClientInterface

Parameters:

remotePort - The port to use.

Throws:

FTPException - Thrown if the client is already connected to the server.

setContentType

public void setContentType(FTPTransferType type)
                    throws java.io.IOException,
                           FTPException

Set the transfer type for all connections, either ASCII or binary. Setting applies to all subsequent transfers that are initiated. It does not apply to transfers currently in progress.

Specified by:

setContentType in interface FileTransferClientInterface

Parameters:

type - transfer type

Throws:

java.io.IOException

FTPException

getContentType

public FTPTransferType getContentType()

Get the current content type for all connections.

Specified by:

getContentType in interface FileTransferClientInterface

Returns:

transfer type

setDetectContentType

public void setDetectContentType(boolean detectContentType)

Set auto detect of filetypes on or off. If on, the transfer mode is switched from ASCII to binary and vice versa depending on the extension of the file. After the transfer, the mode is always returned to what it was before the transfer was performed. The default is off. If the filetype is unknown, the transfer mode is unchanged

Specified by:

setDetectContentType in interface FileTransferClientInterface

Parameters:

detectContentType - true if detecting content type, false if not

isDetectContentType

public boolean isDetectContentType()

Get the detect content type flag

Specified by:

isDetectContentType in interface FileTransferClientInterface

Returns:

true if we are detecting binary and ASCII transfers from the file type

setUserName

public void setUserName(java.lang.String userName)
                 throws FTPException

Set the name of the user to log in with. Can only do this if not already connected.

Specified by:

setUserName in interface FileTransferClientInterface

Parameters:

userName - user-name to log in with.

Throws:

FTPException

getPassword

public java.lang.String getPassword()

Get the current user password.

Specified by:

getPassword in interface FileTransferClientInterface

Returns:

current user password

setPassword

public void setPassword(java.lang.String password)
                 throws FTPException

Set the password of the user to log in with. Can only do this if not already connected.

Specified by:

setPassword in interface FileTransferClientInterface

Parameters:

password - password to log in with.

Throws:

FTPException

getUserName

public java.lang.String getUserName()

Get the current user name.

Specified by:

getUserName in interface FileTransferClientInterface

Returns:

current user name

setMaxTransferRate

public void setMaxTransferRate(int thresholdBytesPerSecond)

Set the maximum transfer rates in bytes per sec

Parameters:

thresholdBytesPerSecond - maximum bytes per second to transfer

getMaxTransferRate

public int getMaxTransferRate()

Get the maximum bandwidth for transfers

Returns:

threshold bytes per second, or -1 if no threshold

isTransferIntegrityCheck

public boolean isTransferIntegrityCheck()

Is integrity checking of transfers enabled?

Returns:

true if enabled, false otherwise

setTransferIntegrityCheck

public void setTransferIntegrityCheck(boolean enabled)

Enable or disable integrity checks on transfers. This is currently not supported for SFTP, only for FTP and FTPS. It also relies on the XCRC command being supported in the FTP server that is being connected to. An exception will be thrown for the transfer if integrity checking is found to be unsupported in FTP/FTPS, or if the integrity check fails.

Parameters:

enabled - true if enabled, false otherwise

isCompressionPreferred

public boolean isCompressionPreferred()

Is compression enabled?

Returns:

true if enabled, false if not

setCompressionPreferred

public void setCompressionPreferred(boolean enabled)

Set compression flag on or off. For FTP/FTPS this will enable MODE Z compression, and for SFTP it will enable zlib compression. In either case the server must be able to support compression for it to be used. It will silently fail if this is not the case, i.e. the data will not be compressed. Use the log files to confirm that compression is being used. Note that once enabled, the connection must be closed and re-opened to disable compression.

Parameters:

enabled - true to enable, false to disable.

getAdvancedFTPSettings

public AdvancedFTPSettings getAdvancedFTPSettings()

Get the advanced FTP configuration parameters object

Specified by:

getAdvancedFTPSettings in interface FileTransferClientInterface

Returns:

advanced parameters

getAdvancedSettings

public AdvancedGeneralSettings getAdvancedSettings()

Get the advanced general configuration parameters object, for none protocol specific parameters

Specified by:

getAdvancedSettings in interface FileTransferClientInterface

Returns:

advanced parameters

getAdvancedSSLSettings

public AdvancedSSLSettings getAdvancedSSLSettings()

Get the advanced SSL configuration parameters object

Returns:

advanced parameters

getAdvancedSSHSettings

public AdvancedSSHSettings getAdvancedSSHSettings()

Get the advanced SSH configuration parameters object

Returns:

advanced parameters

getMultipleTransferSettings

public MultipleTransferSettings getMultipleTransferSettings()

Get the configuration object that controls the settings used for multiple transfers

Returns:

MultipleTransferSettings

changeIntoPathDirectory

public boolean changeIntoPathDirectory()

If true (the default), when paths are supplied as part of filenames, the directory is changed into before transferring the file,e.g. if /path/fileA.name is supplied, then commands sent to the server are CD /path followed by STORE fileA.name. If false, the supplied path is used, e.g. if /path/fileA.name is supplied, then the command sent to the server is "STOR /path/fileA.name".

Returns:

true if changing into directory, false otherwise.

setChangeIntoPathDirectory

public void setChangeIntoPathDirectory(boolean changeIntoPathDirectory)

Determine if when a path is supplied as part of a filename, whether the directory is changed into before transferring the file, e.g. if /path/fileA.name is supplied, then commands sent to the server are CD /path followed by STORE fileA.name. If false, the supplied path is used, e.g. if /path/fileA.name is supplied, then the command sent to the server is "STOR /path/fileA.name". If thousands of files are being transferred rapidly, and many CD commands are observed in the log, try switching this off.

Parameters:

changeIntoPathDirectory - set whether or not the client should change into the path supplied

isServerValidationEnabled

public boolean isServerValidationEnabled()

Is server validation switched on, i.e. is the identify of the server as presented via its certificate (SSL) or public key (SSH) verified by checking a certificate store or known hosts file? The default is disabled. In production systems server validation should always be enabled.

Returns:

true if enabled, false if not enabled.

setServerValidationEnabled

public void setServerValidationEnabled(boolean enabled)
                                throws FTPException

Change the server validation setting, switching it on or off. If server validation is on, the identify of the server as presented via its certificate (SSL) or public key (SSH) is verified by checking a certificate store or known hosts file. The default is disabled. In production systems server validation should always be enabled.

Parameters:

enabled - true to enable, false to disable

Throws:

FTPException

isKeepAliveEnabled

public boolean isKeepAliveEnabled()

Is the connection pool's keep alive thread enabled, i.e. will connections in the thread pool be regularly pinged to ensure they are maintained as live connections? Enabled by default.

Returns:

true if enabled, false if not enabled.

setKeepAliveEnabled

public void setKeepAliveEnabled(boolean enabled)
                         throws FTPException

Change the connection pool keep alive setting, switching it on or off. If the connection pool's keep alive thread is enabled, connections in the thread pool be regularly pinged to ensure they are maintained as live connections. Enabled by default.

Parameters:

enabled - true to enable, false to disable

Throws:

FTPException

loadSSLServerValidation

public void loadSSLServerValidation(java.lang.String rootCertificatesPath)
                             throws java.io.FileNotFoundException,
                                    java.io.IOException,
                                    FTPException

Load the root certificates that the server certificate will be validated against. Note that this sets server validation to enabled. This is used for the FTPS protocol.

Parameters:

rootCertificatesPath - path to root certificates

Throws:

java.io.FileNotFoundException

java.io.IOException

FTPException

loadSSHServerValidation

public void loadSSHServerValidation(java.lang.String knownHosts)
                             throws java.io.FileNotFoundException,
                                    java.io.IOException,
                                    FTPException

Load the public keys that the server public key will be validated against. They are typically stored in a file called 'known_hosts'. Note that this sets server validation to enabled. This is used for the SFTP protocol.

Parameters:

knownHosts - path to known hosts file

Throws:

java.io.FileNotFoundException

java.io.IOException

FTPException

isConnected

public boolean isConnected()

Is this client currently connected to the server?

Specified by:

isConnected in interface FileTransferClientInterface

Returns:

true if connected, false otherwise

getInitialRemoteDirectory

public java.lang.String getInitialRemoteDirectory()

Returns the initial remote directory that all connections change to immediately on connection.

Returns:

Returns the remote host.

setInitialRemoteDirectory

public void setInitialRemoteDirectory(java.lang.String directory)
                               throws FTPException

Set the initial remote directory that all connections change to immediately on connection. This may only be done if the client is not already connected to the server.

Parameters:

directory - The initial remote directory

Throws:

FTPException - Thrown if the client is already connected to the server.

getRemoteDirectory

public java.lang.String getRemoteDirectory()

Get the current remote directory of the master context. Note that individual connections may have different current directories.

Specified by:

getRemoteDirectory in interface FileTransferClientInterface

Returns:

current remote directory of master context

setEventListener

public void setEventListener(EventListener listener)

Set the event listener for transfer event notification

Specified by:

setEventListener in interface FileTransferClientInterface

Parameters:

listener - event listener reference

getStatistics

public FileStatistics getStatistics()

Get statistics on file transfers and deletions.

Specified by:

getStatistics in interface FileTransferClientInterface

Returns:

FTPStatistics

connect

public void connect()
             throws FTPException,
                    java.io.IOException

Make a connection to the FTP server. A number of connections are made - that number being equal to the size of the FTP connection pool.

Specified by:

connect in interface FileTransferClientInterface

Throws:

FTPException

java.io.IOException

executeCommand

public java.lang.String executeCommand(java.lang.String command)
                                throws FTPException,
                                       java.io.IOException

Request that the remote server execute the literal command supplied. In FTP and SFTP, this might be a SITE command, while in SFTP it might be a shell command. For example, "SITE DCB LRECL=600 RECFM=FB WRAPRECORD" might be a SITE command sent to a z/OS FTP server to set certain transfer parameters.

It is up to the user to send a sensible command.

Specified by:

executeCommand in interface FileTransferClientInterface

Parameters:

command - command string

Returns:

result string by server

Throws:

FTPException

java.io.IOException

getLastReply

public FTPReply getLastReply()

Gets the last FTP reply from the server, whether valid or not. This may be null if the protocol is SFTP, which doesn't have reply objects.

Returns:

reply object encapsulating last server response

getSystemType

public java.lang.String getSystemType()
                               throws FTPException,
                                      java.io.IOException

Get a string that represents the remote system that the client is logged into.

Specified by:

getSystemType in interface FileTransferClientInterface

Returns:

system string

Throws:

FTPException

java.io.IOException

directoryNameList

public java.lang.String[] directoryNameList()
                                     throws FTPException,
                                            java.io.IOException

List the names of files and directories in the current directory on the FTP server.

Specified by:

directoryNameList in interface FileTransferClientInterface

Returns:

String[]

Throws:

FTPException

java.io.IOException

directoryNameList

public java.lang.String[] directoryNameList(java.lang.String directoryName,
                                            boolean isLongListing)
                                     throws FTPException,
                                            java.io.IOException

List a directory on the FTP server.

Specified by:

directoryNameList in interface FileTransferClientInterface

Parameters:

directoryName - name of the directory (generally not a path)

isLongListing - true if the listing is a long format listing

Returns:

String[]

Throws:

FTPException

java.io.IOException

directoryList

public FTPFile[] directoryList()
                        throws FTPException,
                               java.io.IOException,
                               java.text.ParseException

List the current directory on the FTP server.

Specified by:

directoryList in interface FileTransferClientInterface

Throws:

java.text.ParseException

FTPException

java.io.IOException

directoryList

public void directoryList(java.lang.String directoryName,
                          DirectoryListCallback lister)
                   throws FTPException,
                          java.io.IOException

List a directory on the FTP server, calling the user-supplied callback for each entry. Listings can be interrupted while they're in progress by throwing an exception from inside the callback.

Specified by:

directoryList in interface FileTransferClientInterface

Parameters:

directoryName - name of the directory (generally not a path)

Throws:

FTPException

java.io.IOException

directoryList

public FTPFile[] directoryList(java.lang.String directoryName)
                        throws FTPException,
                               java.io.IOException

List a directory on the FTP server.

Specified by:

directoryList in interface FileTransferClientInterface

Parameters:

directoryName - name of the directory (generally not a path)

Throws:

FTPException

java.io.IOException

downloadByteArray

public byte[] downloadByteArray(java.lang.String remoteFileName)
                         throws FTPException,
                                java.io.IOException

Download a file from the FTP server into a byte array.

Specified by:

downloadByteArray in interface FileTransferClientInterface

Parameters:

remoteFileName - name of the remote file to be downloaded

Throws:

FTPException

java.io.IOException

downloadFile

public void downloadFile(java.lang.String localFileName,
                         java.lang.String remoteFileName)
                  throws FTPException,
                         java.io.IOException

Download a file from the FTP server .

Specified by:

downloadFile in interface FileTransferClientInterface

Parameters:

localFileName - name (or full path) of the local file to be downloaded to

remoteFileName - name of the remote file to be downloaded

Throws:

FTPException

java.io.IOException

downloadFile

public void downloadFile(java.lang.String localFileName,
                         java.lang.String remoteFileName,
                         WriteMode writeMode)
                  throws FTPException,
                         java.io.IOException

Download a file from the FTP server .

Specified by:

downloadFile in interface FileTransferClientInterface

Parameters:

localFileName - name (or full path) of the local file to be downloaded to

remoteFileName - name of the remote file to be downloaded

writeMode - mode in which the file is written to the client machine

Throws:

FTPException

java.io.IOException

downloadStream

public FileTransferInputStream downloadStream(java.lang.String remoteFileName)
                                       throws FTPException,
                                              java.io.IOException

Download a file from the FTP server as a stream. The close() method *must* be called on the stream once the stream has been read.

Specified by:

downloadStream in interface FileTransferClientInterface

Parameters:

remoteFileName - name of the remote file to be downloaded

Returns:

InputStream

Throws:

FTPException

java.io.IOException

downloadURLStream

public static FileTransferInputStream downloadURLStream(java.lang.String ftpURL)
                                                 throws java.net.MalformedURLException,
                                                        java.io.IOException,
                                                        FTPException

Open an InputStream for the given FTP URL. The URL must be of the form (protocol)://[user[:password]@]host[:port]/path. The value of 'protocol' may be ftp for plain FTP; sftp for SFTP; ftps, ftpes or ftpse for explicit FTPS; or ftpis or ftpsi for implicit FTPS. The stream should be closed when the transfer is complete.

Parameters:

ftpURL - The URL must be of the form (protocol)://[user[:password]@]host[:port]/path.

Returns:

FileTransferInputStream for the given URL. The stream should be closed when the transfer is complete.

Throws:

java.net.MalformedURLException - Thrown when an invalid URL is provided.

java.io.IOException - Thrown when an I/O-related error occurs.

FTPException - Thrown when an FTP-protocol-related error occurs.

downloadURLFile

public static void downloadURLFile(java.lang.String localFileName,
                                   java.lang.String ftpURL)
                            throws java.net.MalformedURLException,
                                   java.io.IOException,
                                   FTPException

Downloads the given file to the given FTP URL. The URL must be of the form (protocol)://[user[:password]@]host[:port]/path. The value of 'protocol' may be ftp for plain FTP; sftp for SFTP; ftps, ftpes or ftpse for explicit FTPS; or ftpis or ftpsi for implicit FTPS.

Parameters:

localFileName - Path to local file

ftpURL - The URL must be of the form (protocol)://[user[:password]@]host[:port]/path.

Throws:

java.net.MalformedURLException - Thrown when an invalid URL is provided.

java.io.IOException - Thrown when an I/O-related error occurs.

FTPException - Thrown when an FTP-protocol-related error occurs.

uploadFile

public java.lang.String uploadFile(java.lang.String localFileName,
                                   java.lang.String remoteFileName)
                            throws FTPException,
                                   java.io.IOException

Upload a file to the FTP server. If a null is supplied as the remoteFileName, the STOU (store unique) FTP feature will be used (if available) and the FTP server will generate a unique name for the file.

Specified by:

uploadFile in interface FileTransferClientInterface

Parameters:

localFileName - name (or full path) of the local file to be downloaded to

remoteFileName - name of the remote file to be downloaded (or null to generate a unique name)

append - true if in append mode

Returns:

name of remote file

Throws:

FTPException

java.io.IOException

uploadFile

public java.lang.String uploadFile(java.lang.String localFileName,
                                   java.lang.String remoteFileName,
                                   WriteMode writeMode)
                            throws FTPException,
                                   java.io.IOException

Upload a file to the FTP server. If a null is supplied as the remoteFileName, the STOU (store unique) FTP feature will be used (if available) and the FTP server will generate a unique name for the file.

Specified by:

uploadFile in interface FileTransferClientInterface

Parameters:

localFileName - name (or full path) of the local file to be downloaded to

remoteFileName - name of the remote file to be downloaded (or null to generate a unique name)

writeMode - mode to write to the remote file with

Returns:

name of remote file

Throws:

FTPException

java.io.IOException

uploadByteArray

public java.lang.String uploadByteArray(byte[] bytes,
                                        java.lang.String remoteFileName,
                                        WriteMode writeMode)
                                 throws FTPException,
                                        java.io.IOException

Upload a byte array to the FTP server. If a null is supplied as the remoteFileName, the STOU (store unique) FTP feature will be used (if available) and the FTP server will generate a unique name for the file.

Parameters:

bytes - byte array to upload

remoteFileName - name of the remote file

writeMode - mode in which the file is written to the server

callback - callback to be notified when upload is completed

tag - any object reference can be saved in this tag and can be accessed later from the result object (e.g. in the callback).

Returns:

name of remote file

Throws:

FTPException

java.io.IOException

uploadStream

public FileTransferOutputStream uploadStream(java.lang.String remoteFileName)
                                      throws FTPException

Upload a file to the FTP server by writing to a stream. The close() method *must* be called on the stream once the stream has been read. If a null is supplied as the remoteFileName, the STOU (store unique) FTP feature will be used (if available) and the FTP server will generate a unique name for the file. This name can be obtained afterwards from FileTransferOutputStream#getRemoteFileName()

Specified by:

uploadStream in interface FileTransferClientInterface

Parameters:

remoteFileName - name of the remote file to be uploaded

Returns:

FTPOutputStream

Throws:

FTPException

uploadStream

public FileTransferOutputStream uploadStream(java.lang.String remoteFileName,
                                             WriteMode writeMode)
                                      throws FTPException

Upload a file to the FTP server by writing to a stream. The close() method *must* be called on the stream once the stream has been read. If a null is supplied as the remoteFileName, the STOU (store unique) FTP feature will be used (if available) and the FTP server will generate a unique name for the file. This name can be obtained afterwards from FileTransferOutputStream#getRemoteFileName()

Specified by:

uploadStream in interface FileTransferClientInterface

Parameters:

remoteFileName - name of the remote file to be uploaded

writeMode - mode in which the file is written to the server

Returns:

FileTransferOutputStream

Throws:

FTPException

uploadURLStream

public static FileTransferOutputStream uploadURLStream(java.lang.String ftpURL)
                                                throws java.net.MalformedURLException,
                                                       java.io.IOException,
                                                       FTPException

Open an OutputStream for the given FTP URL. The URL must be of the form (protocol)://[user[:password]@]host[:port]/path. The value of 'protocol' may be ftp for plain FTP; sftp for SFTP; ftps, ftpes or ftpse for explicit FTPS; or ftpis or ftpsi for implicit FTPS. The stream must be closed when the transfer is complete.

Parameters:

ftpURL - The URL must be of the form (protocol)://[user[:password]@]host[:port]/path.

Returns:

FileTransferInputStream for the given URL. The stream should be closed when the transfer is complete.

Throws:

java.net.MalformedURLException - Thrown when an invalid URL is provided.

java.io.IOException - Thrown when an I/O-related error occurs.

FTPException - Thrown when an FTP-protocol-related error occurs.

uploadURLFile

public static void uploadURLFile(java.lang.String localFileName,
                                 java.lang.String ftpURL)
                          throws java.net.MalformedURLException,
                                 java.io.IOException,
                                 FTPException

Uploads the given file to the given FTP URL. The URL must be of the form (protocol)://[user[:password]@]host[:port]/path. The value of 'protocol' may be ftp for plain FTP; sftp for SFTP; ftps, ftpes or ftpse for explicit FTPS; or ftpis or ftpsi for implicit FTPS.

Parameters:

localFileName - Path to local file

ftpURL - The URL must be of the form (protocol)://[user[:password]@]host[:port]/path.

Throws:

java.net.MalformedURLException - Thrown when an invalid URL is provided.

java.io.IOException - Thrown when an I/O-related error occurs.

FTPException - Thrown when an FTP-protocol-related error occurs.

getSize

public long getSize(java.lang.String remoteFileName)
             throws FTPException,
                    java.io.IOException

Get the size of a remote file.

Specified by:

getSize in interface FileTransferClientInterface

Parameters:

remoteFileName - name of remote file

Returns:

long

Throws:

FTPException

java.io.IOException

getModifiedTime

public java.util.Date getModifiedTime(java.lang.String remoteFileName)
                               throws FTPException,
                                      java.io.IOException

Get the modified-time of a remote file.

Specified by:

getModifiedTime in interface FileTransferClientInterface

Parameters:

remoteFileName - name of remote file

Returns:

Date

Throws:

FTPException

java.io.IOException

setModifiedTime

public void setModifiedTime(java.lang.String remoteFileName,
                            java.util.Date modifiedTime)
                     throws FTPException,
                            java.io.IOException

Set the modified-time of a remote file. May not be supported by all servers.

Specified by:

setModifiedTime in interface FileTransferClientInterface

Parameters:

remoteFileName - name of remote file

modifiedTime - new modified time

Throws:

FTPException

java.io.IOException

setPermissions

public void setPermissions(java.lang.String remotePath,
                           int permissions)
                    throws FTPException,
                           java.io.IOException

Set the permissions of the supplied file or directory. Only supported in SFTP.

Absolute modes are octal numbers specifying the complete list of attributes for the files; you specify attributes by OR'ing together these bits. These must be octal numbers, and are listed below.

 0400       Individual read
 0200       Individual write
 0100       Individual execute (or list directory)
 0040       Group read
 0020       Group write
 0010       Group execute
 0004       Other read
 0002       Other write
 0001       Other execute 
 

For example, for individual read, write and execute only, 0700 should be supplied (0400 | 0200 | 0100).

Parameters:

remotePath - path of file or directory

permissions - octal permissions (must be preceded with a '0').

Throws:

FTPException

java.io.IOException

exists

public boolean exists(java.lang.String remoteFileName)
               throws FTPException,
                      java.io.IOException

Determine if a remote file exists.

Specified by:

exists in interface FileTransferClientInterface

Parameters:

remoteFileName - name of remote file

Throws:

FTPException

java.io.IOException

existsDirectory

public boolean existsDirectory(java.lang.String remoteDir)
                        throws FTPException,
                               java.io.IOException

Determine if a remote directory exists.

Parameters:

remoteDir - name of remote directory

Throws:

FTPException

java.io.IOException

deleteFile

public void deleteFile(java.lang.String remoteFileName)
                throws FTPException,
                       java.io.IOException

Deletes a remote file.

Specified by:

deleteFile in interface FileTransferClientInterface

Parameters:

remoteFileName - name of remote file

Throws:

FTPException

java.io.IOException

deleteMultipleFiles

public void deleteMultipleFiles(java.lang.String wildcard)
                         throws FTPException,
                                java.io.IOException

Deletes remote files in the current directory that match the supplied wildcard

Parameters:

wildcard - wildcard string (supporting '*' and '?')

Throws:

FTPException

java.io.IOException

deleteMultipleFiles

public void deleteMultipleFiles(java.io.FileFilter filter)
                         throws FTPException,
                                java.io.IOException

Deletes remote files in the current directory that match the supplied filename filter

Parameters:

wildcard - filename filter

Throws:

FTPException

java.io.IOException

deleteMultipleFiles

public void deleteMultipleFiles(java.lang.String remoteDirectory,
                                java.lang.String wildcard,
                                boolean recursive)
                         throws FTPException,
                                java.io.IOException

Deletes remote files in the current directory.

Parameters:

remoteFileName - name of remote file

Throws:

FTPException

java.io.IOException

deleteMultipleFiles

public void deleteMultipleFiles(java.lang.String remoteDirectory,
                                java.io.FileFilter filter,
                                boolean recursive)
                         throws FTPException,
                                java.io.IOException

Deletes remote files in the current directory.

Parameters:

remoteFileName - name of remote file

Throws:

FTPException

java.io.IOException

rename

public void rename(java.lang.String renameFromName,
                   java.lang.String renameToName)
            throws FTPException,
                   java.io.IOException

Rename a remote file or directory.

Specified by:

rename in interface FileTransferClientInterface

Parameters:

renameFromName - original name

renameToName - new name

Throws:

FTPException

java.io.IOException

changeDirectory

public void changeDirectory(java.lang.String directoryName)
                     throws FTPException,
                            java.io.IOException

Change directory on the FTP server.

Specified by:

changeDirectory in interface FileTransferClientInterface

Parameters:

directoryName - name the remote directory to change into

Throws:

FTPException

java.io.IOException

changeToParentDirectory

public void changeToParentDirectory()
                             throws FTPException,
                                    java.io.IOException

Change to parent directory on the FTP server.

Specified by:

changeToParentDirectory in interface FileTransferClientInterface

Parameters:

directoryName - name the remote directory to change into

Throws:

FTPException

java.io.IOException

createDirectory

public void createDirectory(java.lang.String directoryName)
                     throws FTPException,
                            java.io.IOException

Create directory on the FTP server.

Specified by:

createDirectory in interface FileTransferClientInterface

Parameters:

directoryName - name the remote directory to create

Throws:

FTPException

java.io.IOException

deleteDirectory

public void deleteDirectory(java.lang.String directoryName)
                     throws FTPException,
                            java.io.IOException

Delete a directory on the FTP server. The directory must be empty, and not the current directory.

Specified by:

deleteDirectory in interface FileTransferClientInterface

Parameters:

directoryName - name the remote directory to create

Throws:

FTPException

java.io.IOException

deleteDirectory

public void deleteDirectory(java.lang.String directoryName,
                            boolean recursive)
                     throws FTPException,
                            java.io.IOException

Delete a directory on the FTP server, and optionally sub-directories. The directory must not be the current directory. The directory must be empty for a non-recursive delete.

Parameters:

directoryName - name the remote directory to create

recursive - true if recursive delete

Throws:

FTPException

java.io.IOException

uploadMultiple

public void uploadMultiple(java.lang.String localDir,
                           java.io.FileFilter filter)
                    throws FTPException,
                           java.io.IOException

Uploads local files from the supplied local directory that match the supplied FileFilter into the current remote directory. Not recursive. Operation is synchronous.

Parameters:

localDir - name of local directory

filter - filename filter

Throws:

FTPException

java.io.IOException

uploadMultiple

public void uploadMultiple(java.lang.String localDir,
                           java.lang.String wildcard)
                    throws FTPException,
                           java.io.IOException

Uploads local files from the supplied local directory that match the supplied wildcard into the current remote directory. Not recursive. Operation is synchronous.

Parameters:

localDir - name of local directory

wildcard - wildcard filter for files to be uploaded (supports '*' and '?')

Throws:

FTPException

java.io.IOException

uploadMultiple

public void uploadMultiple(java.lang.String localDir,
                           java.lang.String remoteDir,
                           java.lang.String wildcard,
                           boolean recursive)
                    throws FTPException,
                           java.io.IOException

Uploads local files from the supplied local directory that match the supplied wildcard into the supplied remote directory. If recursive is set to true, goes through all subdirectories. Operation is synchronous.

Parameters:

localDir - name of local directory

remoteDir - name of remote directory

wildcard - wildcard filter for files to be uploaded (supports '*' and '?')

recursive - if true, operation is recursive through subdirectories

Throws:

FTPException

java.io.IOException

uploadMultiple

public void uploadMultiple(java.lang.String localDir,
                           java.lang.String remoteDir,
                           java.io.FileFilter filter,
                           boolean recursive)
                    throws FTPException,
                           java.io.IOException

Uploads local files from the supplied local directory that match the supplied wildcard into the supplied remote directory. If recursive is set to true, goes through all sub-directories. Operation is synchronous.

Parameters:

localDir - name of local directory

remoteDir - name of remote directory

filter - filename filter for files to be uploaded

recursive - if true, operation is recursive through sub-directories

Throws:

FTPException

java.io.IOException

downloadMultiple

public void downloadMultiple(java.lang.String localDir,
                             java.io.FileFilter filter)
                      throws FTPException,
                             java.io.IOException

Downloads remote files to the supplied local directory that match the supplied wildcard from the current remote directory. Not recursive. Operation is asynchronous.

Parameters:

localDir - name of local directory

filter - filename filter

Throws:

FTPException

java.io.IOException

downloadMultiple

public void downloadMultiple(java.lang.String localDir,
                             java.lang.String wildcard)
                      throws FTPException,
                             java.io.IOException

Downloads remote files to the supplied local directory that match the supplied wildcard from the current remote directory. Not recursive. Operation is asynchronous.

Parameters:

localDir - name of local directory

wildcard - wildcard filter for files to be uploaded (supports '*' and '?')

Throws:

FTPException

java.io.IOException

downloadMultiple

public void downloadMultiple(java.lang.String localDir,
                             java.lang.String remoteDir,
                             java.lang.String wildcard,
                             boolean recursive)
                      throws FTPException,
                             java.io.IOException

Downloads remote files to the supplied local directory that match the supplied wildcard from the current remote directory. If recursive is set to true, goes through all sub-directories. Operation is synchronous.

Parameters:

localDir - name of local directory

remoteDir - name of remote directory

wildcard - wildcard filter for files to be uploaded (supports '*' and '?')

recursive - if true, operation is recursive through sub-directories

Throws:

FTPException

java.io.IOException

downloadMultiple

public void downloadMultiple(java.lang.String localDir,
                             java.lang.String remoteDir,
                             java.io.FileFilter filter,
                             boolean recursive)
                      throws FTPException,
                             java.io.IOException

Downloads remote files to the supplied local directory that match the supplied FileFilter from the current remote directory. If recursive is set to true, goes through all sub-directories. Operation is synchronous.

Parameters:

localDir - name of local directory

remoteDir - name of remote directory

filter - filename filter for files to be uploaded

recursive - if true, operation is recursive through sub-directories

Throws:

FTPException

java.io.IOException

disconnect

public void disconnect()
                throws FTPException,
                       java.io.IOException

Disconnect from the FTP server. All connections in the FTP connection pool are disconnected.

Specified by:

disconnect in interface FileTransferClientInterface

Throws:

FTPException

java.io.IOException

disconnect

public void disconnect(boolean immediate)
                throws FTPException,
                       java.io.IOException

Disconnect from the FTP server immediately.

Specified by:

disconnect in interface FileTransferClientInterface

Throws:

FTPException

java.io.IOException

addErrorListener

public void addErrorListener(ErrorListener listener)

Add an error listener to the list of listeners

Parameters:

listener - new error listener

shutdown

protected void shutdown(boolean immediate)

Shutdown all the worker threads in the task processor.

Parameters:

immediate - if true, shutdown immediately, i.e. do not wait for worker threads to terminate

finalize

public void finalize()

Finalize this instance by shutting down its threads

Overrides:

finalize in class java.lang.Object

cancelAllTransfers

public void cancelAllTransfers()

Cancel all transfers that are either pending or currently under way

Specified by:

cancelAllTransfers in interface FileTransferClientInterface