zeta.tool
Class FTP

java.lang.Object
  |
  +--zeta.tool.FTP

public class FTP

extends java.lang.Object

Implementation of the File Transfer Protocol. Only the passive mode is implemented for connections, i.e. forces the client to open the data connection to the FTP server which is useful to getting past Firewalls.

Nested Class Summary

private static class

FTP.Response Encompasses the FTP server's response - code and message

Field Summary

private boolean	abort
private boolean	allowRestart
private boolean	authenticated
private int	bufferSize Transmit buffer defaults to 10k (binary transfers only)
private java.io.BufferedReader	controlInputStream
private java.io.PrintStream	controlOutputStream
private java.net.Socket	controlSocket
private java.io.PrintStream	debug Printer for debugging statements.
private java.lang.String	host
static boolean	MODE_ASCII Use ASCII mode (attempt to handle new-line's in a sane manner)
static boolean	MODE_BINARY Use binary mode - no translation is performed.
private int	socketTimeout Network socket timeout.
private int	transferSleep

Constructor Summary

FTP()

Method Summary

void	abort() Attempt to gracefully abort active transfer.
void	cd(java.lang.String newDir) Switches current directory on the FTP server.
private void	checkConnection(java.lang.String command) Checks whether the FTP connection has been authenticated.
private FTP.Response	checkResponseCode(java.lang.String command) Convinience routine to simplify the creation of exceptions
void	close() Closes the control connection to the FTP server.
void	connect(java.lang.String host) Connect to the specified host using standard FTP port (21).
void	connect(java.lang.String host, int port) Connect to the specified host using standard FTP port (21) The default network socket timeout is 50 milliseconds.
void	deleteDir(java.lang.String dirName) Removes a directory on the FTP server.
void	deleteFile(java.lang.String fileName) Removes a specified file on the FTP server.
java.util.List	dir() Retrieves the file list in the current working directory on the FTP server.
void	disconnect() Closes the control connection to the FTP server.
private FTP.Response	executeCommand(java.lang.String commandName, java.lang.String arguments) Executes an FTP command and checks the response
void	get(java.lang.String remoteFile, java.io.OutputStream output, boolean mode) Downloads the specified remote file from FTP server in the output stream using the specified mode.
void	get(java.lang.String remoteFile, java.io.OutputStream output, boolean mode, long startAt) Downloads the specified remote file from FTP server in the output stream using the specified mode, starting at the specified position (byte).
void	get(java.lang.String remoteFile, java.lang.String localFile, boolean mode) Downloads the specified remote file from FTP server to the local file using the specified mode.
void	get(java.lang.String remoteDir, java.lang.String remoteFile, java.io.OutputStream output, boolean mode, long startAt) Downloads the specified remote file residing in the remote directory from FTP server in the output stream using the specified mode, starting at the specified position (byte).
void	get(java.lang.String remoteDir, java.lang.String remoteFile, java.lang.String localFile, boolean mode) Downloads the specified remote file residing in the remote directory from FTP server to the local file using the specified mode.
int	getBufferSize() Returns the current send/receive buffer size for binary transfers.
private java.net.Socket	getDataSocket(java.lang.String command) Creates a passive socket and executes the specified command.
java.lang.String	getHost() Returns the host name of the FTP server.
int	getSocketTimeout() Returns the current socket timeout in milliseconds.
boolean	isAllowRestart() Returns true if code attempts to restart downloads, false if existing files are overwritten.
boolean	isDebug() Returns current debug state.
void	login(java.lang.String user, java.lang.String password) Authenticate with the FTP server which is required for most operations.
java.util.List	longDir() Retrieves the extended file list in the current working directory on the FTP server.
static void	main(java.lang.String[] args) Simple test program.
void	makeDir(java.lang.String newDir) Creates a directory on the FTP server.
void	put(java.io.InputStream in, java.lang.String remoteFile, boolean mode) Uploads the contents of the specified input stream to the remote file (in current remote directory of the FTP server) using the specified mode.
void	put(java.io.InputStream in, java.lang.String remoteDir, java.lang.String remoteFile, boolean mode) Uploads the contents of the specified input stream to the remote file in the remote directory of the FTP server using the specified mode.
void	put(java.lang.String localFile, java.lang.String remoteFile, boolean mode) Uploads the specified local file to the remote file (in current remote directory of the FTP server) using the specified mode.
void	put(java.lang.String localFile, java.lang.String remoteDir, java.lang.String remoteFile, boolean mode) Uploads the specified local file to the remote file in the remote directory of the FTP server using the specified mode.
java.lang.String	pwd() Returns the current working directory as seen by the FTP server.
java.lang.String	quote(java.lang.String param) Executes an arbitrary command on the FTP server.
void	rename(java.lang.String oldName, java.lang.String newName) Renames a specified file on the FTP server.
void	setAllowRestart(boolean allowRestart) Allow the library to automatically restart downloads.
void	setBufferSize(int size) Set the send/receive buffer size for binary transfers.
void	setDebug(java.io.PrintStream debug) Enable or disable debugging.
void	setMode(boolean mode) Switches the transfer mode.
void	setSocketTimeout(int timeout) Sets the network socket timeout in milliseconds.
void	setTransferSleep(int millis) Causes the currently executing thread to sleep for the specified number of milliseconds after during each send/receive.
java.lang.String	site(java.lang.String siteCmd) Executes a SITE command on the FTP server.
java.lang.String	systemID() Returns the System ID as supplied by the FTP server.

Methods inherited from class java.lang.Object

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

Field Detail

MODE_ASCII

public static final boolean MODE_ASCII

Use ASCII mode (attempt to handle new-line's in a sane manner)

See Also:

Constant Field Values

MODE_BINARY

public static final boolean MODE_BINARY

Use binary mode - no translation is performed.

See Also:

Constant Field Values

socketTimeout

private int socketTimeout

Network socket timeout.

debug

private java.io.PrintStream debug

Printer for debugging statements.

bufferSize

private int bufferSize

Transmit buffer defaults to 10k (binary transfers only)

transferSleep

private int transferSleep

allowRestart

private boolean allowRestart

host

private java.lang.String host

controlSocket

private java.net.Socket controlSocket

controlInputStream

private java.io.BufferedReader controlInputStream

controlOutputStream

private java.io.PrintStream controlOutputStream

authenticated

private boolean authenticated

abort

private boolean abort

Constructor Detail

FTP

public FTP()

Method Detail

connect

public void connect(java.lang.String host)
             throws java.io.IOException

Connect to the specified host using standard FTP port (21). The default network socket timeout is 50 milliseconds.

Parameters:

host - host name of the FTP server

Throws:

java.io.IOException - if an I/O error occurs.

connect

public void connect(java.lang.String host,
                    int port)
             throws java.io.IOException

Connect to the specified host using standard FTP port (21) The default network socket timeout is 50 milliseconds.

Parameters:

host - host name of the FTP server

port - port number of the FTP server

Throws:

java.io.IOException - if an I/O error occurs.

login

public void login(java.lang.String user,
                  java.lang.String password)
           throws java.io.IOException

Authenticate with the FTP server which is required for most operations. An authentication failure will result in an I/O exception.

java.io.IOException

abort

public void abort()
           throws java.io.IOException

Attempt to gracefully abort active transfer. Note that servers implement this differently - some may leave semi-uploaded files in place, others may delete them. An abort while dowloading will result in the file being truncated.

java.io.IOException

close

public void close()

Closes the control connection to the FTP server. Synonymous to the method disconnect().

disconnect

public void disconnect()

Closes the control connection to the FTP server.

setMode

public void setMode(boolean mode)
             throws java.io.IOException

Switches the transfer mode. Valid modes are MODE_ASCII and MODE_BINARY. ASCII mode attempts to convert newlines to a format understandable by the target system. This works for text files, but corrupts data files. Binary mode ensures that the file is transferred "as-is." For transfers between like-systems this is the preferred mode, as it is much faster.

java.io.IOException

get

public void get(java.lang.String remoteFile,
                java.lang.String localFile,
                boolean mode)
         throws java.io.IOException

Downloads the specified remote file from FTP server to the local file using the specified mode. The mode can be MODE_ASCII or MODE_BINARY. The remote file must be in the current directory, or the full path must be given.

java.io.IOException

get

public void get(java.lang.String remoteDir,
                java.lang.String remoteFile,
                java.lang.String localFile,
                boolean mode)
         throws java.io.IOException

Downloads the specified remote file residing in the remote directory from FTP server to the local file using the specified mode. The mode can be MODE_ASCII or MODE_BINARY.

java.io.IOException

get

public void get(java.lang.String remoteFile,
                java.io.OutputStream output,
                boolean mode)
         throws java.io.IOException

Downloads the specified remote file from FTP server in the output stream using the specified mode. The mode can be MODE_ASCII or MODE_BINARY. The remote file must be in the current directory, or the full path must be given.

java.io.IOException

get

public void get(java.lang.String remoteFile,
                java.io.OutputStream output,
                boolean mode,
                long startAt)
         throws java.io.IOException

Downloads the specified remote file from FTP server in the output stream using the specified mode, starting at the specified position (byte). The mode can be MODE_ASCII or MODE_BINARY. The remote file must be in the current directory, or the full path must be given.

java.io.IOException

get

public void get(java.lang.String remoteDir,
                java.lang.String remoteFile,
                java.io.OutputStream output,
                boolean mode,
                long startAt)
         throws java.io.IOException

Downloads the specified remote file residing in the remote directory from FTP server in the output stream using the specified mode, starting at the specified position (byte). The mode can be MODE_ASCII or MODE_BINARY. The remote file must be in the current directory, or the full path must be given.

java.io.IOException

put

public void put(java.lang.String localFile,
                java.lang.String remoteFile,
                boolean mode)
         throws java.io.IOException

Uploads the specified local file to the remote file (in current remote directory of the FTP server) using the specified mode. The mode can be MODE_ASCII or MODE_BINARY. The local file should include a fully qualified path.

java.io.IOException

put

public void put(java.lang.String localFile,
                java.lang.String remoteDir,
                java.lang.String remoteFile,
                boolean mode)
         throws java.io.IOException

Uploads the specified local file to the remote file in the remote directory of the FTP server using the specified mode. The mode can be MODE_ASCII or MODE_BINARY. The local file should include a fully qualified path.

java.io.IOException

put

public void put(java.io.InputStream in,
                java.lang.String remoteFile,
                boolean mode)
         throws java.io.IOException

Uploads the contents of the specified input stream to the remote file (in current remote directory of the FTP server) using the specified mode. The mode can be MODE_ASCII or MODE_BINARY.

java.io.IOException

put

public void put(java.io.InputStream in,
                java.lang.String remoteDir,
                java.lang.String remoteFile,
                boolean mode)
         throws java.io.IOException

Uploads the contents of the specified input stream to the remote file in the remote directory of the FTP server using the specified mode. The mode can be MODE_ASCII or MODE_BINARY.

java.io.IOException

dir

public java.util.List dir()
                   throws java.io.IOException

Retrieves the file list in the current working directory on the FTP server. The list contains Strings containing the returned filename. Note that no distinction is made between files and subdirectories. Some servers are known to return an error message if the current directory contains no files, i.e. this in turn causes an exception.

java.io.IOException

longDir

public java.util.List longDir()
                       throws java.io.IOException

Retrieves the extended file list in the current working directory on the FTP server. The format used is highly dependent on the FTP server, but will generally include some indication of the file name, size, create date, and type (directory/filename). Use the systemID() call to determine how to parse the output. Some servers are known to return an error message if the current directory contains no files, i.e. this in turn causes an exception.

java.io.IOException

systemID

public java.lang.String systemID()
                          throws java.io.IOException

Returns the System ID as supplied by the FTP server. The reply can be used to determine how to interpret full directory listings for example.

java.io.IOException

cd

public void cd(java.lang.String newDir)
        throws java.io.IOException

Switches current directory on the FTP server. If the directory does not exist the FTP server generally reports an error, which results in an exception.

java.io.IOException

makeDir

public void makeDir(java.lang.String newDir)
             throws java.io.IOException

Creates a directory on the FTP server. The directory is created under the current working directory, see the method pwd(). You must generally create one directory at a time, i.e. you cannot call makeDir("/tmp/foo/bar") if the directory "/tmp/foo" does not already exist. Note that syntax rules of the client machine may differ from the host's - upper/lowercase conventions, allowable characters, etc.

java.io.IOException

pwd

public java.lang.String pwd()
                     throws java.io.IOException

Returns the current working directory as seen by the FTP server. Note that because of links, filesystem structure may not follow a sequence of "cd" commands.

java.io.IOException

rename

public void rename(java.lang.String oldName,
                   java.lang.String newName)
            throws java.io.IOException

Renames a specified file on the FTP server. On most servers the source and target files must reside in the current working directory. Exception may result if the client lacks the necessary permissions, if the source file does not exist, or if the target filename is invalid on the FTP host.

java.io.IOException

deleteDir

public void deleteDir(java.lang.String dirName)
               throws java.io.IOException

Removes a directory on the FTP server. On most systems the directory to be removed must reside directly beneath the current working directory. Exceptions may result if the client lacks the necessary permissions, if the subdirectory cannot be located, or if it is in use.

java.io.IOException

deleteFile

public void deleteFile(java.lang.String fileName)
                throws java.io.IOException

Removes a specified file on the FTP server. On most systems the target file must reside in the current working directory. Exceptions may result if the file cannot be found, or if the client lacks the necessary permissions.

java.io.IOException

quote

public java.lang.String quote(java.lang.String param)
                       throws java.io.IOException

Executes an arbitrary command on the FTP server. The command is passed directly to the FTP server. The response is the string reply on the command channel. No attempt is made to open data connections.

java.io.IOException

site

public java.lang.String site(java.lang.String siteCmd)
                      throws java.io.IOException

Executes a SITE command on the FTP server. The SITE command allows the FTP client to change server behavior, i.e. on MS's FTP server is can be used to switch directory listings to a unix-like format. The supported syntax varies among FTP implementations.

java.io.IOException

getHost

public java.lang.String getHost()

Returns the host name of the FTP server. The returned string is whatever was used to connect to the host originally - a DNS name, or an IP address. No DNS lookup is performed here.

setBufferSize

public void setBufferSize(int size)

Set the send/receive buffer size for binary transfers. The buffer defaults to 10k, which is sufficient for most operations. If you are transferring lots of small files and you want to reduce the memory overhead you can make it smaller. For very fast connections you might benefit from a larger buffer. Changes to the buffer size have no impact on active transfers.

getBufferSize

public int getBufferSize()

Returns the current send/receive buffer size for binary transfers.

setTransferSleep

public void setTransferSleep(int millis)

Causes the currently executing thread to sleep for the specified number of milliseconds after during each send/receive.

setSocketTimeout

public void setSocketTimeout(int timeout)

Sets the network socket timeout in milliseconds. This is the amount of time that the system will wait before considering a link dead. The default value is 50 seconds, i.e. 50000 msec. For satellite-linkup or other high-latency connections this can be made higher. For high-speed internal networks you can lower the default to get faster notification of errors.

getSocketTimeout

public int getSocketTimeout()

Returns the current socket timeout in milliseconds.

setAllowRestart

public void setAllowRestart(boolean allowRestart)

Allow the library to automatically restart downloads. When set to true>, the libarary will check the existing file size, and re-start the download at that point. This feature does not take into account corrupted data, etc. The default setting of false means that existing files will get overwritten. Note that this has no effect on downloads to streams.

isAllowRestart

public boolean isAllowRestart()

Returns true if code attempts to restart downloads, false if existing files are overwritten. By default the library will overwrite existing files. Note that this has no effect on downloads to streams.

setDebug

public void setDebug(java.io.PrintStream debug)

Enable or disable debugging. When in debug mode, the library will print to the specified print stream a "transcript" of the session, excluding of course the content of files or passwords being transferred.

isDebug

public boolean isDebug()

Returns current debug state.

checkConnection

private void checkConnection(java.lang.String command)
                      throws java.io.IOException

Checks whether the FTP connection has been authenticated. An exception is raised if the connection had not been authenticated.

java.io.IOException

checkResponseCode

private FTP.Response checkResponseCode(java.lang.String command)
                                throws java.io.IOException

Convinience routine to simplify the creation of exceptions

java.io.IOException

executeCommand

private FTP.Response executeCommand(java.lang.String commandName,
                                    java.lang.String arguments)
                             throws java.io.IOException

Executes an FTP command and checks the response

java.io.IOException

getDataSocket

private java.net.Socket getDataSocket(java.lang.String command)
                               throws java.io.IOException

Creates a passive socket and executes the specified command.

java.io.IOException

main

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

Simple test program.