/*

 * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package sun.net.ftp;

import java.net.*;

import java.io.*;

import java.util.Date;

import java.util.List;

import java.util.Iterator;

/**

 * A class that implements the FTP protocol according to

 * RFCs <A href="http://www.ietf.org/rfc/rfc0959.txt">959</A>,

 * <A href="http://www.ietf.org/rfc/rfc2228.txt">2228</A>,

 * <A href="http://www.ietf.org/rfc/rfc2389.txt">2389</A>,

 * <A href="http://www.ietf.org/rfc/rfc2428.txt">2428</A>,

 * <A href="http://www.ietf.org/rfc/rfc3659.txt">3659</A>,

 * <A href="http://www.ietf.org/rfc/rfc4217.txt">4217</A>.

 * Which includes support for FTP over SSL/TLS (aka ftps).

 *

 * {@code FtpClient} provides all the functionalities of a typical FTP

 * client, like storing or retrieving files, listing or creating directories.

 * A typical usage would consist of connecting the client to the server,

 * log in, issue a few commands then logout.

 * Here is a code example:

 * <pre>

 * FtpClient cl = FtpClient.create();

 * cl.connect("ftp.gnu.org").login("anonymous", "john.doe@mydomain.com".toCharArray())).changeDirectory("pub/gnu");

 * Iterator<FtpDirEntry> dir = cl.listFiles();

 *     while (dir.hasNext()) {

 *         FtpDirEntry f = dir.next();

 *         System.err.println(f.getName());

 *     }

 *     cl.close();

 * }

 * </pre>

 * <p><b>Error reporting:</b> There are, mostly, two families of errors that

 * can occur during an FTP session. The first kind are the network related issues

 * like a connection reset, and they are usually fatal to the session, meaning,

 * in all likelyhood the connection to the server has been lost and the session

 * should be restarted from scratch. These errors are reported by throwing an

 * {@link IOException}. The second kind are the errors reported by the FTP server,

 * like when trying to download a non-existing file for example. These errors

 * are usually non fatal to the session, meaning more commands can be sent to the

 * server. In these cases, a {@link FtpProtocolException} is thrown.</p>

 * <p>

 * It should be noted that this is not a thread-safe API, as it wouldn't make

 * too much sense, due to the very sequential nature of FTP, to provide a

 * client able to be manipulated from multiple threads.

 *

 * @since 1.7

 */

public abstract class FtpClient implements java.io.Closeable {

    private static final int FTP_PORT = 21;

    public static enum TransferType {

        ASCII, BINARY, EBCDIC

    };

    /**

     * Returns the default FTP port number.

     *

     * @return the port number.

     */

    public static final int defaultPort() {

        return FTP_PORT;

    }

    /**

     * Creates an instance of FtpClient. The client is not connected to any

     * server yet.

     *

     */

    protected FtpClient() {

    }

    /**

     * Creates an instance of {@code FtpClient}. The client is not connected to any

     * server yet.

     *

     * @return the created {@code FtpClient}

     */

    public static FtpClient create() {

        FtpClientProvider provider = FtpClientProvider.provider();

        return provider.createFtpClient();

    }

    /**

     * Creates an instance of FtpClient and connects it to the specified

     * address.

     *

     * @param dest the {@code InetSocketAddress} to connect to.

     * @return The created {@code FtpClient}

     * @throws IOException if the connection fails

     * @see #connect(java.net.SocketAddress)

     */

    public static FtpClient create(InetSocketAddress dest) throws FtpProtocolException, IOException {

        FtpClient client = create();

        if (dest != null) {

            client.connect(dest);

        }

        return client;

    }

    /**

     * Creates an instance of {@code FtpClient} and connects it to the

     * specified host on the default FTP port.

     *

     * @param dest the {@code String} containing the name of the host

     *        to connect to.

     * @return The created {@code FtpClient}

     * @throws IOException if the connection fails.

     * @throws FtpProtocolException if the server rejected the connection

     */

    public static FtpClient create(String dest) throws FtpProtocolException, IOException {

        return create(new InetSocketAddress(dest, FTP_PORT));

    }

    /**

     * Enables, or disables, the use of the <I>passive</I> mode. In that mode,

     * data connections are established by having the client connect to the server.

     * This is the recommended default mode as it will work best through

     * firewalls and NATs. If set to {@code false} the mode is said to be

     * <I>active</I> which means the server will connect back to the client

     * after a PORT command to establish a data connection.

     *

     * <p><b>Note:</b> Since the passive mode might not be supported by all

     * FTP servers, enabling it means the client will try to use it. If the

     * server rejects it, then the client will attempt to fall back to using

     * the <I>active</I> mode by issuing a {@code PORT} command instead.</p>

     *

     * @param passive {@code true} to force passive mode.

     * @return This FtpClient

     * @see #isPassiveModeEnabled()

     */

    public abstract FtpClient enablePassiveMode(boolean passive);

    /**

     * Tests whether passive mode is enabled.

     *

     * @return {@code true} if the passive mode has been enabled.

     * @see #enablePassiveMode(boolean)

     */

    public abstract boolean isPassiveModeEnabled();

    /**

     * Sets the default timeout value to use when connecting to the server,

     *

     * @param timeout the timeout value, in milliseconds, to use for the connect

     *        operation. A value of zero or less, means use the default timeout.

     *

     * @return This FtpClient

     */

    public abstract FtpClient setConnectTimeout(int timeout);

    /**

     * Returns the current default connection timeout value.

     *

     * @return the value, in milliseconds, of the current connect timeout.

     * @see #setConnectTimeout(int)

     */

    public abstract int getConnectTimeout();

    /**

     * Sets the timeout value to use when reading from the server,

     *

     * @param timeout the timeout value, in milliseconds, to use for the read

     *        operation. A value of zero or less, means use the default timeout.

     * @return This FtpClient

     */

    public abstract FtpClient setReadTimeout(int timeout);

    /**

     * Returns the current read timeout value.

     *

     * @return the value, in milliseconds, of the current read timeout.

     * @see #setReadTimeout(int)

     */

    public abstract int getReadTimeout();

    /**

     * Set the {@code Proxy} to be used for the next connection.

     * If the client is already connected, it doesn't affect the current

     * connection. However it is not recommended to change this during a session.

     *

     * @param p the {@code Proxy} to use, or {@code null} for no proxy.

     * @return This FtpClient

     */

    public abstract FtpClient setProxy(Proxy p);

    /**

     * Get the proxy of this FtpClient

     *

     * @return the {@code Proxy}, this client is using, or {@code null}

     * if none is used.

     * @see #setProxy(Proxy)

     */

    public abstract Proxy getProxy();

    /**

     * Tests whether this client is connected or not to a server.

     *

     * @return {@code true} if the client is connected.

     */

    public abstract boolean isConnected();

    /**

     * Connects the {@code FtpClient} to the specified destination server.

     *

     * @param dest the address of the destination server

     * @return this FtpClient

     * @throws IOException if connection failed.

     * @throws SecurityException if there is a SecurityManager installed and it

     * denied the authorization to connect to the destination.

     * @throws FtpProtocolException

     */

    public abstract FtpClient connect(SocketAddress dest) throws FtpProtocolException, IOException;

    /**

     * Connects the FtpClient to the specified destination server.

     *

     * @param dest the address of the destination server

     * @param timeout the value, in milliseconds, to use as a connection timeout

     * @return this FtpClient

     * @throws IOException if connection failed.

     * @throws SecurityException if there is a SecurityManager installed and it

     * denied the authorization to connect to the destination.

     * @throws FtpProtocolException

     */

    public abstract FtpClient connect(SocketAddress dest, int timeout) throws FtpProtocolException, IOException;

    /**

     * Retrieves the address of the FTP server this client is connected to.

     *

     * @return the {@link SocketAddress} of the server, or {@code null} if this

     * client is not connected yet.

     */

    public abstract SocketAddress getServerAddress();

    /**

     * Attempts to log on the server with the specified user name and password.

     *

     * @param user The user name

     * @param password The password for that user

     * @return this FtpClient

     * @throws FtpProtocolException if the login was refused by the server

     */

    public abstract FtpClient login(String user, char[] password) throws FtpProtocolException, IOException;

    /**

     * Attempts to log on the server with the specified user name, password and

     * account name.

     *

     * @param user The user name

     * @param password The password for that user.

     * @param account The account name for that user.

     * @return this FtpClient

     * @throws IOException if an error occurs during the transmission.

     * @throws FtpProtocolException if the login was refused by the server

     */

    public abstract FtpClient login(String user, char[] password, String account) throws FtpProtocolException, IOException;

    /**

     * Closes the current connection. Logs out the current user, if any, by

     * issuing the QUIT command to the server.

     * This is in effect terminates the current

     * session and the connection to the server will be closed.

     * <p>After a close, the client can then be connected to another server

     * to start an entirely different session.</P>

     *

     * @throws IOException if an error occurs during transmission

     */

    public abstract void close() throws IOException;

    /**

     * Checks whether the client is logged in to the server or not.

     *

     * @return {@code true} if the client has already completed a login.

     */

    public abstract boolean isLoggedIn();

    /**

     * Changes to a specific directory on a remote FTP server

     *

     * @param  remoteDirectory path of the directory to CD to.

     * @return this FtpClient

     * @throws IOException if an error occurs during the transmission.

     * @throws FtpProtocolException if the command was refused by the server

     */

    public abstract FtpClient changeDirectory(String remoteDirectory) throws FtpProtocolException, IOException;

    /**

     * Changes to the parent directory, sending the CDUP command to the server.

     *

     * @return this FtpClient

     * @throws IOException if an error occurs during the transmission.

     * @throws FtpProtocolException if the command was refused by the server

     */

    public abstract FtpClient changeToParentDirectory() throws FtpProtocolException, IOException;

    /**

     * Retrieve the server current working directory using the PWD command.

     *

     * @return a {@code String} containing the current working directory

     * @throws IOException if an error occurs during transmission

     * @throws FtpProtocolException if the command was refused by the server,

     */

    public abstract String getWorkingDirectory() throws FtpProtocolException, IOException;

    /**

     * Sets the restart offset to the specified value.  That value will be

     * sent through a {@code REST} command to server before the next file

     * transfer and has the effect of resuming a file transfer from the

     * specified point. After the transfer the restart offset is set back to

     * zero.

     *

     * @param offset the offset in the remote file at which to start the next

     *        transfer. This must be a value greater than or equal to zero.

     * @return this FtpClient

     * @throws IllegalArgumentException if the offset is negative.

     */

    public abstract FtpClient setRestartOffset(long offset);

    /**

     * Retrieves a file from the ftp server and writes its content to the specified

     * {@code OutputStream}.

     * <p>If the restart offset was set, then a {@code REST} command will be

     * sent before the {@code RETR} in order to restart the tranfer from the specified

     * offset.</p>

     * <p>The {@code OutputStream} is not closed by this method at the end

     * of the transfer. </p>

     * <p>This method will block until the transfer is complete or an exception

     * is thrown.</p>

     *

     * @param name a {@code String} containing the name of the file to

     *        retreive from the server.

     * @param local the {@code OutputStream} the file should be written to.

     * @return this FtpClient

     * @throws IOException if the transfer fails.

     * @throws FtpProtocolException if the command was refused by the server

     * @see #setRestartOffset(long)

     */

    public abstract FtpClient getFile(String name, OutputStream local) throws FtpProtocolException, IOException;

    /**

     * Retrieves a file from the ftp server, using the {@code RETR} command, and

     * returns the InputStream from the established data connection.

     * {@link #completePending()} <b>has</b> to be called once the application

     * is done reading from the returned stream.

     * <p>If the restart offset was set, then a {@code REST} command will be

     * sent before the {@code RETR} in order to restart the tranfer from the specified

     * offset.</p>

     *

     * @param name the name of the remote file

     * @return the {@link java.io.InputStream} from the data connection

     * @throws FtpProtocolException if the command was refused by the server

     * @see #setRestartOffset(long)

     */

    public abstract InputStream getFileStream(String name) throws FtpProtocolException, IOException;

    /**

     * Transfers a file from the client to the server (aka a <I>put</I>)

     * by sending the STOR command, and returns the {@code OutputStream}

     * from the established data connection.

     *

     * A new file is created at the server site if the file specified does

     * not already exist.

     *

     * {@link #completePending()} <b>has</b> to be called once the application

     * is finished writing to the returned stream.

     *

     * @param name the name of the remote file to write.

     * @return the {@link java.io.OutputStream} from the data connection or

     *         {@code null} if the command was unsuccessful.

     * @throws FtpProtocolException if the command was rejected by the server

     */

    public OutputStream putFileStream(String name) throws FtpProtocolException, IOException {

        return putFileStream(name, false);

    }

    /**

     * Transfers a file from the client to the server (aka a <I>put</I>)

     * by sending the STOR or STOU command, depending on the

     * {@code unique} argument, and returns the {@code OutputStream}

     * from the established data connection.

     * {@link #completePending()} <b>has</b> to be called once the application

     * is finished writing to the stream.

     *

     * A new file is created at the server site if the file specified does

     * not already exist.

     *

     * If {@code unique} is set to {@code true}, the resultant file

     * is to be created under a name unique to that directory, meaning

     * it will not overwrite an existing file, instead the server will

     * generate a new, unique, file name.

     * The name of the remote file can be retrieved, after completion of the

     * transfer, by calling {@link #getLastFileName()}.

     *

     * @param name the name of the remote file to write.

     * @param unique {@code true} if the remote files should be unique,

     *        in which case the STOU command will be used.

     * @return the {@link java.io.OutputStream} from the data connection.

     * @throws FtpProtocolException if the command was rejected by the server

     */

    public abstract OutputStream putFileStream(String name, boolean unique) throws FtpProtocolException, IOException;

    /**

     * Transfers a file from the client to the server (aka a <I>put</I>)

     * by sending the STOR or STOU command, depending on the

     * {@code unique} argument. The content of the {@code InputStream}

     * passed in argument is written into the remote file, overwriting any

     * existing data.

     *

     * A new file is created at the server site if the file specified does

     * not already exist.

     *

     * If {@code unique} is set to {@code true}, the resultant file

     * is to be created under a name unique to that directory, meaning

     * it will not overwrite an existing file, instead the server will

     * generate a new, unique, file name.

     * The name of the remote file can be retrieved, after completion of the

     * transfer, by calling {@link #getLastFileName()}.

     *

     * <p>This method will block until the transfer is complete or an exception

     * is thrown.</p>

     *

     * @param name the name of the remote file to write.

     * @param local the {@code InputStream} that points to the data to

     *        transfer.

     * @return this FtpClient

     * @throws FtpProtocolException if the command was rejected by the server

     */

    public FtpClient putFile(String name, InputStream local) throws FtpProtocolException, IOException {

        return putFile(name, local, false);

    }

    /**

     * Transfers a file from the client to the server (aka a <I>put</I>)

     * by sending the STOR command. The content of the {@code InputStream}

     * passed in argument is written into the remote file, overwriting any

     * existing data.

     *

     * A new file is created at the server site if the file specified does

     * not already exist.

     *

     * <p>This method will block until the transfer is complete or an exception

     * is thrown.</p>

     *

     * @param name the name of the remote file to write.

     * @param local the {@code InputStream} that points to the data to

     *        transfer.

     * @param unique {@code true} if the remote file should be unique

     *        (i.e. not already existing), {@code false} otherwise.

     * @return this FtpClient

     * @throws FtpProtocolException if the command was rejected by the server

     * @see #getLastFileName()

     */

    public abstract FtpClient putFile(String name, InputStream local, boolean unique) throws FtpProtocolException, IOException;

    /**

     * Sends the APPE command to the server in order to transfer a data stream

     * passed in argument and append it to the content of the specified remote

     * file.

     *