gnu.inet.ftp
Class FtpClient

java.lang.Object
  |
  +--gnu.inet.ftp.FtpClientProtocol
        |
        +--gnu.inet.ftp.FtpClient

All Implemented Interfaces:

ConnectionEventSource, TransferEventSource

public class FtpClient

extends FtpClientProtocol

implements ConnectionEventSource, TransferEventSource

This class implements convenience methods that wrapper the FtpClientProtocol methods for common functionality.

Most developers will want to use this class rather than the lower-level FtpClientProtocol methods directly.

See Also:

FtpClientProtocol

Field Summary

protected PassiveConnection

connection This is a cached PassiveConnection instance.

Fields inherited from class gnu.inet.ftp.FtpClientProtocol

DEFAULT_PORT, fileType, greeting, istream, MDTM_TIME_FORMAT1, MDTM_TIME_FORMAT2, MODE_BLOCK, MODE_COMPRESSED, MODE_STREAM, MODE_ZLIB, ostream, port, sock, STRU_FILE, STRU_PAGE, STRU_RECORD, STRU_TIFF, TYPE_ASCII, TYPE_EBCDIC, TYPE_IMAGE, TYPE_LOCAL

Constructor Summary

FtpClient()
default constructor.

Method Summary

void	addConnectionListener(ConnectionListener listener) Register a connection listener with the event source.
void	addConnectionListeners(java.util.Vector listeners) Register a set of connection listeners with the event source.
void	addTransferListener(TransferListener listener) Register a transfer listener with the event source.
void	addTransferListeners(java.util.Vector listeners) Register a set of transfer listeners with the event source.
void	get(java.lang.String path, java.io.OutputStream out) GET the named file, FTP style.
java.util.Vector	getList() get a long-style listing of files in the current directory.
java.util.Vector	getList(java.lang.String path) get a long-style listing of files in the given directory.
java.util.Vector	getNameList() get name list of files in the current directory.
java.util.Vector	getNameList(java.lang.String path) get name list of files in the given directory.
boolean	getPassive() check whether we're using passive transfers or not.
static void	main(java.lang.String[] Arguments) run some basic tests.
void	mode(char mode) set the transfer mode.
java.lang.String	put(java.io.InputStream in) put a file with a unique name.
void	put(java.io.InputStream in, java.lang.String pathname) store a file.
java.lang.String	putTemporary(java.io.InputStream data) put a temp file, the data is stored in a uniquely named file on the server.
void	removeConnectionListener(ConnectionListener listener) De-register a connection listener with the event source.
void	removeTransferListener(TransferListener listener) De-register a transfer listener with the event source.
void	rename(java.lang.String source, java.lang.String target) Renames remote file from source to target.
void	setPassive(boolean passive) enable or disable passive transfers

Methods inherited from class gnu.inet.ftp.FtpClientProtocol

abor, abor, cdup, connect, cwd, dele, getDebug, getGreeting, getInetAddress, getType, idle, idle, list, list, mdtm, nlst, nlst, noop, open, open, open, pass, pasv, port, pwd, quit, readResponse, retr, rnfr, rnto, setDebug, size, stat, stat, stor, stot, stou, stru, syst, type, user

Methods inherited from class java.lang.Object

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

Field Detail

connection

protected PassiveConnection connection

This is a cached PassiveConnection instance. After some hair-pulling I came to realize that in order to avoid an annoying bug, I needed to cache the last PassiveConnection instance in case an error was encountered in the last passive transfer. In my test cases the error condition that triggered the wierd bug could be duplicated by attempting to getList(some-non-exising-file). This caused an exception during the LIST transfer. The next PASV command would return the same IP/Port values. Opening a second socket to the same IP/Port would yield an exception or other errors. Caching the last PassiveConnection (and by extension the Socket) I could reuse the last PassiveConnection values avoiding the bug/error-condition. This is not very pretty but it works. Unfortunately, I'm worried that it may not be very portable since it relies on the behavior of the HylaFAX server. I'll have to see if this behavior is in the FTP RFC (RFC0959.)

Whenever a successful passive transfer occurrs, this variable should be set to null, thereby invalidating the cached value.

Constructor Detail

FtpClient

public FtpClient()

default constructor. initialize class state.

Method Detail

setPassive

public void setPassive(boolean passive)

enable or disable passive transfers

Parameters:

passive - indicates whether passive transfers should be used

getPassive

public boolean getPassive()

check whether we're using passive transfers or not.

Returns:

true if passive transfers are enabled, false otherwise

mode

public void mode(char mode)
          throws java.io.IOException,
                 ServerResponseException

set the transfer mode. valid mode values are MODE_* listed in the FtpClientProtocol class.

Overrides:

mode in class FtpClientProtocol

Parameters:

mode - the new mode setting

Throws:

java.io.IOException - an io error occurred talking to the server

ServerResponseException - the server replied with an error code

addConnectionListener

public void addConnectionListener(ConnectionListener listener)

Register a connection listener with the event source.

Specified by:

addConnectionListener in interface ConnectionEventSource

Parameters:

listener - the listener to register with the event source

addConnectionListeners

public void addConnectionListeners(java.util.Vector listeners)

Register a set of connection listeners with the event source.

Specified by:

addConnectionListeners in interface ConnectionEventSource

Parameters:

listeners - the listeners to register with the event source

removeConnectionListener

public void removeConnectionListener(ConnectionListener listener)

De-register a connection listener with the event source.

Specified by:

removeConnectionListener in interface ConnectionEventSource

Parameters:

listener - the listener to de-register with the event source

addTransferListener

public void addTransferListener(TransferListener listener)

Register a transfer listener with the event source.

Specified by:

addTransferListener in interface TransferEventSource

Parameters:

listener - the listener to register with the event source

addTransferListeners

public void addTransferListeners(java.util.Vector listeners)

Register a set of transfer listeners with the event source.

Specified by:

addTransferListeners in interface TransferEventSource

Parameters:

listeners - the listeners to register with the event source

removeTransferListener

public void removeTransferListener(TransferListener listener)

De-register a transfer listener with the event source.

Specified by:

removeTransferListener in interface TransferEventSource

Parameters:

listener - the listener to de-register with the event source

putTemporary

public java.lang.String putTemporary(java.io.InputStream data)
                              throws java.io.IOException,
                                     ServerResponseException

put a temp file, the data is stored in a uniquely named file on the server. The remote temp file is deleted when the connection is closed. NOTE: this calls stot() internally.

Returns:

the filename of the temp file

Throws:

java.io.IOException - io error occurred talking to the server

ServerResponseException - server replied with error code

put

public java.lang.String put(java.io.InputStream in)
                     throws java.io.IOException,
                            ServerResponseException

put a file with a unique name. NOTE: this calls stou() internally.

Returns:

the name of the file created

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error code

put

public void put(java.io.InputStream in,
                java.lang.String pathname)
         throws java.io.IOException,
                ServerResponseException

store a file. NOTE: this calls stor() internally.

Parameters:

pathname - name of file to store on server (where to put the file on the server)

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error

getList

public java.util.Vector getList(java.lang.String path)
                         throws java.io.IOException,
                                java.io.FileNotFoundException,
                                ServerResponseException

get a long-style listing of files in the given directory. NOTE: this calls the list() method internally.

Parameters:

path - the path that we're interested in finding the contents of

Returns:

a Vector of Strings containing the list information

Throws:

java.io.IOException - an IO error occurred

java.io.FileNotFoundException - the given path doesn't exist

ServerResponseException - the server reported an error

getList

public java.util.Vector getList()
                         throws java.io.IOException,
                                java.io.FileNotFoundException,
                                ServerResponseException

get a long-style listing of files in the current directory. NOTE: this calls the list() method internally with the "." path.

Returns:

a Vector of Strings containing the list information

Throws:

java.io.IOException - an IO error occurred

java.io.FileNotFoundException - the "." path doesn't exist

ServerResponseException - the server reported an error

getNameList

public java.util.Vector getNameList(java.lang.String path)
                             throws java.io.IOException,
                                    ServerResponseException,
                                    java.io.FileNotFoundException

get name list of files in the given directory. Similar to getList() but returns filenames only where getList() returns other, system dependant information.

Parameters:

path - the path of the directory that we want the name list of

Returns:

Vector of Strings containing filenames

Throws:

java.io.IOException - an IO error occurred

ServerResponseException - the server reported an error

java.io.FileNotFoundException - the requested path does not exist

getNameList

public java.util.Vector getNameList()
                             throws java.io.IOException,
                                    ServerResponseException,
                                    java.io.FileNotFoundException

get name list of files in the current directory. Similar to getList() but returns filenames only where getList() returns other, system dependant information.

Returns:

Vector of Strings containing filenames

Throws:

java.io.IOException - an IO error occurred

ServerResponseException - the server reported an error

java.io.FileNotFoundException - the requested path does not exist

get

public void get(java.lang.String path,
                java.io.OutputStream out)
         throws java.io.IOException,
                java.io.FileNotFoundException,
                ServerResponseException

GET the named file, FTP style.

Parameters:

path - the name of the file to GET. This can be a full or partial path.

out - the OutputStream to write the file data to

Throws:

java.io.IOException - an IO error occurred

ServerResponseException - the server reported an error

java.io.FileNotFoundException - the given path does not exist

rename

public void rename(java.lang.String source,
                   java.lang.String target)
            throws java.io.IOException,
                   ServerResponseException,
                   java.io.FileNotFoundException

Renames remote file from source to target. Uses rnfr and rnto internally.

Parameters:

source - file to rename

target - new filename

Throws:

java.io.IOException - an IO error occurred

ServerResponseException - the server reported an error

java.io.FileNotFoundException - the source file does not exist

main

public static void main(java.lang.String[] Arguments)

run some basic tests. eventually this method should be removed in favor of a decent testing framework.

Parameters:

Arguments - an array of command-line-argument Strings