com.myjavaworld.ftp
Interface FTPClient

All Known Implementing Classes:

AS400FTPClient, DefaultFTPClient

public interface FTPClient

A contract for FTPClient implementation classes.

Version:

2.0

Author:

Sai Pullabhotla, psai [at] jMethods [dot] com

Method Summary

void	abort() Sends an abort command to the remote host.
void	addControlConnectionListener(ControlConnectionListener l) Adds a listener that will be notified about the activities of ControlConnection associated with this FTPClient .
void	addDataConnectionListener(DataConnectionListener l) Adds a DataConnection Listener to this FTPClient.
void	addFTPConnectionListener(FTPConnectionListener l) Adds the given FTPConnectionListener to the list of registered listeners.
void	allocate(long bytes) Allocates the specified number of bytes on the remote system.
void	close() Closes the control and data connections associated with this FTPClient.
void	connect(FTPHost ftpHost) Connects and logs in to the FTP host.
void	connect(String host) Connects to the specified remote host host on the default FTP port.
void	connect(String host, int port) Connects to the specfied remote host host, on the specified port number port.
void	createDirectory(RemoteFile dir) Creates the specified remote directory dir on the remote host.
void	createFile(RemoteFile file) Creates an empty file with the given name on the remote host.
void	delete(RemoteFile path) Deletes the specified path from the remote system.
void	deleteDirectory(RemoteFile dir) Deletes the specified directory dir on the remote system.
void	deleteFile(RemoteFile file) Deletes the specified file, file from the remote system.
void	disconnect() Sends a quit command to the remote system and closes the control connection and data connection associated with this FTPClient.
void	download(RemoteFile source, File destination, int type, boolean append) Copies the contents of the source to the local file destination.
String	executeCommand(String command) Executes the given command returns the response back.
int	getBufferSize() Returns the current buffer size being used by this FTPClient .
String	getExplicitSSLProtocol() Returns the SSL protocol that is in use for negotiating Explicit SSL connections.
String	getHelp() Executes the HELP command on the remote host and returns the response back.
EventListenerList	getListenerList() Returns the list of registered listeners.
ListParser	getListParser() Returns the current ListParser in use by this FTPClient.
InetAddress	getLocalAddress() Returns the InetAddress of the local host.
String	getLocalHost() Returns the host name or IP address of the local host.
String	getLocalIPAddress() Returns the IP address of the local host in xxx.xxx.xxx.xxx format.
int	getLocalPort() Returns the local port number used by the control connection.
int	getMode() Returns the current mode in use.
Proxy	getProxy() Returns the current proxy configuration, if any.
InetAddress	getRemoteAddress() Returns the Address of the remote host.
String	getRemoteHost() Returns the fully qaulified domain name of the remote host.
String	getRemoteIPAddress() Returns the IP address of the remote host in xxx.xxx.xxx.xxx format.
int	getRemotePort() Returns the remote port number to which the ControlConnection is established.
SSLContext	getSSLContext() Gets the SSLContext of this FTPclient.
int	getSSLUsage() Returns the SSL usage of this FTPClient.
int	getStructure() Returns the current structure in use.
String	getSystemInfo() Returns the remote host's information by executing the SYST command.
int	getTimeout() Returns the timeout setting of this FTP client.
int	getType() Returns the current data representation type in use.
RemoteFile	getWorkingDirectory() Returns the current working directory.
boolean	isConnected() Checks whether or not this FTPClient is still connected to to the remote host.
boolean	isDataChannelUnencrypted() Tells whether or not the data channel encryption is ON.
boolean	isLoggedIn() Checks wherher or not this client is logged in.
boolean	isPassive() Tells whether or not the data connectons are opned in passive mode.
boolean	isPassiveIPSubstitutionEnabled() Tells whether or not the substitution of passive IP address is enabled.
boolean	isSecured() Tells whether this connection is secured.
RemoteFile[]	list() Retrieves the contents (children) of the current working directory.
RemoteFile[]	list(Filter filter) Retrieves the children of the current working directory.
RemoteFile[]	list(RemoteFile dir) Returns the direct children of the specified directory.
RemoteFile[]	list(RemoteFile dir, Filter filter) Returns the direct children of the specified directory.
void	login(String user, String password) Logs in to the remote host with the specified user id and password.
void	login(String user, String password, String account) Logs in to the remote host with the specified user ID, pasword and account.
void	mountStructure(String path) Sends a SMNT command with the specified path to mount.
void	noop() Sends a No-Operation command to the remote system.
void	reinitialize() Sends a reinitialize command to the remote host.
void	removeControlConnectionListener(ControlConnectionListener l) Removes the given listener from the list of registered listenerrs.
void	removeDataConnectionListener(DataConnectionListener l) Removes the given data connection listener from the registered list of listeners.
void	removeFTPConnectionListener(FTPConnectionListener l) Unregisters the given listener from the list of listeners.
void	rename(RemoteFile from, RemoteFile to) Renames a file or directory, from to to.
void	restart(long bytes) Sends a RESTART command to the remote host with the specified number of bytes.
void	setBufferSize(int bufferSize) Sets the buffer size to use for transferring data over the data connection.
void	setDataChannelUnencrypted(boolean dataChannelUnencrypted) Sets/unsets the flag to encrypt the data channel.
void	setExplicitSSLProtocol(String protocol) Sets the SSL protocol to use when negotiating an Explicit SSL connection.
void	setListParser(ListParser listParser) Sets the ListParser to the specified listParser .ListParser objects are used to parsre the contents of a remote directory in to RemoteFile objects.
void	setMode(int mode) Sets the mode in which data is transferred to the given mode .
void	setPassive(boolean passive) If true, marks that the data is to be transgerrred over a passive data connection.
void	setPassiveIPSubstitutionEnabled(boolean enable) Sets or unsets the flag that determines whether or not to ignore the response (the IP address portion) of PASV command and substitute it with the original server IP address when making a PASSIVE data connection.
void	setProxy(Proxy proxy) Sets the proxy server to use when making the control/data connections.
void	setSiteParameter(String param) Sends a SITE command with the specified parameter(s).
void	setSSLContext(SSLContext context) Sets the SSLContext of this FTPClient to the given context.
void	setSSLUsage(int sslUsage) Sets the SSL usage of this client to the given value.
void	setStructure(int structure) Sets the structure to the specified structure.
void	setTimeout(int timeout) Sets the timeout for this FTPClient to the specified timeout.
RemoteFile	setToParentDirectory() Sets the remote working directory to the parent directory of the current working directory.
void	setType(int type) Sets the data representation type to the given type.
RemoteFile	setWorkingDirectory(RemoteFile dir) Sets the remote working directory to the specified directory dir.
void	upload(File source, RemoteFile destination, int type, boolean append, long skip) copies the contents of local file source to the specified remote file destination.

Method Detail

setTimeout

void setTimeout(int timeout)

Sets the timeout for this FTPClient to the specified timeout. Timeout is the amount of time an FTPClient waits for a server's reponse. If the server does not respond with in the timeout period, Implementations should close the connection. The timeout must be set before calling the connect methods. If an FTP client is already connected to a remote host, the new time out may be ignored by implementation classes.

Parameters:

timeout - Timeout in milli seconds.

getTimeout

int getTimeout()

Returns the timeout setting of this FTP client.

Returns:

Timeout of this FTPClient.

setBufferSize

void setBufferSize(int bufferSize)

Sets the buffer size to use for transferring data over the data connection.

Parameters:

bufferSize - Buffer size to use for transferring data over the data connection.

getBufferSize

int getBufferSize()

Returns the current buffer size being used by this FTPClient .

Returns:

Current buffer size in use.

setListParser

void setListParser(ListParser listParser)

Sets the ListParser to the specified listParser .ListParser objects are used to parsre the contents of a remote directory in to RemoteFile objects.

Parameters:

listParser - The ListParser to use to parse the contents of a remote directory.

getListParser

ListParser getListParser()

Returns the current ListParser in use by this FTPClient.

Returns:

ListParser in use.

setSSLUsage

void setSSLUsage(int sslUsage)

Sets the SSL usage of this client to the given value. The possible values are:

• FTPConstants.USE_NO_SSL
• FTPConstants.USE_SSL_IF_AVAILABLE
• FTPConstants.USE_EXPLICIT_SSL
• FTPConstants.USE_IMPLICIT_SSL

Parameters:

sslUsage - SSL usage parameter to set.

getSSLUsage

int getSSLUsage()

Returns the SSL usage of this FTPClient.

Returns:

SSL usage of this FTPClient. Possible values are:

• FTPConstants.USE_NO_SSL
• FTPConstants.USE_SSL_IF_AVAILABLE
• FTPConstants.USE_EXPLICIT_SSL
• FTPConstants.USE_IMPLICIT_SSL

setExplicitSSLProtocol

void setExplicitSSLProtocol(String protocol)

Sets the SSL protocol to use when negotiating an Explicit SSL connection. The specified protocol string will be sent (to the FTP server) as a parameter to the AUTH command. Valid values are "SSL" and "TLS", however, this method does not restrict clients from using other values.

Parameters:

protocol - the security protocol to use when negotiating an Explicit SSL connection.

getExplicitSSLProtocol

String getExplicitSSLProtocol()

Returns the SSL protocol that is in use for negotiating Explicit SSL connections.

Returns:

the SSL protocol that is in use for negotiating Explicit SSL connections. If the setExplicitSSLProtocol(string protocol) method is not called, this method returns the default value "SSL".

setSSLContext

void setSSLContext(SSLContext context)

Sets the SSLContext of this FTPClient to the given context.

Parameters:

context - SSLContext

getSSLContext

SSLContext getSSLContext()

Gets the SSLContext of this FTPclient.

Returns:

SSLContext of this FTPClient. May return null, if no context was set.

setDataChannelUnencrypted

void setDataChannelUnencrypted(boolean dataChannelUnencrypted)

Sets/unsets the flag to encrypt the data channel.

Parameters:

dataChannelUnencrypted - whether or not to encrypt the data channel.

isDataChannelUnencrypted

boolean isDataChannelUnencrypted()

Tells whether or not the data channel encryption is ON.

Returns:

true, if the data channel encryption os ON, false, otherwise.

isSecured

boolean isSecured()

Tells whether this connection is secured.

Returns:

true, if this connection is secured. false, othherwise.

connect

void connect(String host)
             throws FTPException,
                    ConnectionException

Connects to the specified remote host host on the default FTP port.

Parameters:

host - Host name or IP address of the remote host.

Throws:

FTPException

ConnectionException

connect

void connect(String host,
             int port)
             throws FTPException,
                    ConnectionException

Connects to the specfied remote host host, on the specified port number port.

Parameters:

host - Host name or IP address of the remote host.

port - Port number to connect to.

Throws:

FTPException

ConnectionException

connect

void connect(FTPHost ftpHost)
             throws FTPException,
                    ConnectionException

Connects and logs in to the FTP host.

Parameters:

ftpHost - Remote FTP host to connect to.

Throws:

FTPException

ConnectionException

isConnected

boolean isConnected()

Checks whether or not this FTPClient is still connected to to the remote host.

Returns:

true, if this FTPClient is still connected to the remote host. Otherwise, false.

login

void login(String user,
           String password)
           throws FTPException,
                  ConnectionException

Logs in to the remote host with the specified user id and password.

Parameters:

user - User ID.

password - Password.

Throws:

FTPException

ConnectionException

login

void login(String user,
           String password,
           String account)
           throws FTPException,
                  ConnectionException

Logs in to the remote host with the specified user ID, pasword and account. Not all FTP servers need Account information.

Parameters:

user - User ID.

password - Password.

account - Account Name.

Throws:

FTPException

ConnectionException

isLoggedIn

boolean isLoggedIn()

Checks wherher or not this client is logged in.

Returns:

true, if this client is logged in to the remote host. false otherwise.

setWorkingDirectory

RemoteFile setWorkingDirectory(RemoteFile dir)
                               throws FTPException,
                                      ConnectionException

Sets the remote working directory to the specified directory dir. Clients must send a PWD command after sending the CWD command to make sure that the working directory has changed.

Parameters:

dir - New remote working directory to set.

Returns:

Working directory after the execution of this method.

Throws:

FTPException

ConnectionException

setToParentDirectory

RemoteFile setToParentDirectory()
                                throws FTPException,
                                       ConnectionException

Sets the remote working directory to the parent directory of the current working directory.

Returns:

working directory after the execution of this method.

Throws:

FTPException

ConnectionException

getWorkingDirectory

RemoteFile getWorkingDirectory()
                               throws FTPException,
                                      ConnectionException

Returns the current working directory.

Returns:

Current remote working directory.

Throws:

FTPException

ConnectionException

setType

void setType(int type)
             throws FTPException,
                    ConnectionException

Sets the data representation type to the given type.

Parameters:

type - New data representation type to set. Possible types are -

• FTPConstants.TYPE_ASCII
• FTPConstants.TYPE_BINARY
• FTPConstants.TYPE_IMAGE
• FTPConstants.TYPE_EBCDIC
• FTPConstants.TYPE_LOCAL

Throws:

FTPException

ConnectionException

getType

int getType()

Returns the current data representation type in use.

Returns:

current data representation type.

setStructure

void setStructure(int structure)
                  throws FTPException,
                         ConnectionException

Sets the structure to the specified structure.

Parameters:

structure - New structure to set. Possible structure type are -

• FTPConstants.STRUCTURE_FILE
• FTPConstants.STRUCTURE_RECORD
• FTPConstants.STRUCTURE_PAGE

Throws:

FTPException

ConnectionException

getStructure

int getStructure()

Returns the current structure in use.

Returns:

current structure.

setMode

void setMode(int mode)
             throws FTPException,
                    ConnectionException

Sets the mode in which data is transferred to the given mode .

Parameters:

mode - The new mode to set. Possible modes are -

• FTPConstants.MODE_STREAM
• FTPConstants.MODE_BLOCK
• FTPConstants.MODE_COMPRESSED

Throws:

FTPException

ConnectionException

getMode

int getMode()

Returns the current mode in use.

Returns:

Current mode in use.

setPassive

void setPassive(boolean passive)

If true, marks that the data is to be transgerrred over a passive data connection.

Parameters:

passive - Value true marks that the data is to be transferred over a passive data connection. Otherwise, over an active data connection.

isPassive

boolean isPassive()

Tells whether or not the data connectons are opned in passive mode. This method will be consulted every time when there a need to open a data connection.

Returns:

true if in passive mode. Otherwise, false.

createDirectory

void createDirectory(RemoteFile dir)
                     throws FTPException,
                            ConnectionException

Creates the specified remote directory dir on the remote host.

Parameters:

dir - New directory to create.

Throws:

FTPException

ConnectionException

createFile

void createFile(RemoteFile file)
                throws FTPException,
                       ConnectionException

Creates an empty file with the given name on the remote host.

Parameters:

file - Path and name of the file.

Throws:

FTPException

ConnectionException

deleteDirectory

void deleteDirectory(RemoteFile dir)
                     throws FTPException,
                            ConnectionException

Deletes the specified directory dir on the remote system. Most FTP servers would not allow the deletion of a directory unless it is empty. It is the responsibility of the clients to delete the children of the directory before attempting to delete a directory.

Parameters:

dir - Directory to delete.

Throws:

FTPException

ConnectionException

deleteFile

void deleteFile(RemoteFile file)
                throws FTPException,
                       ConnectionException

Deletes the specified file, file from the remote system.

Parameters:

file - File to be deleted.

Throws:

FTPException

ConnectionException

delete

void delete(RemoteFile path)
            throws FTPException,
                   ConnectionException

Deletes the specified path from the remote system. If the path is a directory (as determined by RemoteFile.isDirectory()) , then deleteDirectory() method will be called with path as an argument. Otherwise, deleteFile() method will be called with path as an argument.

Parameters:

path - The file to delete.

Throws:

FTPException

ConnectionException

rename

void rename(RemoteFile from,
            RemoteFile to)
            throws FTPException,
                   ConnectionException

Renames a file or directory, from to to.

Parameters:

from - The file to be renamed.

to - New file name.

Throws:

FTPException

ConnectionException

noop

void noop()
          throws FTPException,
                 ConnectionException

Sends a No-Operation command to the remote system.

Throws:

FTPException

ConnectionException

abort

void abort()
           throws FTPException,
                  ConnectionException

Sends an abort command to the remote host.

Throws:

FTPException

ConnectionException

reinitialize

void reinitialize()
                  throws FTPException,
                         ConnectionException

Sends a reinitialize command to the remote host. Clients may need to login after executing this method.

Throws:

FTPException

ConnectionException

disconnect

void disconnect()
                throws FTPException,
                       ConnectionException

Sends a quit command to the remote system and closes the control connection and data connection associated with this FTPClient.

Throws:

FTPException

ConnectionException

close

void close()

Closes the control and data connections associated with this FTPClient. This method should usually be called after a network error ocuurs in order to clean up the resources. Under normal conditions, the clients are recommended to call disconnect method.

allocate

void allocate(long bytes)
              throws FTPException,
                     ConnectionException

Allocates the specified number of bytes on the remote system.

Parameters:

bytes - Number of bytes to allocate for this FTPClient.

Throws:

FTPException

ConnectionException

restart

void restart(long bytes)
             throws FTPException,
                    ConnectionException

Sends a RESTART command to the remote host with the specified number of bytes.

Parameters:

bytes - number of bytes to skip in the Input/Output stream.

Throws:

FTPException

ConnectionException

getSystemInfo

String getSystemInfo()
                     throws FTPException,
                            ConnectionException

Returns the remote host's information by executing the SYST command.

Returns:

remote host's system information. The informaion returned will vary from FTP server to server.

Throws:

FTPException

ConnectionException

getHelp

String getHelp()
               throws FTPException,
                      ConnectionException

Executes the HELP command on the remote host and returns the response back.

Returns:

Response to HELP command.

Throws:

FTPException

ConnectionException

setSiteParameter

void setSiteParameter(String param)
                      throws FTPException,
                             ConnectionException

Sends a SITE command with the specified parameter(s).

Parameters:

param - Parameters or the SITE command.

Throws:

FTPException

ConnectionException

mountStructure

void mountStructure(String path)
                    throws FTPException,
                           ConnectionException

Sends a SMNT command with the specified path to mount.

Parameters:

path - New path structure to mount.

Throws:

FTPException

ConnectionException

executeCommand

String executeCommand(String command)
                      throws FTPException,
                             ConnectionException

Executes the given command returns the response back.

Parameters:

command - Command to execute.

Returns:

Response to the command sent.

Throws:

FTPException

ConnectionException

getRemoteAddress

InetAddress getRemoteAddress()

Returns the Address of the remote host.

Returns:

InetAddress of the remote host.

getRemoteHost

String getRemoteHost()

Returns the fully qaulified domain name of the remote host.

Returns:

domain name or IP address of the remote host.

getRemoteIPAddress

String getRemoteIPAddress()

Returns the IP address of the remote host in xxx.xxx.xxx.xxx format.

Returns:

IP address of the remote host.

getRemotePort

int getRemotePort()

Returns the remote port number to which the ControlConnection is established.

Returns:

port number.

getLocalAddress

InetAddress getLocalAddress()

Returns the InetAddress of the local host.

Returns:

InetAddress of the local host.

getLocalHost

String getLocalHost()

Returns the host name or IP address of the local host.

Returns:

Host name or IP address of the local host.

getLocalIPAddress

String getLocalIPAddress()

Returns the IP address of the local host in xxx.xxx.xxx.xxx format.

Returns:

IP address of the local host.

getLocalPort

int getLocalPort()

Returns the local port number used by the control connection.

Returns:

Local port number.

list

RemoteFile[] list()
                  throws FTPException,
                         ParseException,
                         ConnectionException

Retrieves the contents (children) of the current working directory.

Returns:

Direct children of the current working directory.

Throws:

FTPException

ParseException

ConnectionException

list

RemoteFile[] list(Filter filter)
                  throws FTPException,
                         ParseException,
                         ConnectionException

Retrieves the children of the current working directory. The contents will be filtered using the given filter.

Parameters:

filter - the filter to use.

Returns:

direct children of the working directory.

Throws:

FTPException

ParseException

ConnectionException

list

RemoteFile[] list(RemoteFile dir)
                  throws FTPException,
                         ParseException,
                         ConnectionException

Returns the direct children of the specified directory.

Parameters:

dir - directory whose children are to be retrieved

Returns:

Direct children of the specified directory dir.

Throws:

FTPException

ParseException

ConnectionException

list

RemoteFile[] list(RemoteFile dir,
                  Filter filter)
                  throws FTPException,
                         ParseException,
                         ConnectionException

Returns the direct children of the specified directory.

Parameters:

dir - directory whose children are to be retrieved.

filter - Fiter to apply.

Returns:

Direct children of the given directory.

Throws:

FTPException

ParseException

ConnectionException

download

void download(RemoteFile source,
              File destination,
              int type,
              boolean append)
              throws FTPException,
                     ConnectionException

Copies the contents of the source to the local file destination.

Parameters:

source - Remote file to be copied or downloaded.

destination - Local file to which the contents are to be copied.

type - Data representation type to use for data transfer.

append - Whether or not to open the destination file in append mode.

Throws:

FTPException

ConnectionException

upload

void upload(File source,
            RemoteFile destination,
            int type,
            boolean append,
            long skip)
            throws FTPException,
                   ConnectionException

copies the contents of local file source to the specified remote file destination.

Parameters:

source - Local file to be copied.

destination - Destination file on the remote system.

type - Data representation type to use for data transfer.

append - Whether or not the destination file is to be appended with the contents of source file.

skip - Number of bytes to skip.

Throws:

FTPException

ConnectionException

addControlConnectionListener

void addControlConnectionListener(ControlConnectionListener l)

Adds a listener that will be notified about the activities of ControlConnection associated with this FTPClient .

Parameters:

l - Listener to register.

removeControlConnectionListener

void removeControlConnectionListener(ControlConnectionListener l)

Removes the given listener from the list of registered listenerrs.

Parameters:

l - Listner to remove from the registered listener list.

addDataConnectionListener

void addDataConnectionListener(DataConnectionListener l)

Adds a DataConnection Listener to this FTPClient.

Parameters:

l - Listener to register.

removeDataConnectionListener

void removeDataConnectionListener(DataConnectionListener l)

Removes the given data connection listener from the registered list of listeners.

Parameters:

l - Listener to unregister.

getListenerList

EventListenerList getListenerList()

Returns the list of registered listeners.

Returns:

List of registered listeners.

addFTPConnectionListener

void addFTPConnectionListener(FTPConnectionListener l)

Adds the given FTPConnectionListener to the list of registered listeners.

Parameters:

l - Listener to register.

removeFTPConnectionListener

void removeFTPConnectionListener(FTPConnectionListener l)

Unregisters the given listener from the list of listeners.

Parameters:

l - Listener to unregister.

setPassiveIPSubstitutionEnabled

void setPassiveIPSubstitutionEnabled(boolean enable)

Sets or unsets the flag that determines whether or not to ignore the response (the IP address portion) of PASV command and substitute it with the original server IP address when making a PASSIVE data connection. This method has been added to support some FTP servers that return an unreachable IP address in response to the PASV command. This method can also be used to ensure that the data connections will always be made to the same server to which you are connected.

Parameters:

enable - true to enable the IP address substitution; false to disable it.

isPassiveIPSubstitutionEnabled

boolean isPassiveIPSubstitutionEnabled()

Tells whether or not the substitution of passive IP address is enabled.

Returns:

true, if the addressed retunred by the server in response to a PASV command will be ignored and substituted with the original server's IP address; false, otherewise.

setProxy

void setProxy(Proxy proxy)

Sets the proxy server to use when making the control/data connections.

Parameters:

proxy - the proxy server to use when making the control/data connections. Supported proxy types are - SOCKS and DIRECT.

getProxy

Proxy getProxy()

Returns the current proxy configuration, if any.

Returns:

the current proxy configuration, if any. Returns null, if there is no proxy set.