org.apache.commons.net.ftp
Class FTPClient

java.lang.Object
  extended by org.apache.commons.net.SocketClient
      extended by org.apache.commons.net.ftp.FTP
          extended by org.apache.commons.net.ftp.FTPClient
All Implemented Interfaces:
Configurable
Direct Known Subclasses:
FTPHTTPClient, FTPSClient

public class FTPClient
extends FTP
implements Configurable

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:

    FTPClient ftp = new FTPClient();
    FTPClientConfig config = new FTPClientConfig();
    config.setXXX(YYY); // change required options
    ftp.configure(config );
    boolean error = false;
    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);
      }
      ... // transfer files
      ftp.logout();
    } catch(IOException e) {
      error = true;
      e.printStackTrace();
    } finally {
      if(ftp.isConnected()) {
        try {
          ftp.disconnect();
        } catch(IOException ioe) {
          // do nothing
        }
      }
      System.exit(error ? 1 : 0);
    }
 

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.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 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 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 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 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 = f.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

see FTPClientConfig.

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 minutes
 
This will cause the file upload/download methods to send a NOOP approximately every 5 minutes.

The implementation currently uses a CopyStreamListener which is passed to the 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. retrieveFileStream(String) , storeFileStream(String) and the other xxxFileStream methods

See Also:
FTP_SYSTEM_TYPE, SYSTEM_TYPE_PROPERTIES, FTP, FTPConnectionClosedException, FTPFileEntryParser, FTPFileEntryParserFactory, DefaultFTPFileEntryParserFactory, FTPClientConfig, MalformedServerReplyException

Field Summary
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 String FTP_SYSTEM_TYPE
          The system property ("org.apache.commons.net.ftp.systemType") which can be used to override the system type.
If defined, the value will be used to create any automatically created parsers.
static String FTP_SYSTEM_TYPE_DEFAULT
          The system property ("org.apache.commons.net.ftp.systemType.default") which can be used as the default system type.
If defined, the value will be used if the SYST command fails.
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.
static String SYSTEM_TYPE_PROPERTIES
          The name of an optional systemType properties file ("/systemType.properties"), which is loaded using Class.getResourceAsStream(String).
The entries are the systemType (as determined by getSystemType()) and the values are the replacement type or parserClass, which is passed to FTPFileEntryParserFactory.createFileEntryParser(String).
For example:
 
Fields inherited from class org.apache.commons.net.ftp.FTP
_commandSupport_, _controlEncoding, _controlInput_, _controlOutput_, _newReplyString, _replyCode, _replyLines, _replyString, ASCII_FILE_TYPE, BINARY_FILE_TYPE, BLOCK_TRANSFER_MODE, CARRIAGE_CONTROL_TEXT_FORMAT, COMPRESSED_TRANSFER_MODE, DEFAULT_CONTROL_ENCODING, DEFAULT_DATA_PORT, DEFAULT_PORT, EBCDIC_FILE_TYPE, FILE_STRUCTURE, LOCAL_FILE_TYPE, NON_PRINT_TEXT_FORMAT, PAGE_STRUCTURE, RECORD_STRUCTURE, REPLY_CODE_LEN, STREAM_TRANSFER_MODE, strictMultilineParsing, TELNET_TEXT_FORMAT
 
Fields inherited from class org.apache.commons.net.SocketClient
_defaultPort_, _input_, _output_, _serverSocketFactory_, _socket_, _socketFactory_, _timeout_, connectTimeout, NETASCII_EOL
 
Constructor Summary
FTPClient()
          Default FTPClient constructor.
 
Method Summary
protected  void _connectAction_()
          Initiates control connections and gets initial reply.
protected  Socket _openDataConnection_(int command, String arg)
          Establishes a data connection with the FTP server, returning a Socket for the connection if successful.
protected  Socket _openDataConnection_(String command, String arg)
          Establishes a data connection with the FTP server, returning a Socket for the connection if successful.
protected  void _parseExtendedPassiveModeReply(String reply)
           
protected  void _parsePassiveModeReply(String reply)
           
protected  boolean _retrieveFile(String command, String remote, OutputStream local)
           
protected  InputStream _retrieveFileStream(String command, String remote)
           
protected  boolean _storeFile(String command, String remote, InputStream local)
           
protected  OutputStream _storeFileStream(String command, String remote)
           
 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.
 void configure(FTPClientConfig config)
          Implementation of the Configurable interface.
 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.
 boolean doCommand(String command, String params)
          Issue a command and wait for the reply.
 String[] doCommandAsStrings(String command, String params)
          Issue a command and wait for the reply, returning it as an array of strings.
 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 .
 boolean features()
          Query the server for supported features.
 String featureValue(String feature)
          Query the server for a supported feature, and returns the its value (if any).
 String[] featureValues(String feature)
          Query the server for a supported feature, and returns its values (if any).
 boolean getAutodetectUTF8()
          Tells if automatic server encoding detection is enabled or disabled.
 int getBufferSize()
          Retrieve the current internal buffer size for data sockets.
 int getControlKeepAliveReplyTimeout()
          Get how long to wait for control keep-alive message replies.
 long getControlKeepAliveTimeout()
          Get the time to wait between sending control connection keepalive messages.
 CopyStreamListener getCopyStreamListener()
          Obtain the currently active listener.
 int getDataConnectionMode()
          Returns the current data connection mode (one of the _DATA_CONNECTION_MODE constants.
protected  String getListArguments(String pathname)
           
 boolean getListHiddenFiles()
           
 String getModificationTime(String pathname)
          Issue the FTP MDTM command (not supported by all servers to retrieve the last modification time of a file.
 String getPassiveHost()
          Returns the hostname or IP address (in the form of a string) returned by the server when entering passive mode.
 InetAddress getPassiveLocalIPAddress()
          Set the local IP address in 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()
          Deprecated. use getSystemType() instead
 String getSystemType()
          Fetches the system type from the server and returns the string.
 boolean hasFeature(String feature)
          Query the server for a supported feature.
 boolean hasFeature(String feature, String value)
          Query the server for a supported feature with particular value, for example "AUTH SSL" or "AUTH TLS".
 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.
 boolean isUseEPSVwithIPv4()
          Whether should attempt to use EPSV with IPv4.
 FTPFile[] listDirectories()
          Using the default system autodetect mechanism, obtain a list of directories contained in the current working directory.
 FTPFile[] listDirectories(String parent)
          Using the default system autodetect mechanism, obtain a list of directories contained in the specified directory.
 FTPFile[] listFiles()
          Using the default system autodetect mechanism, obtain a list of file information for the current working directory.
 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(String pathname, FTPFileFilter filter)
          Version of listFiles(String) which allows a filter to be provided.
 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()
          Obtain a list of filenames in the current working directory This information is obtained through the NLST command.
 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).
 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).
 FTPFile[] mlistDir()
          Generate a directory listing for the current directory using the MLSD command.
 FTPFile[] mlistDir(String pathname)
          Generate a directory listing using the MLSD command.
 FTPFile[] mlistDir(String pathname, FTPFileFilter filter)
          Generate a directory listing using the MLSD command.
 FTPFile mlistFile(String pathname)
          Get file details using the MLST command
 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()
          Initiate a server to server file transfer.
 boolean remoteStoreUnique(String filename)
          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.
protected  boolean restart(long offset)
          Restart a STREAM_TRANSFER_MODE file transfer starting from the given offset.
 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 setActiveExternalIPAddress(String ipAddress)
          Set the external IP address in active mode.
 void setActivePortRange(int minPort, int maxPort)
          Set the client side port range in active mode.
 void setAutodetectUTF8(boolean autodetect)
          Enables or disables automatic server encoding detection (only UTF-8 supported).
 void setBufferSize(int bufSize)
          Set the internal buffer size for data sockets.
 void setControlKeepAliveReplyTimeout(int timeout)
          Set how long to wait for control keep-alive message replies.
 void setControlKeepAliveTimeout(long controlIdle)
          Set the time to wait between sending control connection keepalive messages when processing file upload or download.
 void setCopyStreamListener(CopyStreamListener listener)
          Set the listener to be used when performing store/retrieve operations.
 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 setListHiddenFiles(boolean listHiddenFiles)
          You can set this to true if you would like to get hidden files when listFiles(java.lang.String) too.
 boolean setModificationTime(String pathname, String timeval)
          Issue the FTP MFMT command (not supported by all servers) which sets the last modified time of a file.
 void setParserFactory(FTPFileEntryParserFactory parserFactory)
          set the factory used for parser creation to the supplied factory object.
 void setPassiveLocalIPAddress(InetAddress inetAddress)
          Set the local IP address to use in passive mode.
 void setPassiveLocalIPAddress(String ipAddress)
          Set the local IP address to use in passive mode.
 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 setReportActiveExternalIPAddress(String ipAddress)
          Set the external IP address to report in EPRT/PORT commands in active mode.
 void setRestartOffset(long offset)
          Sets the restart offset for file transfers.
 void setUseEPSVwithIPv4(boolean selected)
          Set whether to use EPSV with IPv4.
 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(InputStream local)
          Stores a file on the server using a unique name assigned by the server and taking input from the given InputStream.
 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.
 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.
 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.
 boolean structureMount(String pathname)
          Issue the FTP SMNT command.
 
Methods inherited from class org.apache.commons.net.ftp.FTP
__getReplyNoReport, __noop, abor, acct, allo, allo, appe, cdup, cwd, dele, eprt, epsv, feat, getCommandSupport, getControlEncoding, getReply, getReplyCode, getReplyString, getReplyStrings, help, help, isStrictMultilineParsing, list, list, mdtm, mfmt, mkd, mlsd, mlsd, mlst, mlst, mode, nlst, nlst, noop, pass, pasv, port, pwd, quit, rein, rest, retr, rmd, rnfr, rnto, sendCommand, sendCommand, sendCommand, sendCommand, setControlEncoding, setStrictMultilineParsing, site, smnt, stat, stat, stor, stou, stou, stru, syst, type, type, user
 
Methods inherited from class org.apache.commons.net.SocketClient
addProtocolCommandListener, connect, connect, connect, connect, connect, connect, createCommandSupport, fireCommandSent, fireReplyReceived, getConnectTimeout, getDefaultPort, getDefaultTimeout, getKeepAlive, getLocalAddress, getLocalPort, getProxy, getReceiveBufferSize, getRemoteAddress, getRemotePort, getSendBufferSize, getServerSocketFactory, getSoLinger, getSoTimeout, getTcpNoDelay, isAvailable, isConnected, removeProtocolCommandListener, setConnectTimeout, setDefaultPort, setDefaultTimeout, setKeepAlive, setProxy, setReceiveBufferSize, setSendBufferSize, setServerSocketFactory, setSocketFactory, setSoLinger, setSoTimeout, setTcpNoDelay, verifyRemote
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FTP_SYSTEM_TYPE

public static final String FTP_SYSTEM_TYPE
The system property ("org.apache.commons.net.ftp.systemType") which can be used to override the system type.
If defined, the value will be used to create any automatically created parsers.

Since:
3.0
See Also:
Constant Field Values

FTP_SYSTEM_TYPE_DEFAULT

public static final String FTP_SYSTEM_TYPE_DEFAULT
The system property ("org.apache.commons.net.ftp.systemType.default") which can be used as the default system type.
If defined, the value will be used if the SYST command fails.

Since:
3.1
See Also:
Constant Field Values

SYSTEM_TYPE_PROPERTIES

public static final String SYSTEM_TYPE_PROPERTIES
The name of an optional systemType properties file ("/systemType.properties"), which is loaded using Class.getResourceAsStream(String).
The entries are the systemType (as determined by getSystemType()) and the values are the replacement type or parserClass, which is passed to FTPFileEntryParserFactory.createFileEntryParser(String).
For example:
 Plan 9=Unix
 OS410=org.apache.commons.net.ftp.parser.OS400FTPEntryParser
 

Since:
3.0
See Also:
Constant Field Values

ACTIVE_LOCAL_DATA_CONNECTION_MODE

public static final 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. This is the default data connection mode when and FTPClient instance is created.

See Also:
Constant Field Values

ACTIVE_REMOTE_DATA_CONNECTION_MODE

public static final 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.

See Also:
Constant Field Values

PASSIVE_LOCAL_DATA_CONNECTION_MODE

public static final 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.

See Also:
Constant Field Values

PASSIVE_REMOTE_DATA_CONNECTION_MODE

public static final 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.

See Also:
Constant Field Values
Constructor Detail

FTPClient

public FTPClient()
Default FTPClient constructor. Creates a new FTPClient instance with the data connection mode set to ACTIVE_LOCAL_DATA_CONNECTION_MODE , the file type set to FTP.ASCII_FILE_TYPE , the file format set to FTP.NON_PRINT_TEXT_FORMAT , the file structure set to FTP.FILE_STRUCTURE , and the transfer mode set to FTP.STREAM_TRANSFER_MODE .

The list parsing auto-detect feature can be configured to use lenient future dates (short dates may be up to one day in the future) as follows:

 FTPClient ftp = new FTPClient();
 FTPClientConfig config = new FTPClientConfig();
 config.setLenientFutureDates(true);
 ftp.configure(config );
 

Method Detail

_parsePassiveModeReply

protected void _parsePassiveModeReply(String reply)
                               throws MalformedServerReplyException
Throws:
MalformedServerReplyException
Since:
3.1

_parseExtendedPassiveModeReply

protected void _parseExtendedPassiveModeReply(String reply)
                                       throws MalformedServerReplyException
Throws:
MalformedServerReplyException

_storeFile

protected boolean _storeFile(String command,
                             String remote,
                             InputStream local)
                      throws IOException
Throws:
IOException
Since:
3.1

_storeFileStream

protected OutputStream _storeFileStream(String command,
                                        String remote)
                                 throws IOException
Throws:
IOException
Since:
3.1

_openDataConnection_

protected Socket _openDataConnection_(int command,
                                      String arg)
                               throws IOException
Establishes a data connection with the FTP server, returning a Socket for the connection if successful. If a restart offset has been set with setRestartOffset(long), a REST command is issued to the server with the offset as an argument before establishing the data connection. Active mode connections also cause a local PORT command to be issued.

Parameters:
command - The int representation of the FTP command to send.
arg - The arguments to the FTP command. If this parameter is set to null, then the command is sent with no argument.
Returns:
A Socket corresponding to the established data connection. Null is returned if an FTP protocol error is reported at any point during the establishment and initialization of the connection.
Throws:
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

_openDataConnection_

protected Socket _openDataConnection_(String command,
                                      String arg)
                               throws IOException
Establishes a data connection with the FTP server, returning a Socket for the connection if successful. If a restart offset has been set with setRestartOffset(long), a REST command is issued to the server with the offset as an argument before establishing the data connection. Active mode connections also cause a local PORT command to be issued.

Parameters:
command - The text representation of the FTP command to send.
arg - The arguments to the FTP command. If this parameter is set to null, then the command is sent with no argument.
Returns:
A Socket corresponding to the established data connection. Null is returned if an FTP protocol error is reported at any point during the establishment and initialization of the connection.
Throws:
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Since:
3.1

_connectAction_

protected void _connectAction_()
                        throws IOException
Description copied from class: FTP
Initiates control connections and gets initial reply. Initializes FTP._controlInput_ and FTP._controlOutput_.

Overrides:
_connectAction_ in class FTP
Throws:
IOException

setDataTimeout

public void setDataTimeout(int timeout)
Sets the timeout in milliseconds to use when reading from the data connection. This timeout will be set immediately after opening the data connection, provided that the value is ≥ 0.

Note: the timeout will also be applied when calling accept() whilst establishing an active local data connection.

Parameters:
timeout - The default timeout in milliseconds that is used when opening a data connection socket. The value 0 means an infinite timeout.

setParserFactory

public void setParserFactory(FTPFileEntryParserFactory parserFactory)
set the factory used for parser creation to the supplied factory object.

Parameters:
parserFactory - factory object used to create FTPFileEntryParsers
See Also:
FTPFileEntryParserFactory, DefaultFTPFileEntryParserFactory

disconnect

public void disconnect()
                throws IOException
Closes the connection to the FTP server and restores connection parameters to the default values.

Overrides:
disconnect in class FTP
Throws:
IOException - If an error occurs while disconnecting.

setRemoteVerificationEnabled

public 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. The default is for verification to be enabled. You may set this value at any time, whether the FTPClient is currently connected or not.

Parameters:
enable - True to enable verification, false to disable verification.

isRemoteVerificationEnabled

public boolean isRemoteVerificationEnabled()
Return whether or not verification of the remote host participating in data connections is enabled. The default behavior is for verification to be enabled.

Returns:
True if verification is enabled, false if not.

login

public boolean login(String username,
                     String password)
              throws IOException
Login to the FTP server using the provided username and password.

Parameters:
username - The username to login under.
password - The password to use.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

login

public boolean login(String username,
                     String password,
                     String account)
              throws IOException
Login to the FTP server using the provided username, password, and account. If no account is required by the server, only the username and password, the account information is not used.

Parameters:
username - The username to login under.
password - The password to use.
account - The account to use.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

logout

public boolean logout()
               throws IOException
Logout of the FTP server by sending the QUIT command.

Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

changeWorkingDirectory

public boolean changeWorkingDirectory(String pathname)
                               throws IOException
Change the current working directory of the FTP session.

Parameters:
pathname - The new current working directory.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

changeToParentDirectory

public boolean changeToParentDirectory()
                                throws IOException
Change to the parent directory of the current working directory.

Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

structureMount

public boolean structureMount(String pathname)
                       throws IOException
Issue the FTP SMNT command.

Parameters:
pathname - The pathname to mount.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

enterLocalActiveMode

public void enterLocalActiveMode()
Set the current data connection mode to ACTIVE_LOCAL_DATA_CONNECTION_MODE. No communication with the FTP server is conducted, but this causes all future data transfers to require the FTP server to connect to the client's data port. Additionally, to accommodate differences between socket implementations on different platforms, this method causes the client to issue a PORT command before every data transfer.


enterLocalPassiveMode

public void enterLocalPassiveMode()
Set the current data connection mode to PASSIVE_LOCAL_DATA_CONNECTION_MODE . Use this method only for data transfers between the client and server. This method causes a PASV (or EPSV) command to be issued to the server before the opening of every data connection, telling the server to open a data port to which the client will connect to conduct data transfers. The FTPClient will stay in PASSIVE_LOCAL_DATA_CONNECTION_MODE until the mode is changed by calling some other method such as enterLocalActiveMode()

N.B. currently calling any connect method will reset the mode to ACTIVE_LOCAL_DATA_CONNECTION_MODE.


enterRemoteActiveMode

public boolean enterRemoteActiveMode(InetAddress host,
                                     int port)
                              throws IOException
Set the current data connection mode to ACTIVE_REMOTE_DATA_CONNECTION . Use this method only for server to server data transfers. This method issues a PORT command to the server, indicating the other server and port to which it should connect for data transfers. You must call this method before EVERY server to server transfer attempt. The FTPClient will NOT automatically continue to issue PORT commands. You also must remember to call enterLocalActiveMode() if you wish to return to the normal data connection mode.

Parameters:
host - The passive mode server accepting connections for data transfers.
port - The passive mode server's data port.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

enterRemotePassiveMode

public boolean enterRemotePassiveMode()
                               throws IOException
Set the current data connection mode to PASSIVE_REMOTE_DATA_CONNECTION_MODE . Use this method only for server to server data transfers. This method issues a PASV command to the server, telling it to open a data port to which the active server will connect to conduct data transfers. You must call this method before EVERY server to server transfer attempt. The FTPClient will NOT automatically continue to issue PASV commands. You also must remember to call enterLocalActiveMode() if you wish to return to the normal data connection mode.

Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

getPassiveHost

public String getPassiveHost()
Returns the hostname or IP address (in the form of a string) returned by the server when entering passive mode. If not in passive mode, returns null. This method only returns a valid value AFTER a data connection has been opened after a call to enterLocalPassiveMode(). This is because FTPClient sends a PASV command to the server only just before opening a data connection, and not when you call enterLocalPassiveMode().

Returns:
The passive host name if in passive mode, otherwise null.

getPassivePort

public int getPassivePort()
If in passive mode, returns the data port of the passive host. This method only returns a valid value AFTER a data connection has been opened after a call to enterLocalPassiveMode(). This is because FTPClient sends a PASV command to the server only just before opening a data connection, and not when you call enterLocalPassiveMode().

Returns:
The data port of the passive server. If not in passive mode, undefined.

getDataConnectionMode

public int getDataConnectionMode()
Returns the current data connection mode (one of the _DATA_CONNECTION_MODE constants.

Returns:
The current data connection mode (one of the _DATA_CONNECTION_MODE constants.

setActivePortRange

public void setActivePortRange(int minPort,
                               int maxPort)
Set the client side port range in active mode.

Parameters:
minPort - The lowest available port (inclusive).
maxPort - The highest available port (inclusive).
Since:
2.2

setActiveExternalIPAddress

public void setActiveExternalIPAddress(String ipAddress)
                                throws UnknownHostException
Set the external IP address in active mode. Useful when there are multiple network cards.

Parameters:
ipAddress - The external IP address of this machine.
Throws:
UnknownHostException - if the ipAddress cannot be resolved
Since:
2.2

setPassiveLocalIPAddress

public void setPassiveLocalIPAddress(String ipAddress)
                              throws UnknownHostException
Set the local IP address to use in passive mode. Useful when there are multiple network cards.

Parameters:
ipAddress - The local IP address of this machine.
Throws:
UnknownHostException - if the ipAddress cannot be resolved

setPassiveLocalIPAddress

public void setPassiveLocalIPAddress(InetAddress inetAddress)
Set the local IP address to use in passive mode. Useful when there are multiple network cards.

Parameters:
inetAddress - The local IP address of this machine.

getPassiveLocalIPAddress

public InetAddress getPassiveLocalIPAddress()
Set the local IP address in passive mode. Useful when there are multiple network cards.

Returns:
The local IP address in passive mode.

setReportActiveExternalIPAddress

public void setReportActiveExternalIPAddress(String ipAddress)
                                      throws UnknownHostException
Set the external IP address to report in EPRT/PORT commands in active mode. Useful when there are multiple network cards.

Parameters:
ipAddress - The external IP address of this machine.
Throws:
UnknownHostException - if the ipAddress cannot be resolved
Since:
3.1
See Also:
getReportHostAddress()

setFileType

public boolean setFileType(int fileType)
                    throws IOException
Sets the file type to be transferred. This should be one of FTP.ASCII_FILE_TYPE , FTP.BINARY_FILE_TYPE, etc. The file type only needs to be set when you want to change the type. After changing it, the new type stays in effect until you change it again. The default file type is FTP.ASCII_FILE_TYPE if this method is never called.

N.B. currently calling any connect method will reset the mode to ACTIVE_LOCAL_DATA_CONNECTION_MODE.

Parameters:
fileType - The _FILE_TYPE constant indcating the type of file.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

setFileType

public boolean setFileType(int fileType,
                           int formatOrByteSize)
                    throws IOException
Sets the file type to be transferred and the format. The type should be one of FTP.ASCII_FILE_TYPE , FTP.BINARY_FILE_TYPE , etc. The file type only needs to be set when you want to change the type. After changing it, the new type stays in effect until you change it again. The default file type is FTP.ASCII_FILE_TYPE if this method is never called. The format should be one of the FTP class TEXT_FORMAT constants, or if the type is FTP.LOCAL_FILE_TYPE , the format should be the byte size for that type. The default format is FTP.NON_PRINT_TEXT_FORMAT if this method is never called.

N.B. currently calling any connect method will reset the mode to ACTIVE_LOCAL_DATA_CONNECTION_MODE.

Parameters:
fileType - The _FILE_TYPE constant indcating the type of file.
formatOrByteSize - The format of the file (one of the _FORMAT constants. In the case of LOCAL_FILE_TYPE, the byte size.

Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

setFileStructure

public boolean setFileStructure(int structure)
                         throws IOException
Sets the file structure. The default structure is FTP.FILE_STRUCTURE if this method is never called.

Parameters:
structure - The structure of the file (one of the FTP class _STRUCTURE constants).
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

setFileTransferMode

public boolean setFileTransferMode(int mode)
                            throws IOException
Sets the transfer mode. The default transfer mode FTP.STREAM_TRANSFER_MODE if this method is never called.

Parameters:
mode - The new transfer mode to use (one of the FTP class _TRANSFER_MODE constants).
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

remoteRetrieve

public boolean remoteRetrieve(String filename)
                       throws IOException
Initiate a server to server file transfer. This method tells the server to which the client is connected to retrieve a given file from the other server.

Parameters:
filename - The name of the file to retrieve.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

remoteStore

public boolean remoteStore(String filename)
                    throws IOException
Initiate a server to server file transfer. This method tells the server to which the client is connected to store a file on the other server using the given filename. The other server must have had a remoteRetrieve issued to it by another FTPClient.

Parameters:
filename - The name to call the file that is to be stored.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

remoteStoreUnique

public boolean remoteStoreUnique(String filename)
                          throws IOException
Initiate a server to server file transfer. This method tells the server to which the client is connected to store a file on the other server using a unique filename based on the given filename. The other server must have had a remoteRetrieve issued to it by another FTPClient.

Parameters:
filename - The name on which to base the filename of the file that is to be stored.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

remoteStoreUnique

public boolean remoteStoreUnique()
                          throws IOException
Initiate a server to server file transfer. This method tells the server to which the client is connected to store a file on the other server using a unique filename. The other server must have had a remoteRetrieve issued to it by another FTPClient. Many FTP servers require that a base filename be given from which the unique filename can be derived. For those servers use the other version of remoteStoreUnique

Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

remoteAppend

public boolean remoteAppend(String filename)
                     throws IOException
Initiate a server to server file transfer. This method tells the server to which the client is connected to append to a given file on the other server. The other server must have had a remoteRetrieve issued to it by another FTPClient.

Parameters:
filename - The name of the file to be appended to, or if the file does not exist, the name to call the file being stored.

Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

completePendingCommand

public boolean completePendingCommand()
                               throws IOException
There are a few FTPClient methods that do not complete the entire sequence of FTP commands to complete a transaction. These commands require some action by the programmer after the reception of a positive intermediate command. After the programmer's code completes its actions, it must call this method to receive the completion reply from the server and verify the success of the entire transaction.

For example,

 InputStream input;
 OutputStream output;
 input  = new FileInputStream("foobaz.txt");
 output = ftp.storeFileStream("foobar.txt")
 if(!FTPReply.isPositiveIntermediate(ftp.getReplyCode())) {
     input.close();
     output.close();
     ftp.logout();
     ftp.disconnect();
     System.err.println("File transfer failed.");
     System.exit(1);
 }
 Util.copyStream(input, output);
 input.close();
 output.close();
 // Must call completePendingCommand() to finish command.
 if(!ftp.completePendingCommand()) {
     ftp.logout();
     ftp.disconnect();
     System.err.println("File transfer failed.");
     System.exit(1);
 }
 

Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

retrieveFile

public boolean retrieveFile(String remote,
                            OutputStream local)
                     throws IOException
Retrieves a named file from the server and writes it to the given OutputStream. This method does NOT close the given OutputStream. If the current file type is ASCII, line separators in the file are converted to the local representation.

Note: if you have used setRestartOffset(long), the file data will start from the selected offset.

Parameters:
remote - The name of the remote file.
local - The local OutputStream to which to write the file.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
CopyStreamException - If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to determine the number of bytes transferred and the IOException causing the error. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

_retrieveFile

protected boolean _retrieveFile(String command,
                                String remote,
                                OutputStream local)
                         throws IOException
Throws:
IOException
Since:
3.1

retrieveFileStream

public InputStream retrieveFileStream(String remote)
                               throws IOException
Returns an InputStream from which a named file from the server can be read. If the current file type is ASCII, the returned InputStream will convert line separators in the file to the local representation. You must close the InputStream when you finish reading from it. The InputStream itself will take care of closing the parent data connection socket upon being closed. To finalize the file transfer you must call completePendingCommand and check its return value to verify success.

Note: if you have used setRestartOffset(long), the file data will start from the selected offset.

Parameters:
remote - The name of the remote file.
Returns:
An InputStream from which the remote file can be read. If the data connection cannot be opened (e.g., the file does not exist), null is returned (in which case you may check the reply code to determine the exact reason for failure).
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

_retrieveFileStream

protected InputStream _retrieveFileStream(String command,
                                          String remote)
                                   throws IOException
Throws:
IOException
Since:
3.1

storeFile

public boolean storeFile(String remote,
                         InputStream local)
                  throws IOException
Stores a file on the server using the given name and taking input from the given InputStream. This method does NOT close the given InputStream. If the current file type is ASCII, line separators in the file are transparently converted to the NETASCII format (i.e., you should not attempt to create a special InputStream to do this).

Parameters:
remote - The name to give the remote file.
local - The local InputStream from which to read the file.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
CopyStreamException - If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to determine the number of bytes transferred and the IOException causing the error. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

storeFileStream

public OutputStream storeFileStream(String remote)
                             throws IOException
Returns an OutputStream through which data can be written to store a file on the server using the given name. If the current file type is ASCII, the returned OutputStream will convert line separators in the file to the NETASCII format (i.e., you should not attempt to create a special OutputStream to do this). You must close the OutputStream when you finish writing to it. The OutputStream itself will take care of closing the parent data connection socket upon being closed. To finalize the file transfer you must call completePendingCommand and check its return value to verify success.

Parameters:
remote - The name to give the remote file.
Returns:
An OutputStream through which the remote file can be written. If the data connection cannot be opened (e.g., the file does not exist), null is returned (in which case you may check the reply code to determine the exact reason for failure).
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

appendFile

public boolean appendFile(String remote,
                          InputStream local)
                   throws IOException
Appends to a file on the server with the given name, taking input from the given InputStream. This method does NOT close the given InputStream. If the current file type is ASCII, line separators in the file are transparently converted to the NETASCII format (i.e., you should not attempt to create a special InputStream to do this).

Parameters:
remote - The name of the remote file.
local - The local InputStream from which to read the data to be appended to the remote file.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
CopyStreamException - If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to determine the number of bytes transferred and the IOException causing the error. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

appendFileStream

public OutputStream appendFileStream(String remote)
                              throws IOException
Returns an OutputStream through which data can be written to append to a file on the server with the given name. If the current file type is ASCII, the returned OutputStream will convert line separators in the file to the NETASCII format (i.e., you should not attempt to create a special OutputStream to do this). You must close the OutputStream when you finish writing to it. The OutputStream itself will take care of closing the parent data connection socket upon being closed. To finalize the file transfer you must call completePendingCommand and check its return value to verify success.

Parameters:
remote - The name of the remote file.
Returns:
An OutputStream through which the remote file can be appended. If the data connection cannot be opened (e.g., the file does not exist), null is returned (in which case you may check the reply code to determine the exact reason for failure).
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

storeUniqueFile

public boolean storeUniqueFile(String remote,
                               InputStream local)
                        throws IOException
Stores a file on the server using a unique name derived from the given name and taking input from the given InputStream. This method does NOT close the given InputStream. If the current file type is ASCII, line separators in the file are transparently converted to the NETASCII format (i.e., you should not attempt to create a special InputStream to do this).

Parameters:
remote - The name on which to base the unique name given to the remote file.
local - The local InputStream from which to read the file.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
CopyStreamException - If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to determine the number of bytes transferred and the IOException causing the error. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

storeUniqueFileStream

public OutputStream storeUniqueFileStream(String remote)
                                   throws IOException
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. If the current file type is ASCII, the returned OutputStream will convert line separators in the file to the NETASCII format (i.e., you should not attempt to create a special OutputStream to do this). You must close the OutputStream when you finish writing to it. The OutputStream itself will take care of closing the parent data connection socket upon being closed. To finalize the file transfer you must call completePendingCommand and check its return value to verify success.

Parameters:
remote - The name on which to base the unique name given to the remote file.
Returns:
An OutputStream through which the remote file can be written. If the data connection cannot be opened (e.g., the file does not exist), null is returned (in which case you may check the reply code to determine the exact reason for failure).
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

storeUniqueFile

public boolean storeUniqueFile(InputStream local)
                        throws IOException
Stores a file on the server using a unique name assigned by the server and taking input from the given InputStream. This method does NOT close the given InputStream. If the current file type is ASCII, line separators in the file are transparently converted to the NETASCII format (i.e., you should not attempt to create a special InputStream to do this).

Parameters:
local - The local InputStream from which to read the file.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
CopyStreamException - If an I/O error occurs while actually transferring the file. The CopyStreamException allows you to determine the number of bytes transferred and the IOException causing the error. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

storeUniqueFileStream

public OutputStream storeUniqueFileStream()
                                   throws IOException
Returns an OutputStream through which data can be written to store a file on the server using a unique name assigned by the server. If the current file type is ASCII, the returned OutputStream will convert line separators in the file to the NETASCII format (i.e., you should not attempt to create a special OutputStream to do this). You must close the OutputStream when you finish writing to it. The OutputStream itself will take care of closing the parent data connection socket upon being closed. To finalize the file transfer you must call completePendingCommand and check its return value to verify success.

Returns:
An OutputStream through which the remote file can be written. If the data connection cannot be opened (e.g., the file does not exist), null is returned (in which case you may check the reply code to determine the exact reason for failure).
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

allocate

public boolean allocate(int bytes)
                 throws IOException
Reserve a number of bytes on the server for the next file transfer.

Parameters:
bytes - The number of bytes which the server should allocate.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

features

public boolean features()
                 throws IOException
Query the server for supported features. The server may reply with a list of server-supported exensions. For example, a typical client-server interaction might be (from RFC 2389):
        C> feat
        S> 211-Extensions supported:
        S>  MLST size*;create;modify*;perm;media-type
        S>  SIZE
        S>  COMPRESSION
        S>  MDTM
        S> 211 END
 

Returns:
True if successfully completed, false if not.
Throws:
IOException
Since:
2.2
See Also:
http://www.faqs.org/rfcs/rfc2389.html

featureValues

public String[] featureValues(String feature)
                       throws IOException
Query the server for a supported feature, and returns its values (if any). Caches the parsed response to avoid resending the command repeatedly.

Returns:
if the feature is present, returns the feature values (empty array if none) Returns null if the feature is not found or the command failed. Check FTP.getReplyCode() or FTP.getReplyString() if so.
Throws:
IOException
Since:
3.0

featureValue

public String featureValue(String feature)
                    throws IOException
Query the server for a supported feature, and returns the its value (if any). Caches the parsed response to avoid resending the command repeatedly.

Returns:
if the feature is present, returns the feature value or the empty string if the feature exists but has no value. Returns null if the feature is not found or the command failed. Check FTP.getReplyCode() or FTP.getReplyString() if so.
Throws:
IOException
Since:
3.0

hasFeature

public boolean hasFeature(String feature)
                   throws IOException
Query the server for a supported feature. Caches the parsed response to avoid resending the command repeatedly.

Parameters:
feature - the name of the feature; it is converted to upper case.
Returns:
true if the feature is present, false if the feature is not present or the FTP.feat() command failed. Check FTP.getReplyCode() or FTP.getReplyString() if it is necessary to distinguish these cases.
Throws:
IOException
Since:
3.0

hasFeature

public boolean hasFeature(String feature,
                          String value)
                   throws IOException
Query the server for a supported feature with particular value, for example "AUTH SSL" or "AUTH TLS". Caches the parsed response to avoid resending the command repeatedly.

Parameters:
feature - the name of the feature; it is converted to upper case.
value - the value to find.
Returns:
true if the feature is present, false if the feature is not present or the FTP.feat() command failed. Check FTP.getReplyCode() or FTP.getReplyString() if it is necessary to distinguish these cases.
Throws:
IOException
Since:
3.0

allocate

public boolean allocate(int bytes,
                        int recordSize)
                 throws IOException
Reserve space on the server for the next file transfer.

Parameters:
bytes - The number of bytes which the server should allocate.
recordSize - The size of a file record.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

doCommand

public boolean doCommand(String command,
                         String params)
                  throws IOException
Issue a command and wait for the reply.

Should only be used with commands that return replies on the command channel - do not use for LIST, NLST, MLSD etc.

Parameters:
command - The command to invoke
params - The parameters string, may be null
Returns:
True if successfully completed, false if not, in which case call FTP.getReplyCode() or FTP.getReplyString() to get the reason.
Throws:
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Since:
3.0

doCommandAsStrings

public String[] doCommandAsStrings(String command,
                                   String params)
                            throws IOException
Issue a command and wait for the reply, returning it as an array of strings.

Should only be used with commands that return replies on the command channel - do not use for LIST, NLST, MLSD etc.

Parameters:
command - The command to invoke
params - The parameters string, may be null
Returns:
The array of replies, or null if the command failed, in which case call FTP.getReplyCode() or FTP.getReplyString() to get the reason.
Throws:
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Since:
3.0

mlistFile

public FTPFile mlistFile(String pathname)
                  throws IOException
Get file details using the MLST command

Parameters:
pathname - the file or directory to list, may be null
Returns:
the file details, may be null
Throws:
IOException
Since:
3.0

mlistDir

public FTPFile[] mlistDir()
                   throws IOException
Generate a directory listing for the current directory using the MLSD command.

Returns:
the array of file entries
Throws:
IOException
Since:
3.0

mlistDir

public FTPFile[] mlistDir(String pathname)
                   throws IOException
Generate a directory listing using the MLSD command.

Parameters:
pathname - the directory name, may be null
Returns:
the array of file entries
Throws:
IOException
Since:
3.0

mlistDir

public FTPFile[] mlistDir(String pathname,
                          FTPFileFilter filter)
                   throws IOException
Generate a directory listing using the MLSD command.

Parameters:
pathname - the directory name, may be null
filter - the filter to apply to the responses
Returns:
the array of file entries
Throws:
IOException
Since:
3.0

restart

protected boolean restart(long offset)
                   throws IOException
Restart a STREAM_TRANSFER_MODE file transfer starting from the given offset. This will only work on FTP servers supporting the REST comand for the stream transfer mode. However, most FTP servers support this. Any subsequent file transfer will start reading or writing the remote file from the indicated offset.

Parameters:
offset - The offset into the remote file at which to start the next file transfer.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Since:
3.1 (changed from private to protected)

setRestartOffset

public void setRestartOffset(long offset)
Sets the restart offset for file transfers.

The restart command is not sent to the server immediately. It is sent when a data connection is created as part of a subsequent command. The restart marker is reset to zero after use.

Note: This method should only be invoked immediately prior to the transfer to which it applies.

Parameters:
offset - The offset into the remote file at which to start the next file transfer. This must be a value greater than or equal to zero.

getRestartOffset

public long getRestartOffset()
Fetches the restart offset.

Returns:
offset The offset into the remote file at which to start the next file transfer.

rename

public boolean rename(String from,
                      String to)
               throws IOException
Renames a remote file.

Parameters:
from - The name of the remote file to rename.
to - The new name of the remote file.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

abort

public boolean abort()
              throws IOException
Abort a transfer in progress.

Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

deleteFile

public boolean deleteFile(String pathname)
                   throws IOException
Deletes a file on the FTP server.

Parameters:
pathname - The pathname of the file to be deleted.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

removeDirectory

public boolean removeDirectory(String pathname)
                        throws IOException
Removes a directory on the FTP server (if empty).

Parameters:
pathname - The pathname of the directory to remove.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

makeDirectory

public boolean makeDirectory(String pathname)
                      throws IOException
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).

Parameters:
pathname - The pathname of the directory to create.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

printWorkingDirectory

public String printWorkingDirectory()
                             throws IOException
Returns the pathname of the current working directory.

Returns:
The pathname of the current working directory. If it cannot be obtained, returns null.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

sendSiteCommand

public boolean sendSiteCommand(String arguments)
                        throws IOException
Send a site specific command.

Parameters:
arguments - The site specific command and arguments.
Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

getSystemType

public String getSystemType()
                     throws IOException
Fetches the system type from the server and returns the string. This value is cached for the duration of the connection after the first call to this method. In other words, only the first time that you invoke this method will it issue a SYST command to the FTP server. FTPClient will remember the value and return the cached value until a call to disconnect.

If the SYST command fails, and the system property FTP_SYSTEM_TYPE_DEFAULT is defined, then this is used instead.

Returns:
The system type obtained from the server. Never null.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server (and the default system type property is not defined)
Since:
2.2

listHelp

public String listHelp()
                throws IOException
Fetches the system help information from the server and returns the full string.

Returns:
The system help string obtained from the server. null if the information could not be obtained.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

listHelp

public String listHelp(String command)
                throws IOException
Fetches the help information for a given command from the server and returns the full string.

Parameters:
command - The command on which to ask for help.
Returns:
The command help string obtained from the server. null if the information could not be obtained.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

sendNoOp

public boolean sendNoOp()
                 throws IOException
Sends a NOOP command to the FTP server. This is useful for preventing server timeouts.

Returns:
True if successfully completed, false if not.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

listNames

public String[] listNames(String pathname)
                   throws IOException
Obtain a list of filenames in a directory (or just the name of a given file, which is not particularly useful). This information is obtained through the NLST command. If the given pathname is a directory and contains no files, a zero length array is returned only if the FTP server returned a positive completion code, otherwise null is returned (the FTP server returned a 550 error No files found.). If the directory is not empty, an array of filenames in the directory is returned. If the pathname corresponds to a file, only that file will be listed. The server may or may not expand glob expressions.

Parameters:
pathname - The file or directory to list. Warning: the server may treat a leading '-' as an option introducer. If so, try using an absolute path, or prefix the path with ./ (unix style servers). Some servers may support "--" as meaning end of options, in which case "-- -xyz" should work.
Returns:
The list of filenames contained in the given path. null if the list could not be obtained. If there are no filenames in the directory, a zero-length array is returned.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

listNames

public String[] listNames()
                   throws IOException
Obtain a list of filenames in the current working directory This information is obtained through the NLST command. If the current directory contains no files, a zero length array is returned only if the FTP server returned a positive completion code, otherwise, null is returned (the FTP server returned a 550 error No files found.). If the directory is not empty, an array of filenames in the directory is returned.

Returns:
The list of filenames contained in the current working directory. null if the list could not be obtained. If there are no filenames in the directory, a zero-length array is returned.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

listFiles

public FTPFile[] listFiles(String pathname)
                    throws IOException
Using the default system autodetect mechanism, obtain a list of file information for the current working directory or for just a single file.

This information is obtained through the LIST command. The contents of the returned array is determined by the FTPFileEntryParser used.

Parameters:
pathname - The file or directory to list. Since the server may or may not expand glob expressions, using them here is not recommended and may well cause this method to fail. Also, some servers treat a leading '-' as being an option. To avoid this interpretation, use an absolute pathname or prefix the pathname with ./ (unix style servers). Some servers may support "--" as meaning end of options, in which case "-- -xyz" should work.
Returns:
The list of file information contained in the given path in the format determined by the autodetection mechanism
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
ParserInitializationException - Thrown if the parserKey parameter cannot be resolved by the selected parser factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is neither the fully qualified class name of a class implementing the interface org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the recognized keys mapping to such a parser or if class loader security issues prevent its being loaded.
See Also:
DefaultFTPFileEntryParserFactory, FTPFileEntryParserFactory, FTPFileEntryParser

listFiles

public FTPFile[] listFiles()
                    throws IOException
Using the default system autodetect mechanism, obtain a list of file information for the current working directory.

This information is obtained through the LIST command. The contents of the returned array is determined by the FTPFileEntryParser used.

Returns:
The list of file information contained in the current directory in the format determined by the autodetection mechanism.

NOTE: This array may contain null members if any of the individual file listings failed to parse. The caller should check each entry for null before referencing it.

Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
ParserInitializationException - Thrown if the parserKey parameter cannot be resolved by the selected parser factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is neither the fully qualified class name of a class implementing the interface org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the recognized keys mapping to such a parser or if class loader security issues prevent its being loaded.
See Also:
DefaultFTPFileEntryParserFactory, FTPFileEntryParserFactory, FTPFileEntryParser

listFiles

public FTPFile[] listFiles(String pathname,
                           FTPFileFilter filter)
                    throws IOException
Version of listFiles(String) which allows a filter to be provided. For example: listFiles("site", FTPFileFilters.DIRECTORY);

Parameters:
pathname - the initial path, may be null
filter - the filter, non-null
Returns:
the list of FTPFile entries.
Throws:
IOException
Since:
2.2

listDirectories

public FTPFile[] listDirectories()
                          throws IOException
Using the default system autodetect mechanism, obtain a list of directories contained in the current working directory.

This information is obtained through the LIST command. The contents of the returned array is determined by the FTPFileEntryParser used.

Returns:
The list of directories contained in the current directory in the format determined by the autodetection mechanism.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
ParserInitializationException - Thrown if the parserKey parameter cannot be resolved by the selected parser factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is neither the fully qualified class name of a class implementing the interface org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the recognized keys mapping to such a parser or if class loader security issues prevent its being loaded.
Since:
3.0
See Also:
DefaultFTPFileEntryParserFactory, FTPFileEntryParserFactory, FTPFileEntryParser

listDirectories

public FTPFile[] listDirectories(String parent)
                          throws IOException
Using the default system autodetect mechanism, obtain a list of directories contained in the specified directory.

This information is obtained through the LIST command. The contents of the returned array is determined by the FTPFileEntryParser used.

Returns:
The list of directories contained in the specified directory in the format determined by the autodetection mechanism.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
ParserInitializationException - Thrown if the parserKey parameter cannot be resolved by the selected parser factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is neither the fully qualified class name of a class implementing the interface org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the recognized keys mapping to such a parser or if class loader security issues prevent its being loaded.
Since:
3.0
See Also:
DefaultFTPFileEntryParserFactory, FTPFileEntryParserFactory, FTPFileEntryParser

initiateListParsing

public FTPListParseEngine initiateListParsing()
                                       throws IOException
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. This object is then capable of being iterated to return a sequence of FTPFile objects with information filled in by the FTPFileEntryParser used.

This method differs from using the listFiles() methods in that expensive FTPFile objects are not created until needed which may be an advantage on large lists.

Returns:
A FTPListParseEngine object that holds the raw information and is capable of providing parsed FTPFile objects, one for each file containing information contained in the given path in the format determined by the parser parameter. Null will be returned if a data connection cannot be opened. If the current working directory contains no files, an empty array will be the return.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
ParserInitializationException - Thrown if the autodetect mechanism cannot resolve the type of system we are connected with.
See Also:
FTPListParseEngine

initiateListParsing

public FTPListParseEngine initiateListParsing(String pathname)
                                       throws IOException
Using the default autodetect mechanism, initialize an FTPListParseEngine object containing a raw file information for the supplied directory. This information is obtained through the LIST command. This object is then capable of being iterated to return a sequence of FTPFile objects with information filled in by the FTPFileEntryParser used.

The server may or may not expand glob expressions. You should avoid using glob expressions because the return format for glob listings differs from server to server and will likely cause this method to fail.

This method differs from using the listFiles() methods in that expensive FTPFile objects are not created until needed which may be an advantage on large lists.

    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.
    }
 

Returns:
A FTPListParseEngine object that holds the raw information and is capable of providing parsed FTPFile objects, one for each file containing information contained in the given path in the format determined by the parser parameter. Null will be returned if a data connection cannot be opened. If the current working directory contains no files, an empty array will be the return.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
ParserInitializationException - Thrown if the autodetect mechanism cannot resolve the type of system we are connected with.
See Also:
FTPListParseEngine

initiateListParsing

public FTPListParseEngine initiateListParsing(String parserKey,
                                              String pathname)
                                       throws IOException
Using the supplied parser key, initialize an FTPListParseEngine object containing a raw file information for the supplied directory. This information is obtained through the LIST command. This object is then capable of being iterated to return a sequence of FTPFile objects with information filled in by the FTPFileEntryParser used.

The server may or may not expand glob expressions. You should avoid using glob expressions because the return format for glob listings differs from server to server and will likely cause this method to fail.

This method differs from using the listFiles() methods in that expensive FTPFile objects are not created until needed which may be an advantage on large lists.

Parameters:
parserKey - A string representing a designated code or fully-qualified class name of an FTPFileEntryParser that should be used to parse each server file listing. May be null, in which case the code checks first the system property FTP_SYSTEM_TYPE, and if that is not defined the SYST command is used to provide the value. To allow for arbitrary system types, the return from the SYST command is used to look up an alias for the type in the SYSTEM_TYPE_PROPERTIES properties file if it is available.
Returns:
A FTPListParseEngine object that holds the raw information and is capable of providing parsed FTPFile objects, one for each file containing information contained in the given path in the format determined by the parser parameter. Null will be returned if a data connection cannot be opened. If the current working directory contains no files, an empty array will be the return.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
ParserInitializationException - Thrown if the parserKey parameter cannot be resolved by the selected parser factory. In the DefaultFTPEntryParserFactory, this will happen when parserKey is neither the fully qualified class name of a class implementing the interface org.apache.commons.net.ftp.FTPFileEntryParser nor a string containing one of the recognized keys mapping to such a parser or if class loader security issues prevent its being loaded.
See Also:
FTPListParseEngine

getListArguments

protected String getListArguments(String pathname)
Since:
2.0

getStatus

public String getStatus()
                 throws IOException
Issue the FTP STAT command to the server.

Returns:
The status information returned by the server.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

getStatus

public String getStatus(String pathname)
                 throws IOException
Issue the FTP STAT command to the server for a given pathname. This should produce a listing of the file or directory.

Returns:
The status information returned by the server.
Throws:
FTPConnectionClosedException - If the FTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send FTP reply code 421. This exception may be caught either as an IOException or independently as itself.
IOException - If an I/O error occurs while either sending a command to the server or receiving a reply from the server.

getModificationTime

public String getModificationTime(String pathname)
                           throws IOException
Issue the FTP MDTM command (not supported by all servers to retrieve the last modification time of a file. The modification string should be in the ISO 3077 form "YYYYMMDDhhmmss(.xxx)?". The timestamp represented should also be in GMT, but not all FTP servers honour this.

Parameters:
pathname - The file path to query.
Returns:
A string representing the last file modification time in YYYYMMDDhhmmss format.
Throws:
IOException - if an I/O error occurs.
Since:
2.0

setModificationTime

public boolean setModificationTime(String pathname,
                                   String timeval)
                            throws IOException
Issue the FTP MFMT command (not supported by all servers) which sets the last modified time of a file. The timestamp should be in the form YYYYMMDDhhmmss. It should also be in GMT, but not all servers honour this. An FTP server would indicate its support of this feature by including "MFMT" in its response to the FEAT command, which may be retrieved by FTPClient.features()

Parameters:
pathname - The file path for which last modified time is to be changed.
timeval - The timestamp to set to, in YYYYMMDDhhmmss format.
Returns:
true if successfully set, false if not
Throws:
IOException - if an I/O error occurs.
Since:
2.2
See Also:
http://tools.ietf.org/html/draft-somers-ftp-mfxx-04

setBufferSize

public void setBufferSize(int bufSize)
Set the internal buffer size for data sockets.

Parameters:
bufSize - The size of the buffer. Use a non-positive value to use the default.

getBufferSize

public int getBufferSize()
Retrieve the current internal buffer size for data sockets.

Returns:
The current buffer size.

configure

public void configure(FTPClientConfig config)
Implementation of the Configurable interface. In the case of this class, configuring merely makes the config object available for the factory methods that construct parsers.

Specified by:
configure in interface Configurable
Parameters:
config - FTPClientConfig object used to provide non-standard configurations to the parser.
Since:
1.4

setListHiddenFiles

public void setListHiddenFiles(boolean listHiddenFiles)
You can set this to true if you would like to get hidden files when listFiles(java.lang.String) too. A LIST -a will be issued to the ftp server. It depends on your ftp server if you need to call this method, also dont expect to get rid of hidden files if you call this method with "false".

Parameters:
listHiddenFiles - true if hidden files should be listed
Since:
2.0

getListHiddenFiles

public boolean getListHiddenFiles()
Returns:
the current state
Since:
2.0
See Also:
setListHiddenFiles(boolean)

isUseEPSVwithIPv4

public boolean isUseEPSVwithIPv4()
Whether should attempt to use EPSV with IPv4. Default (if not set) is false

Returns:
true if should attempt EPSV
Since:
2.2

setUseEPSVwithIPv4

public void setUseEPSVwithIPv4(boolean selected)
Set whether to use EPSV with IPv4. Might be worth enabling in some circumstances. For example, when using IPv4 with NAT it may work with some rare configurations. E.g. if FTP server has a static PASV address (external network) and the client is coming from another internal network. In that case the data connection after PASV command would fail, while EPSV would make the client succeed by taking just the port.

Parameters:
selected - value to set.
Since:
2.2

setCopyStreamListener

public void setCopyStreamListener(CopyStreamListener listener)
Set the listener to be used when performing store/retrieve operations. The default value (if not set) is null.

Parameters:
listener - to be used, may be null to disable
Since:
3.0

getCopyStreamListener

public CopyStreamListener getCopyStreamListener()
Obtain the currently active listener.

Returns:
the listener, may be null
Since:
3.0

setControlKeepAliveTimeout

public void setControlKeepAliveTimeout(long controlIdle)
Set the time to wait between sending control connection keepalive messages when processing file upload or download.

Parameters:
controlIdle - the wait (in secs) between keepalive messages. Zero (or less) disables.
Since:
3.0
See Also:
setControlKeepAliveReplyTimeout(int)

getControlKeepAliveTimeout

public long getControlKeepAliveTimeout()
Get the time to wait between sending control connection keepalive messages.

Returns:
the number of seconds between keepalive messages.
Since:
3.0

setControlKeepAliveReplyTimeout

public void setControlKeepAliveReplyTimeout(int timeout)
Set how long to wait for control keep-alive message replies.

Parameters:
timeout - number of milliseconds to wait (defaults to 1000)
Since:
3.0
See Also:
setControlKeepAliveTimeout(long)

getControlKeepAliveReplyTimeout

public int getControlKeepAliveReplyTimeout()
Get how long to wait for control keep-alive message replies.

Since:
3.0

setAutodetectUTF8

public void setAutodetectUTF8(boolean autodetect)
Enables or disables automatic server encoding detection (only UTF-8 supported).

Does not affect existing connections; must be invoked before a connection is established.

Parameters:
autodetect - If true, automatic server encoding detection will be enabled.

getAutodetectUTF8

public boolean getAutodetectUTF8()
Tells if automatic server encoding detection is enabled or disabled.

Returns:
true, if automatic server encoding detection is enabled.

getSystemName

@Deprecated
public String getSystemName()
                     throws IOException
Deprecated. use getSystemType() instead

Throws:
IOException


Copyright © 2001-2012 The Apache Software Foundation. All Rights Reserved.