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 {@link org.apache.commons.net.ftp.FTP#getReplyCode getReplyCode } aftera 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.BINARY_FILE_TYPE
. Because there are at least 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 {@link ToNetASCIIOutputStream NetASCII}filter streams 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 (or EPRT) 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 (or EPRT) 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 {@link #setRemoteVerificationEnabled 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 {@link org.apache.commons.net.ftp.FTPReply#SERVICE_NOT_AVAILABLE FTPReply.SERVICE_NOT_AVAILABLE }response to a command. When that occurs, the FTP class method encountering that reply will throw an {@link org.apache.commons.net.ftp.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 {@link org.apache.commons.net.ftp.FTPConnectionClosedException}, you must disconnect the connection with {@link #disconnect disconnect() } to properly clean up thesystem resources used by FTPClient. Before disconnecting, you may check the last reply code and text with {@link org.apache.commons.net.ftp.FTP#getReplyCode getReplyCode }, {@link org.apache.commons.net.ftp.FTP#getReplyString getReplyString }, and {@link org.apache.commons.net.ftp.FTP#getReplyStrings getReplyStrings}. You may avoid server disconnections while the client is idle by periodically 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 {@link org.apache.commons.net.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 = new 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 = new 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 = new 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. }
For examples of using FTPClient on servers whose directory listings
MM d yyyy
Control channel keep-alive feature:
During file transfers, the data connection is busy, but the control connection is idle. FTP servers know that the control connection is in use, so won't close it through lack of activity, but it's a lot harder for network routers to know that the control and data connections are associated with each other. Some routers may treat the control connection as idle, and disconnect it if the transfer over the data connection takes longer than the allowable idle time for the router.
One solution to this is to send a safe command (i.e. NOOP) over the control connection to reset the router's idle timer. This is enabled as follows:
ftpClient.setControlKeepAliveTimeout(300); // set timeout to 5 minutesThis will cause the file upload/download methods to send a NOOP approximately every 5 minutes.
The implementation currently uses a {@link CopyStreamListener} which is passed to the{@link Util#copyStream(InputStream,OutputStream,int,long,CopyStreamListener,boolean)}method, so the timing is partially dependent on how long each block transfer takes.
Note: this does not apply to the methods where the user is responsible for writing or reading the data stream, i.e. {@link #retrieveFileStream(String)} , {@link #storeFileStream(String)}and the other xxxFileStream methods
@see #FTP_SYSTEM_TYPE @see #SYSTEM_TYPE_PROPERTIES @see FTP @see FTPConnectionClosedException @see FTPFileEntryParser @see FTPFileEntryParserFactory @see DefaultFTPFileEntryParserFactory @see FTPClientConfig @see org.apache.commons.net.MalformedServerReplyException
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|