net/ftp/FtpClient.java

8  * particular file as subject to the "Classpath" exception as provided
18  * 2 along with this work; if not, write to the Free Software Foundation,
34  * A class that implements the FTP protocol according to
45  * A typical usage would consist of connecting the client to the server,
61  * like a connection reset, and they are usually fatal to the session, meaning,
62  * in all likelyhood the connection to the server has been lost and the session
65  * like when trying to download a non-existing file for example. These errors
66  * are usually non fatal to the session, meaning more commands can be sent to the
70  * too much sense, due to the very sequential nature of FTP, to provide a
71  * client able to be manipulated from multiple threads.
94      * Creates an instance of FtpClient. The client is not connected to any
102      * Creates an instance of {@code FtpClient}. The client is not connected to any
113      * Creates an instance of FtpClient and connects it to the specified
116      * @param dest the {@code InetSocketAddress} to connect to.
130      * Creates an instance of {@code FtpClient} and connects it to the
134      *        to connect to.
145      * data connections are established by having the client connect to the server.
147      * firewalls and NATs. If set to {@code false} the mode is said to be
148      * <I>active</I> which means the server will connect back to the client
149      * after a PORT command to establish a data connection.
152      * FTP servers, enabling it means the client will try to use it. If the
153      * server rejects it, then the client will attempt to fall back to using
156      * @param passive {@code true} to force passive mode.
171      * Sets the default timeout value to use when connecting to the server,
173      * @param timeout the timeout value, in milliseconds, to use for the connect
189      * Sets the timeout value to use when reading from the server,
191      * @param timeout the timeout value, in milliseconds, to use for the read
206      * Set the {@code Proxy} to be used for the next connection.
208      * connection. However it is not recommended to change this during a session.
210      * @param p the {@code Proxy} to use, or {@code null} for no proxy.
225      * Tests whether this client is connected or not to a server.
232      * Connects the {@code FtpClient} to the specified destination server.
238      * denied the authorization to connect to the destination.
244      * Connects the FtpClient to the specified destination server.
247      * @param timeout the value, in milliseconds, to use as a connection timeout
251      * denied the authorization to connect to the destination.
257      * Retrieves the address of the FTP server this client is connected to.
265      * Attempts to log on the server with the specified user name and password.
276      * Attempts to log on the server with the specified user name, password and
290      * issuing the QUIT command to the server.
292      * session and the connection to the server will be closed.
293      * <p>After a close, the client can then be connected to another server
294      * to start an entirely different session.</P>
301      * Checks whether the client is logged in to the server or not.
308      * Changes to a specific directory on a remote FTP server
310      * @param  remoteDirectory path of the directory to CD to.
318      * Changes to the parent directory, sending the CDUP command to the server.
336      * Sets the restart offset to the specified value.  That value will be
337      * sent through a {@code REST} command to server before the next file
339      * specified point. After the transfer the restart offset is set back to
342      * @param offset the offset in the remote file at which to start the next
343      *        transfer. This must be a value greater than or equal to zero.
350      * Retrieves a file from the ftp server and writes its content to the specified
353      * sent before the {@code RETR} in order to restart the tranfer from the specified
360      * @param name a {@code String} containing the name of the file to
362      * @param local the {@code OutputStream} the file should be written to.
373      * {@link #completePending()} <b>has</b> to be called once the application
376      * sent before the {@code RETR} in order to restart the tranfer from the specified
388      * Transfers a file from the client to the server (aka a <I>put</I>)
395      * {@link #completePending()} <b>has</b> to be called once the application
396      * is finished writing to the returned stream.
398      * @param name the name of the remote file to write.
409      * Transfers a file from the client to the server (aka a <I>put</I>)
413      * {@link #completePending()} <b>has</b> to be called once the application
414      * is finished writing to the stream.
419      * If {@code unique} is set to {@code true}, the resultant file
420      * is to be created under a name unique to that directory, meaning
426      * @param name the name of the remote file to write.
436      * Transfers a file from the client to the server (aka a <I>put</I>)
445      * If {@code unique} is set to {@code true}, the resultant file
446      * is to be created under a name unique to that directory, meaning
455      * @param name the name of the remote file to write.
456      * @param local the {@code InputStream} that points to the data to
467      * Transfers a file from the client to the server (aka a <I>put</I>)
478      * @param name the name of the remote file to write.
479      * @param local the {@code InputStream} that points to the data to
491      * Sends the APPE command to the server in order to transfer a data stream
492      * passed in argument and append it to the content of the specified remote
499      *        to append to.
500      * @param local The {@code InputStream} providing access to the data
501      *        to be appended.
512      * @param to the new name for the file
517     public abstract FtpClient rename(String from, String to) throws FtpProtocolException, IOException;
523      *        to delete.
534      *        to create.
545      *        to remove.
564      * Sends the {@code STAT} command to the server.
565      * This can be used while a data connection is open to get a status
573      *        the STAT command should apply to.
581      * Sends the {@code FEAT} command to the server and returns the list of supported
598      * Sends the {@code ABOR} command to the server.
599      * <p>It tells the server to stop the previous command or transfer. No action
612      * method can be called to wait until completion. This is typically the case
614      * So this method should be called before accessing information related to
622      * <p>It should be also noted that most methods issuing commands to the ftp
656      * proper command (e.g. TYPE A) to the server.
658      * @param type the {@code TransferType} to use.
666      * Changes the current transfer type to binary.
667      * This is a convenience method that is equivalent to
681      * Changes the current transfer type to ascii.
682      * This is a convenience method that is equivalent to
696      * Issues a {@code LIST} command to the server to get the current directory
699      * <p>{@link #completePending()} <b>has</b> to be called once the application
702      * @param path the pathname of the directory to list, or {@code null}
713      * Issues a {@code NLST path} command to server to get the specified directory
718      * <p>{@link #completePending()} <b>has</b> to be called once the application
722      *        directory to list or {@code null} for the current working directory.
730      * Issues the {@code SIZE [path]} command to the server to get the size of a
746      * Issues the {@code MDTM [path]} command to the server to get the modification
761      * Sets the parser used to handle the directory output to the specified
762      * one. By default the parser is set to one that can handle most FTP
764      * and application to provide its own parser due to some uncommon
767      * @param p The {@code FtpDirParser} to use.
774      * Issues a {@code MLSD} command to the server to get the specified directory
775      * listing and applies the internal parser to create an Iterator of
782      * {@link #completePending()} <b>has</b> to be called once the application
785      * @param path the pathname of the directory to list or {@code null}
797      * Attempts to use Kerberos GSSAPI as an authentication mechanism with the
800      * command to exchange the various tokens until authentication is
801      * successful. This conforms to Appendix I of RFC 2228.
835      * response to a {@code RETR} or similar request.
845      * set since it allows to recover the unique file name created on the
854      * Attempts to switch to a secure, encrypted connection. This is done by
873      * command to the server terminating an encrypted session and reverting
874      * back to a non encrypted transmission.
884      * Sends the "Allocate" ({@code ALLO}) command to the server telling it to
887      * @param size The number of bytes to allocate.
895      * Sends the "Structure Mount" ({@code SMNT}) command to the server. This let the
900      *        structure to mount.
908      * Sends a System ({@code SYST}) command to the server and returns the String
920      * Sends the {@code HELP} command to the server, with an optional command, like
933      * Sends the {@code SITE} command to the server. This is used by the server
934      * to provide services specific to his system that are essential
935      * to file transfer.
937      * @param cmd the command to be sent.