com.enterprisedt.net.ftp
Interface FTPClientInterface

All Known Implementing Classes:

FTPClient

public interface FTPClientInterface

Defines operations in common with a number of FTP implementations.

Version:

$Revision: 1.16 $

Author:

Hans Andersen

Method Summary

void	cancelResume() Cancel the resume.
void	cancelTransfer() Cancels the current transfer.
void	cdup() Change the remote working directory to the parent directory
void	chdir(String dir) Change the remote working directory to that supplied
void	connect() Connects to the server at the address and port number defined in the constructor.
boolean	connected() Is the client currently connected?
void	delete(String remoteFile) Delete the specified remote file
String[]	dir() List current directory's contents as an array of strings of filenames.
String[]	dir(String dirname) List a directory's contents as an array of strings of filenames.
String[]	dir(String dirname, boolean full) List a directory's contents as an array of strings.
FTPFile[]	dirDetails(String dirname) List a directory's contents as an array of FTPFile objects.
boolean	exists(String remoteFile) Does the named file exist in the current server directory?
void	get(OutputStream destStream, String remoteFile) Get data from the FTP server.
byte[]	get(String remoteFile) Get data from the FTP server.
void	get(String localPath, String remoteFile) Get data from the FTP server.
boolean	getDetectTransferMode() Get the detect transfer mode
String	getId() Get the identifying string for this instance
long	getMonitorInterval() Get the bytes transferred between each callback on the progress monitor
String	getRemoteHost() Returns the IP address or name of the remote host.
int	getRemotePort() Returns the port being connected to on the remote server.
int	getTimeout() Get the TCP timeout on the underlying socket(s).
FTPTransferType	getType() Get the current transfer type
void	keepAlive() Tries to keep the current connection alive by some means, usually by sending an innocuous commmand.
void	mkdir(String dir) Create the specified remote working directory
Date	modtime(String remoteFile) Get modification time for a remote file.
String	put(byte[] bytes, String remoteFile) Put data onto the FTP server.
String	put(byte[] bytes, String remoteFile, boolean append) Put data onto the FTP server.
String	put(InputStream srcStream, String remoteFile) Put a stream of data onto the FTP server.
String	put(InputStream srcStream, String remoteFile, boolean append) Put a stream of data onto the FTP server.
String	put(String localPath, String remoteFile) Put a local file onto the FTP server.
String	put(String localPath, String remoteFile, boolean append) Put a local file onto the FTP server.
String	pwd() Get the current remote working directory
void	quit() Quit the FTP session
void	quitImmediately() Quit the FTP session immediately.
void	rename(String from, String to) Rename a file or directory
void	resume() Make the next file transfer (put or get) resume.
void	rmdir(String dir) Delete the specified remote working directory
void	setDetectTransferMode(boolean detectTransferMode) Set autodetect of filetypes on or off.
void	setId(String id) Set the identifying string for this instance
void	setProgressMonitor(FTPProgressMonitor monitor) Set a progress monitor for callbacks.
void	setProgressMonitor(FTPProgressMonitor monitor, long interval) Set a progress monitor for callbacks.
void	setRemoteHost(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	setTimeout(int millis) Set the TCP timeout on the underlying socket(s).
void	setType(FTPTransferType type) Set the transfer type
long	size(String remoteFile) Get the size of a remote file.

Method Detail

getId

String getId()

Get the identifying string for this instance

Returns:

identifying string

setId

void setId(String id)

Set the identifying string for this instance

Parameters:

id - identifying string

getRemoteHost

String getRemoteHost()

Returns the IP address or name of the remote host.

Returns:

Returns the remote host.

setRemoteHost

void setRemoteHost(String remoteHost)
                   throws IOException,
                          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.

Parameters:

remoteHost - The IP address or name of the remote host

Throws:

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

IOException

getRemotePort

int getRemotePort()

Returns the port being connected to on the remote server.

Returns:

Returns the port being connected to on the remote server.

setRemotePort

void setRemotePort(int remotePort)
                   throws FTPException

Set the port to connect to on the remote server. Can only do this if not already connected.

Parameters:

remotePort - The port to use.

Throws:

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

getTimeout

int getTimeout()

Get the TCP timeout on the underlying socket(s). A value of 0 (the default) means that there are no timeouts.

Returns:

timeout that is used, in milliseconds

setTimeout

void setTimeout(int millis)
                throws IOException,
                       FTPException

Set the TCP timeout on the underlying socket(s). Timeouts should be set before connections are made. If a timeout is set, then any operation which takes longer than the timeout value will be killed with a java.io.InterruptedException. The default is 0 meaning that the connection never times out.

Parameters:

millis - The length of the timeout, in milliseconds

Throws:

IOException

FTPException

setProgressMonitor

void setProgressMonitor(FTPProgressMonitor monitor,
                        long interval)

Set a progress monitor for callbacks. The bytes transferred in between callbacks is only indicative. In many cases, the data is read in chunks, and if the interval is set to be smaller than the chunk size, the callback will occur after after chunk transfer rather than the interval. Depending on the implementation, the chunk size can be as large as 64K.

Parameters:

monitor - the monitor object

interval - bytes transferred in between callbacks

setProgressMonitor

void setProgressMonitor(FTPProgressMonitor monitor)

Set a progress monitor for callbacks. Uses default callback interval

Parameters:

monitor - the monitor object

getMonitorInterval

long getMonitorInterval()

Get the bytes transferred between each callback on the progress monitor

Returns:

long bytes to be transferred before a callback

setDetectTransferMode

void setDetectTransferMode(boolean detectTransferMode)

Set autodetect 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

Parameters:

detectTransferMode - true if detecting transfer mode, false if not

getDetectTransferMode

boolean getDetectTransferMode()

Get the detect transfer mode

Returns:

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

connect

void connect()
             throws IOException,
                    FTPException

Connects to the server at the address and port number defined in the constructor.

Throws:

IOException - Thrown if there is a TCP/IP-related error.

FTPException - Thrown if there is an error related to the FTP protocol.

connected

boolean connected()

Is the client currently connected?

Returns:

true if connected, false otherwise

size

long size(String remoteFile)
          throws IOException,
                 FTPException

Get the size of a remote file. This is not a standard FTP command, it is defined in "Extensions to FTP", a draft RFC (draft-ietf-ftpext-mlst-16.txt)

Parameters:

remoteFile - name or path of remote file in current directory

Returns:

size of file in bytes

Throws:

IOException

FTPException

exists

boolean exists(String remoteFile)
               throws IOException,
                      FTPException

Does the named file exist in the current server directory?

Parameters:

remoteFile - name of remote file

Returns:

true if exists, false otherwise

Throws:

IOException

FTPException

getType

FTPTransferType getType()

Get the current transfer type

Returns:

the current type of the transfer, i.e. BINARY or ASCII

setType

void setType(FTPTransferType type)
             throws IOException,
                    FTPException

Set the transfer type

Parameters:

type - the transfer type to set the server to

Throws:

IOException

FTPException

resume

void resume()
            throws FTPException

Make the next file transfer (put or get) resume. For puts(), the bytes already transferred are skipped over, while for gets(), if writing to a file, it is opened in append mode, and only the bytes required are transferred. Currently resume is only supported for BINARY transfers (which is generally what it is most useful for).

Throws:

FTPException

cancelResume

void cancelResume()
                  throws IOException,
                         FTPException

Cancel the resume. Use this method if something goes wrong and the server is left in an inconsistent state

Throws:

IOException

FTPException

cancelTransfer

void cancelTransfer()

Cancels the current transfer. Generally called from a separate thread. Note that this may leave partially written files on the server or on local disk, and should not be used unless absolutely necessary. After the transfer is cancelled the connection may be in an inconsistent state, therefore it is best to quit and reconnect. It may cause exceptions to be thrown depending on the underlying protocol being used. Note that this can also be used to cancel directory listings, which can involve large amounts of data for directories containing many files.

put

String put(String localPath,
           String remoteFile)
           throws IOException,
                  FTPException

Put a local file onto the FTP server. It is placed in the current directory. If a remote file name is supplied, it is stored as that name on the server. If null is supplied, the server will generate a unique filename (via STOU) if it supports this option.

Parameters:

localPath - path of the local file

remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server

Returns:

The name of the remote file - normally the name supplied, or else the unique name generated by the server.

Throws:

IOException

FTPException

put

String put(InputStream srcStream,
           String remoteFile)
           throws IOException,
                  FTPException

Put a stream of data onto the FTP server. It is placed in the current directory. If a remote file name is supplied, it is stored as that name on the server. If null is supplied, the server will generate a unique filename (via STOU) if it supports this option.

Parameters:

srcStream - input stream of data to put

remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server

Returns:

The name of the remote file - normally the name supplied, or else the unique name generated by the server.

Throws:

IOException

FTPException

put

String put(InputStream srcStream,
           String remoteFile,
           boolean append)
           throws IOException,
                  FTPException

Put a stream of data onto the FTP server. It is placed in the current directory. If a remote file name is supplied, it is stored as that name on the server. If null is supplied, the server will generate a unique filename (via STOU) if it supports this option. Allows appending if current file exists.

Parameters:

srcStream - input stream of data to put

remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server

append - true if appending, false otherwise

Returns:

The name of the remote file - normally the name supplied, or else the unique name generated by the server.

Throws:

IOException

FTPException

put

String put(byte[] bytes,
           String remoteFile)
           throws IOException,
                  FTPException

Put data onto the FTP server. It is placed in the current directory. If a remote file name is supplied, it is stored as that name on the server. If null is supplied, the server will generate a unique filename (via STOU) if it supports this option.

Parameters:

bytes - array of bytes

remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server

Returns:

The name of the remote file - normally the name supplied, or else the unique name generated by the server.

Throws:

IOException

FTPException

put

String put(byte[] bytes,
           String remoteFile,
           boolean append)
           throws IOException,
                  FTPException

Put data onto the FTP server. It is placed in the current directory. If a remote file name is supplied, it is stored as that name on the server. If null is supplied, the server will generate a unique filename (via STOU) if it supports this option. Allows appending if current file exists.

Parameters:

bytes - array of bytes

remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server

append - true if appending, false otherwise

Returns:

The name of the remote file - normally the name supplied, or else the unique name generated by the server.

Throws:

IOException

FTPException

put

String put(String localPath,
           String remoteFile,
           boolean append)
           throws IOException,
                  FTPException

Put a local file onto the FTP server. It is placed in the current directory. If a remote file name is supplied, it is stored as that name on the server. If null is supplied, the server will generate a unique filename (via STOU) if it supports this option. Allows appending if current file exists.

Parameters:

localPath - path of the local file

remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server

append - true if appending, false otherwise

Returns:

The name of the remote file - normally the name supplied, or else the unique name generated by the server.

Throws:

IOException

FTPException

get

void get(String localPath,
         String remoteFile)
         throws IOException,
                FTPException

Get data from the FTP server. Uses the currently set transfer mode.

Parameters:

localPath - local file to put data in

remoteFile - name of remote file in current directory

Throws:

IOException

FTPException

get

void get(OutputStream destStream,
         String remoteFile)
         throws IOException,
                FTPException

Get data from the FTP server. Uses the currently set transfer mode.

Parameters:

destStream - data stream to write data to

remoteFile - name of remote file in current directory

Throws:

IOException

FTPException

get

byte[] get(String remoteFile)
           throws IOException,
                  FTPException

Get data from the FTP server. Transfers in whatever mode we are in. Retrieve as a byte array. Note that we may experience memory limitations as the entire file must be held in memory at one time.

Parameters:

remoteFile - name of remote file in current directory

Throws:

IOException

FTPException

dirDetails

FTPFile[] dirDetails(String dirname)
                     throws IOException,
                            FTPException,
                            ParseException

List a directory's contents as an array of FTPFile objects. Should work for Windows and most Unix FTP servers - let us know about unusual formats (http://www.enterprisedt.com/forums/index.php). If accurate timestamps are required (i.e. to the second), it is generally better to use @see #modtime(String).

Parameters:

dirname - name of directory (some servers permit a filemask)

Returns:

an array of FTPFile objects

Throws:

IOException

FTPException

ParseException

dir

String[] dir()
             throws IOException,
                    FTPException

List current directory's contents as an array of strings of filenames.

Returns:

an array of current directory listing strings

Throws:

IOException

FTPException

dir

String[] dir(String dirname)
             throws IOException,
                    FTPException

List a directory's contents as an array of strings of filenames.

Parameters:

dirname - name of directory OR filemask

Returns:

an array of directory listing strings

Throws:

IOException

FTPException

dir

String[] dir(String dirname,
             boolean full)
             throws IOException,
                    FTPException

List a directory's contents as an array of strings. A detailed listing is available, otherwise just filenames are provided. The detailed listing varies in details depending on OS and FTP server. Note that a full listing can be used on a file name to obtain information about a file

Parameters:

dirname - name of directory OR filemask

full - true if detailed listing required false otherwise

Returns:

an array of directory listing strings

Throws:

IOException

FTPException

delete

void delete(String remoteFile)
            throws IOException,
                   FTPException

Delete the specified remote file

Parameters:

remoteFile - name of remote file to delete

Throws:

IOException

FTPException

rename

void rename(String from,
            String to)
            throws IOException,
                   FTPException

Rename a file or directory

Parameters:

from - name of file or directory to rename

to - intended name

Throws:

IOException

FTPException

rmdir

void rmdir(String dir)
           throws IOException,
                  FTPException

Delete the specified remote working directory

Parameters:

dir - name of remote directory to delete

Throws:

IOException

FTPException

mkdir

void mkdir(String dir)
           throws IOException,
                  FTPException

Create the specified remote working directory

Parameters:

dir - name of remote directory to create

Throws:

IOException

FTPException

chdir

void chdir(String dir)
           throws IOException,
                  FTPException

Change the remote working directory to that supplied

Parameters:

dir - name of remote directory to change to

Throws:

IOException

FTPException

cdup

void cdup()
          throws IOException,
                 FTPException

Change the remote working directory to the parent directory

Throws:

IOException

FTPException

modtime

Date modtime(String remoteFile)
             throws IOException,
                    FTPException

Get modification time for a remote file. For accurate modification times (e.g. to the second) this method is to be preferred over @see #dirDetails(java.lang.String) which parses a listing returned by the server. The timezone is GMT.

Parameters:

remoteFile - name of remote file

Returns:

modification time of file as a date

Throws:

IOException

FTPException

pwd

String pwd()
           throws IOException,
                  FTPException

Get the current remote working directory

Returns:

the current working directory

Throws:

IOException

FTPException

keepAlive

void keepAlive()
               throws IOException,
                      FTPException

Tries to keep the current connection alive by some means, usually by sending an innocuous commmand.

Throws:

IOException

FTPException

quit

void quit()
          throws IOException,
                 FTPException

Quit the FTP session

Throws:

IOException

FTPException

quitImmediately

void quitImmediately()
                     throws IOException,
                            FTPException

Quit the FTP session immediately. If a transfer is underway it will be terminated.

Throws:

IOException

FTPException