edtFTPj/Free - Open-source FTP library for Java | Download


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.28 $
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(java.lang.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(java.lang.String remoteFile)
          Delete the specified remote file
 java.lang.String[] dir()
          List current directory's contents as an array of strings of filenames.
 java.lang.String[] dir(java.lang.String dirname)
          List a directory's contents as an array of strings of filenames.
 java.lang.String[] dir(java.lang.String dirname, boolean full)
          List a directory's contents as an array of strings.
 FTPFile[] dirDetails(java.lang.String dirname)
          List a directory's contents as an array of FTPFile objects.
 void dirDetails(java.lang.String dirname, DirectoryListCallback lister)
          List a directory's contents via a callback.
 java.lang.String executeCommand(java.lang.String command)
          Request that the remote server execute the literal command supplied.
 boolean exists(java.lang.String remoteFile)
          Does the named file exist in the current server directory?
 void get(java.io.OutputStream destStream, java.lang.String remoteFile)
          Get data from the FTP server.
 byte[] get(java.lang.String remoteFile)
          Get data from the FTP server.
 void get(java.lang.String localPath, java.lang.String remoteFile)
          Get data from the FTP server.
 int getDeleteCount()
          Get the number of files deleted since the count was reset
 boolean getDetectTransferMode()
          Get the detect transfer mode
 int getDownloadCount()
          Get the number of files downloaded since the count was reset
 boolean getFileLockingEnabled()
          Determine if file locking on local downloaded files is being used or not.
 java.lang.String getId()
          Get the identifying string for this instance
 long getMonitorInterval()
          Get the bytes transferred between each callback on the progress monitor
 int getNetworkBufferSize()
          Get the size of the network buffers (SO_SNDBUF and SO_RCVBUF).
 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.
 int getTimeout()
          Get the timeout used for sockets and other resources
 FTPTransferType getType()
          Get the current transfer type
 int getUploadCount()
          Get the number of files uploaded since the count was reset
 void keepAlive()
          Tries to keep the current connection alive by some means, usually by sending an innocuous commmand.
 void mkdir(java.lang.String dir)
          Create the specified remote working directory
 java.util.Date modtime(java.lang.String remoteFile)
          Get modification time for a remote file.
 java.lang.String put(byte[] bytes, java.lang.String remoteFile)
          Put data onto the FTP server.
 java.lang.String put(byte[] bytes, java.lang.String remoteFile, boolean append)
          Put data onto the FTP server.
 java.lang.String put(java.io.InputStream srcStream, java.lang.String remoteFile)
          Put a stream of data onto the FTP server.
 java.lang.String put(java.io.InputStream srcStream, java.lang.String remoteFile, boolean append)
          Put a stream of data onto the FTP server.
 java.lang.String put(java.lang.String localPath, java.lang.String remoteFile)
          Put a local file onto the FTP server.
 java.lang.String put(java.lang.String localPath, java.lang.String remoteFile, boolean append)
          Put a local file onto the FTP server.
 java.lang.String pwd()
          Get the current remote working directory
 void quit()
          Quit the FTP session
 void quitImmediately()
          Quit the FTP session immediately.
 void rename(java.lang.String from, java.lang.String to)
          Rename a file or directory
 void resetDeleteCount()
          Reset the count of deleted files to zero.
 void resetDownloadCount()
          Reset the count of downloaded files to zero.
 void resetUploadCount()
          Reset the count of uploaded files to zero.
 void resume()
          Make the next file transfer (put or get) resume.
 void resumeNextDownload(long offset)
          Make the next download resume at a specific point.
 void rmdir(java.lang.String dir)
          Delete the specified remote working directory
 void setControlEncoding(java.lang.String controlEncoding)
          Set the encoding used on the control channel.
 void setDetectTransferMode(boolean detectTransferMode)
          Set autodetect of filetypes on or off.
 void setFileLockingEnabled(boolean lockingEnabled)
          Set file locking to enabled or disabled.
 void setId(java.lang.String id)
          Set the identifying string for this instance
 void setModTime(java.lang.String path, java.util.Date modTime)
          Set the last modified time (UTC) for the supplied file.
 void setNetworkBufferSize(int networkBufferSize)
          Set the size of the network buffers (SO_SNDBUF and SO_RCVBUF).
 void setProgressMonitor(FTPProgressMonitor monitor)
          Set a progress monitor for callbacks.
 void setProgressMonitor(FTPProgressMonitor monitor, long interval)
          Set a progress monitor for callbacks.
 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 setTimeout(int millis)
          Set the timeout on the underlying sockets and other resources that may be used.
 void setType(FTPTransferType type)
          Set the transfer type
 long size(java.lang.String remoteFile)
          Get the size of a remote file.
 java.lang.String system()
          Get a string representing the remote system
 

Method Detail

getId

java.lang.String getId()
Get the identifying string for this instance

Returns:
identifying string

setId

void setId(java.lang.String id)
Set the identifying string for this instance

Parameters:
id - identifying string

getRemoteHost

java.lang.String getRemoteHost()
Returns the IP address or name of the remote host.

Returns:
Returns the remote host.

setRemoteHost

void setRemoteHost(java.lang.String remoteHost)
                   throws java.io.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.
java.io.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 timeout used for sockets and other resources

Returns:
timeout that is used, in milliseconds

setTimeout

void setTimeout(int millis)
                throws java.io.IOException,
                       FTPException
Set the timeout on the underlying sockets and other resources that may be used. A timeout of 0 should not be used - for an infinite timeout use a large number. 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 result in an IOException being thrown. The default is 60,000 (60 seconds).

Parameters:
millis - The length of the timeout, in milliseconds
Throws:
java.io.IOException
FTPException

getNetworkBufferSize

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

Returns:
network buffer size

setNetworkBufferSize

void setNetworkBufferSize(int networkBufferSize)
Set the size of the network buffers (SO_SNDBUF and SO_RCVBUF).

Parameters:
networkBufferSize - new buffer size to set

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

setFileLockingEnabled

void setFileLockingEnabled(boolean lockingEnabled)
Set file locking to enabled or disabled. When downloading files, by default the local file is locked for exclusive writing to prevent other processes corrupting it. Sometimes this needs to be disabled, e.g. tryLock() fails on NFS drives in versions of Java prior to 7.

Parameters:
lockingEnabled - true to enable locking, false to disable

getFileLockingEnabled

boolean getFileLockingEnabled()
Determine if file locking on local downloaded files is being used or not. Default is true.

Returns:
true if file locking is enabled, false otherwise

setControlEncoding

void setControlEncoding(java.lang.String controlEncoding)
                        throws FTPException
Set the encoding used on the control channel. Can only do this if not connected

Parameters:
controlEncoding - The controlEncoding to set, which is the name of a Charset
Throws:
FTPException
See Also:
Charset

connect

void connect()
             throws java.io.IOException,
                    FTPException
Connects to the server at the address and port number defined in the constructor.

Throws:
java.io.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(java.lang.String remoteFile)
          throws java.io.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:
java.io.IOException
FTPException

exists

boolean exists(java.lang.String remoteFile)
               throws java.io.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:
java.io.IOException
FTPException

executeCommand

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.

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

Parameters:
command - command string
Returns:
result string by server
Throws:
FTPException
java.io.IOException

system

java.lang.String system()
                        throws FTPException,
                               java.io.IOException
Get a string representing the remote system

Returns:
system string
Throws:
FTPException
java.io.IOException

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 java.io.IOException,
                    FTPException
Set the transfer type

Parameters:
type - the transfer type to set the server to
Throws:
java.io.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

resumeNextDownload

void resumeNextDownload(long offset)
                        throws FTPException
Make the next download resume at a specific point. This resume method allows the resume offset to be set explicitly for downloads. Offset bytes are skipped before downloading the file. This means you can download only the last few bytes of the file rather than the whole file, irrespective of the size of the local file. Currently resume is only supported for BINARY transfers (which is generally what it is most useful for).

Throws:
FTPException

cancelResume

void cancelResume()
                  throws java.io.IOException,
                         FTPException
Cancel the resume. Use this method if something goes wrong and the server is left in an inconsistent state

Throws:
java.io.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

java.lang.String put(java.lang.String localPath,
                     java.lang.String remoteFile)
                     throws java.io.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:
java.io.IOException
FTPException

put

java.lang.String put(java.io.InputStream srcStream,
                     java.lang.String remoteFile)
                     throws java.io.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:
java.io.IOException
FTPException

put

java.lang.String put(java.io.InputStream srcStream,
                     java.lang.String remoteFile,
                     boolean append)
                     throws java.io.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:
java.io.IOException
FTPException

put

java.lang.String put(byte[] bytes,
                     java.lang.String remoteFile)
                     throws java.io.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:
java.io.IOException
FTPException

put

java.lang.String put(byte[] bytes,
                     java.lang.String remoteFile,
                     boolean append)
                     throws java.io.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:
java.io.IOException
FTPException

put

java.lang.String put(java.lang.String localPath,
                     java.lang.String remoteFile,
                     boolean append)
                     throws java.io.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:
java.io.IOException
FTPException

get

void get(java.lang.String localPath,
         java.lang.String remoteFile)
         throws java.io.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:
java.io.IOException
FTPException

get

void get(java.io.OutputStream destStream,
         java.lang.String remoteFile)
         throws java.io.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:
java.io.IOException
FTPException

get

byte[] get(java.lang.String remoteFile)
           throws java.io.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:
java.io.IOException
FTPException

getDownloadCount

int getDownloadCount()
Get the number of files downloaded since the count was reset

Returns:
download file count

resetDownloadCount

void resetDownloadCount()
Reset the count of downloaded files to zero.


getUploadCount

int getUploadCount()
Get the number of files uploaded since the count was reset

Returns:
upload file count

resetUploadCount

void resetUploadCount()
Reset the count of uploaded files to zero.


getDeleteCount

int getDeleteCount()
Get the number of files deleted since the count was reset

Returns:
deleted file count

resetDeleteCount

void resetDeleteCount()
Reset the count of deleted files to zero.


dirDetails

void dirDetails(java.lang.String dirname,
                DirectoryListCallback lister)
                throws java.io.IOException,
                       FTPException,
                       java.text.ParseException
List a directory's contents via a callback. The callback is notified for each directory entry, meaning they can be processed individually. It also avoids out of memory problems if the directory is huge, and an array of thousands of FTPFile objects would otherwise be returned.

Parameters:
dirname - name of directory (some servers permit a filemask)
lister - callback to be notified of errors
Throws:
java.io.IOException
FTPException
java.text.ParseException

dirDetails

FTPFile[] dirDetails(java.lang.String dirname)
                     throws java.io.IOException,
                            FTPException,
                            java.text.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:
java.io.IOException
FTPException
java.text.ParseException

dir

java.lang.String[] dir()
                       throws java.io.IOException,
                              FTPException
List current directory's contents as an array of strings of filenames.

Returns:
an array of current directory listing strings
Throws:
java.io.IOException
FTPException

dir

java.lang.String[] dir(java.lang.String dirname)
                       throws java.io.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:
java.io.IOException
FTPException

dir

java.lang.String[] dir(java.lang.String dirname,
                       boolean full)
                       throws java.io.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:
java.io.IOException
FTPException

delete

void delete(java.lang.String remoteFile)
            throws java.io.IOException,
                   FTPException
Delete the specified remote file

Parameters:
remoteFile - name of remote file to delete
Throws:
java.io.IOException
FTPException

rename

void rename(java.lang.String from,
            java.lang.String to)
            throws java.io.IOException,
                   FTPException
Rename a file or directory

Parameters:
from - name of file or directory to rename
to - intended name
Throws:
java.io.IOException
FTPException

rmdir

void rmdir(java.lang.String dir)
           throws java.io.IOException,
                  FTPException
Delete the specified remote working directory

Parameters:
dir - name of remote directory to delete
Throws:
java.io.IOException
FTPException

mkdir

void mkdir(java.lang.String dir)
           throws java.io.IOException,
                  FTPException
Create the specified remote working directory

Parameters:
dir - name of remote directory to create
Throws:
java.io.IOException
FTPException

chdir

void chdir(java.lang.String dir)
           throws java.io.IOException,
                  FTPException
Change the remote working directory to that supplied

Parameters:
dir - name of remote directory to change to
Throws:
java.io.IOException
FTPException

cdup

void cdup()
          throws java.io.IOException,
                 FTPException
Change the remote working directory to the parent directory

Throws:
java.io.IOException
FTPException

modtime

java.util.Date modtime(java.lang.String remoteFile)
                       throws java.io.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 time zone is UTC.

Parameters:
remoteFile - name of remote file
Throws:
java.io.IOException
FTPException

setModTime

void setModTime(java.lang.String path,
                java.util.Date modTime)
                throws java.io.IOException,
                       FTPException
Set the last modified time (UTC) for the supplied file. This is not supported by all servers.

Parameters:
path - the path to the file/directory on the remote server
modTime - the time stamp to set the modified time to in UTC
Throws:
java.io.IOException
FTPException

pwd

java.lang.String pwd()
                     throws java.io.IOException,
                            FTPException
Get the current remote working directory

Returns:
the current working directory
Throws:
java.io.IOException
FTPException

keepAlive

void keepAlive()
               throws java.io.IOException,
                      FTPException
Tries to keep the current connection alive by some means, usually by sending an innocuous commmand.

Throws:
java.io.IOException
FTPException

quit

void quit()
          throws java.io.IOException,
                 FTPException
Quit the FTP session

Throws:
java.io.IOException
FTPException

quitImmediately

void quitImmediately()
                     throws java.io.IOException,
                            FTPException
Quit the FTP session immediately. If a transfer is underway it will be terminated.

Throws:
java.io.IOException
FTPException


Copyright (c) 2001-2007 Enterprise Distributed Technologies Ltd. All Rights Reserved.