FTPClient

FTPClient encapsulates all the functionality necessary to store and retrieve files from an FTP server. This class takes care of all low level details of interacting with an FTP server and provides a convenient higher level interface. As with all classes derived from SocketClient , you must first connect to the server with connect before doing anything, and finally disconnect after you're completely finished interacting with the server. Then you need to check the FTP reply code to see if the connection was successful. For example:

    try {
      int reply;
      ftp.connect("ftp.foobar.com");
      System.out.println("Connected to " + server + ".");
      System.out.print(ftp.getReplyString());

      // After connection attempt, you should check the reply code to verify
      // success.
      reply = ftp.getReplyCode();

      if(!FTPReply.isPositiveCompletion(reply)) {
        ftp.disconnect();
        System.err.println("FTP server refused connection.");
        System.exit(1);
      }
    } catch(IOException e) {
      if(ftp.isConnected()) {
        try {
          ftp.disconnect();
        } catch(IOException f) {
          // do nothing
        }
      }
      System.err.println("Could not connect to server.");
      e.printStackTrace();
      System.exit(1);
    }

Immediately after connecting is the only real time you need to check the reply code (because connect is of type void). The convention for all the FTP command methods in FTPClient is such that they either return a boolean value or some other value. The boolean methods return true on a successful completion reply from the FTP server and false on a reply resulting in an error condition or failure. The methods returning a value other than boolean return a value containing the higher level data produced by the FTP command, or null if a reply resulted in an error condition or failure. If you want to access the exact FTP reply code causing a success or failure, you must call getReplyCode after a success or failure.

The default settings for FTPClient are for it to use FTP.ASCII_FILE_TYPE , FTP.NON_PRINT_TEXT_FORMAT , FTP.STREAM_TRANSFER_MODE , and FTP.FILE_STRUCTURE . The only file types directly supported are FTP.ASCII_FILE_TYPE and FTP.IMAGE_FILE_TYPE (which is the same as FTP.BINARY_FILE_TYPE ). Because there are at lest 4 different EBCDIC encodings, we have opted not to provide direct support for EBCDIC. To transfer EBCDIC and other unsupported file types you must create your own filter InputStreams and OutputStreams and wrap them around the streams returned or required by the FTPClient methods. FTPClient uses the NetASCII filter streams in org.apache.commons.net.io to provide transparent handling of ASCII files. We will consider incorporating EBCDIC support if there is enough demand.

FTP.NON_PRINT_TEXT_FORMAT , FTP.STREAM_TRANSFER_MODE , and FTP.FILE_STRUCTURE are the only supported formats, transfer modes, and file structures.

Because the handling of sockets on different platforms can differ significantly, the FTPClient automatically issues a new PORT command prior to every transfer requiring that the server connect to the client's data port. This ensures identical problem-free behavior on Windows, Unix, and Macintosh platforms. Additionally, it relieves programmers from having to issue the PORT command themselves and dealing with platform dependent issues.

Additionally, for security purposes, all data connections to the client are verified to ensure that they originated from the intended party (host and port). If a data connection is initiated by an unexpected party, the command will close the socket and throw an IOException. You may disable this behavior with setRemoteVerificationEnabled().

You should keep in mind that the FTP server may choose to prematurely close a connection if the client has been idle for longer than a given time period (usually 900 seconds). The FTPClient class will detect a premature FTP server connection closing when it receives a FTPReply.SERVICE_NOT_AVAILABLE response to a command. When that occurs, the FTP class method encountering that reply will throw an FTPConnectionClosedException . FTPConnectionClosedException is a subclass of IOException and therefore need not be caught separately, but if you are going to catch it separately, its catch block must appear before the more general IOException catch block. When you encounter an FTPConnectionClosedException , you must disconnect the connection with disconnect() to properly clean up the system resources used by FTPClient. Before disconnecting, you may check the last reply code and text with getReplyCode , getReplyString , and getReplyStrings. You may avoid server disconnections while the client is idle by periodicaly sending NOOP commands to the server.

Rather than list it separately for each method, we mention here that every method communicating with the server and throwing an IOException can also throw a MalformedServerReplyException , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the reply received from the server deviates enough from the protocol specification that it cannot be interpreted in a useful manner despite attempts to be as lenient as possible.

Listing API Examples Both paged and unpaged examples of directory listings are available, as follows:

Unpaged (whole list) access, using a parser accessible by auto-detect:

    FTPClient f=FTPClient();
    f.connect(server);
    f.login(username, password);
    FTPFile[] files = listFiles(directory);

Paged access, using a parser not accessible by auto-detect. The class defined in the first parameter of initateListParsing should be derived from org.apache.commons.net.FTPFileEntryParser:

    FTPClient f=FTPClient();
    f.connect(server);
    f.login(username, password);
    FTPListParseEngine engine =
       f.initiateListParsing("com.whatever.YourOwnParser", directory);

    while (engine.hasNext()) {
       FTPFile[] files = engine.getNext(25);  // "page size" you want
       //do whatever you want with these files, display them, etc.
       //expensive FTPFile objects not created until needed.
    }

Paged access, using a parser accessible by auto-detect:

    FTPClient f=FTPClient();
    f.connect(server);
    f.login(username, password);
    FTPListParseEngine engine = f.initiateListParsing(directory);

    while (engine.hasNext()) {
       FTPFile[] files = engine.getNext(25);  // "page size" you want
       //do whatever you want with these files, display them, etc.
       //expensive FTPFile objects not created until needed.
    }

* @author Daniel F. Savarese

static int	ACTIVE_LOCAL_DATA_CONNECTION_MODE A constant indicating the FTP session is expecting all transfers to occur between the client (local) and server and that the server should connect to the client's data port to initiate a data transfer.
static int	ACTIVE_REMOTE_DATA_CONNECTION_MODE A constant indicating the FTP session is expecting all transfers to occur between two remote servers and that the server the client is connected to should connect to the other server's data port to initiate a data transfer.
static int	PASSIVE_LOCAL_DATA_CONNECTION_MODE A constant indicating the FTP session is expecting all transfers to occur between the client (local) and server and that the server is in passive mode, requiring the client to connect to the server's data port to initiate a transfer.
static int	PASSIVE_REMOTE_DATA_CONNECTION_MODE A constant indicating the FTP session is expecting all transfers to occur between two remote servers and that the server the client is connected to is in passive mode, requiring the other server to connect to the first server's data port to initiate a data transfer.

void	_connectAction_()
Socket	_openDataConnection_(int command, String arg) Establishes a data connection with the FTP server, returning a Socket for the connection if successful.
boolean	abort() Abort a transfer in progress.
boolean	allocate(int bytes) Reserve a number of bytes on the server for the next file transfer.
boolean	allocate(int bytes, int recordSize) Reserve space on the server for the next file transfer.
boolean	appendFile(String remote, InputStream local) Appends to a file on the server with the given name, taking input from the given InputStream.
OutputStream	appendFileStream(String remote) Returns an OutputStream through which data can be written to append to a file on the server with the given name.
boolean	changeToParentDirectory() Change to the parent directory of the current working directory.
boolean	changeWorkingDirectory(String pathname) Change the current working directory of the FTP session.
boolean	completePendingCommand() There are a few FTPClient methods that do not complete the entire sequence of FTP commands to complete a transaction.
FTPFileList	createFileList(FTPFileEntryParser parser) Using a programmer specified FTPFileEntryParser , initialize an object containing a raw file information for the current working directory.
FTPFileList	createFileList(String pathname, FTPFileEntryParser parser) Using a programmer specified FTPFileEntryParser , initialize an object containing a raw file information for a directory or information for a single file.
boolean	deleteFile(String pathname) Deletes a file on the FTP server.
void	disconnect() Closes the connection to the FTP server and restores connection parameters to the default values.
void	enterLocalActiveMode() Set the current data connection mode to ACTIVE_LOCAL_DATA_CONNECTION_MODE.
void	enterLocalPassiveMode() Set the current data connection mode to PASSIVE_LOCAL_DATA_CONNECTION_MODE .
boolean	enterRemoteActiveMode(InetAddress host, int port) Set the current data connection mode to ACTIVE_REMOTE_DATA_CONNECTION .
boolean	enterRemotePassiveMode() Set the current data connection mode to PASSIVE_REMOTE_DATA_CONNECTION_MODE .
int	getDataConnectionMode() Returns the current data connection mode (one of the _DATA_CONNECTION_MODE constants.
String	getPassiveHost() Returns the hostname or IP address (in the form of a string) returned by the server when entering passive mode.
int	getPassivePort() If in passive mode, returns the data port of the passive host.
long	getRestartOffset() Fetches the restart offset.
String	getStatus() Issue the FTP STAT command to the server.
String	getStatus(String pathname) Issue the FTP STAT command to the server for a given pathname.
String	getSystemName() Fetches the system type name from the server and returns the string.
FTPListParseEngine	initiateListParsing() Using the default autodetect mechanism, initialize an FTPListParseEngine object containing a raw file information for the current working directory on the server This information is obtained through the LIST command.
FTPListParseEngine	initiateListParsing(String pathname) Using the default autodetect mechanism, initialize an FTPListParseEngine object containing a raw file information for the supplied directory.
FTPListParseEngine	initiateListParsing(String parserKey, String pathname) Using the supplied parser key, initialize an FTPListParseEngine object containing a raw file information for the supplied directory.
boolean	isRemoteVerificationEnabled() Return whether or not verification of the remote host participating in data connections is enabled.
FTPFile[]	listFiles(String parserKey, String pathname) Using the supplied parserKey, obtain a list of file information for the current working directory or for just a single file.
FTPFile[]	listFiles(String pathname) Using the default system autodetect mechanism, obtain a list of file information for the current working directory or for just a single file.
FTPFile[]	listFiles() Using the default system autodetect mechanism, obtain a list of file information for the current working directory.
FTPFile[]	listFiles(FTPFileListParser parser, String pathname) Using a programmer specified FTPFileListParser , obtain a list of file information for a directory or information for just a single file.
FTPFile[]	listFiles(FTPFileListParser parser) Using a programmer specified FTPFileListParser , obtain a list of file information for the current working directory.
String	listHelp() Fetches the system help information from the server and returns the full string.
String	listHelp(String command) Fetches the help information for a given command from the server and returns the full string.
String[]	listNames(String pathname) Obtain a list of filenames in a directory (or just the name of a given file, which is not particularly useful).
String[]	listNames() Obtain a list of filenames in the current working directory This information is obtained through the NLST command.
boolean	login(String username, String password) Login to the FTP server using the provided username and password.
boolean	login(String username, String password, String account) Login to the FTP server using the provided username, password, and account.
boolean	logout() Logout of the FTP server by sending the QUIT command.
boolean	makeDirectory(String pathname) Creates a new subdirectory on the FTP server in the current directory (if a relative pathname is given) or where specified (if an absolute pathname is given).
String	printWorkingDirectory() Returns the pathname of the current working directory.
boolean	remoteAppend(String filename) Initiate a server to server file transfer.
boolean	remoteRetrieve(String filename) Initiate a server to server file transfer.
boolean	remoteStore(String filename) Initiate a server to server file transfer.
boolean	remoteStoreUnique(String filename) Initiate a server to server file transfer.
boolean	remoteStoreUnique() Initiate a server to server file transfer.
boolean	removeDirectory(String pathname) Removes a directory on the FTP server (if empty).
boolean	rename(String from, String to) Renames a remote file.
boolean	retrieveFile(String remote, OutputStream local) Retrieves a named file from the server and writes it to the given OutputStream.
InputStream	retrieveFileStream(String remote) Returns an InputStream from which a named file from the server can be read.
boolean	sendNoOp() Sends a NOOP command to the FTP server.
boolean	sendSiteCommand(String arguments) Send a site specific command.
void	setDataTimeout(int timeout) Sets the timeout in milliseconds to use when reading from the data connection.
boolean	setFileStructure(int structure) Sets the file structure.
boolean	setFileTransferMode(int mode) Sets the transfer mode.
boolean	setFileType(int fileType) Sets the file type to be transferred.
boolean	setFileType(int fileType, int formatOrByteSize) Sets the file type to be transferred and the format.
void	setParserFactory(FTPFileEntryParserFactory parserFactory) set the factory used for parser creation to the supplied factory object.
void	setRemoteVerificationEnabled(boolean enable) Enable or disable verification that the remote host taking part of a data connection is the same as the host to which the control connection is attached.
void	setRestartOffset(long offset) Sets the restart offset.
boolean	storeFile(String remote, InputStream local) Stores a file on the server using the given name and taking input from the given InputStream.
OutputStream	storeFileStream(String remote) Returns an OutputStream through which data can be written to store a file on the server using the given name.
boolean	storeUniqueFile(String remote, InputStream local) Stores a file on the server using a unique name derived from the given name and taking input from the given InputStream.
boolean	storeUniqueFile(InputStream local) Stores a file on the server using a unique name assigned by the server and taking input from the given InputStream.
OutputStream	storeUniqueFileStream(String remote) Returns an OutputStream through which data can be written to store a file on the server using a unique name derived from the given name.
OutputStream	storeUniqueFileStream() Returns an OutputStream through which data can be written to store a file on the server using a unique name assigned by the server.
boolean	structureMount(String pathname) Issue the FTP SMNT command.

Class FTPClient

Field Summary

Constructor Summary

Method Summary

Field Details

ACTIVE_LOCAL_DATA_CONNECTION_MODE

ACTIVE_REMOTE_DATA_CONNECTION_MODE

PASSIVE_LOCAL_DATA_CONNECTION_MODE

PASSIVE_REMOTE_DATA_CONNECTION_MODE

Constructor Details

FTPClient

Method Details

_connectAction_

_openDataConnection_

abort

allocate

allocate

appendFile

appendFileStream

changeToParentDirectory

changeWorkingDirectory

completePendingCommand

createFileList

createFileList

deleteFile

disconnect

enterLocalActiveMode

enterLocalPassiveMode

enterRemoteActiveMode

enterRemotePassiveMode

getDataConnectionMode

getPassiveHost

getPassivePort

getRestartOffset

getStatus

getStatus

getSystemName

initiateListParsing

initiateListParsing

initiateListParsing

isRemoteVerificationEnabled

listFiles

listFiles

listFiles

listFiles

listFiles

listHelp

listHelp

listNames

listNames

login

login

logout

makeDirectory

printWorkingDirectory

remoteAppend

remoteRetrieve

remoteStore

remoteStoreUnique

remoteStoreUnique

removeDirectory

rename

retrieveFile

retrieveFileStream

sendNoOp

sendSiteCommand

setDataTimeout

setFileStructure

setFileTransferMode

setFileType

setFileType

setParserFactory

setRemoteVerificationEnabled

setRestartOffset

storeFile

storeFileStream

storeUniqueFile

storeUniqueFile

storeUniqueFileStream

storeUniqueFileStream