//==============================================================================
// FTPSimpleClientI.java
//==============================================================================

package tribble.net.ftp;

import java.io.File;
import java.io.FilenameFilter;
import java.io.InputStream;
import java.io.IOException;
import java.io.OutputStream;

import java.lang.Exception;
import java.lang.String;

import java.util.ArrayList;


/*******************************************************************************
* Simple FTP client interface.
* Allows clients to establish FTP connections, send and receive files, get
* remote directory listings, etc.
*
* <!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~->
* <dl>
* <dt> <b>Source code:</b> </dt>
*  <dd> Available at:
*   <a href="http://david.tribble.com/src/java/tribble/net/ftp/FTPSimpleClientI.java"
*    >http://david.tribble.com/src/java/tribble/net/ftp/FTPSimpleClientI.java</a>
*  </dd>
* <dt> <b>Documentation:</b> </dt>
*  <dd> Available at:
*   <a href="http://david.tribble.com/docs/tribble/net/ftp/FTPSimpleClientI.html"
*    >http://david.tribble.com/docs/tribble/net/ftp/FTPSimpleClientI.html</a>
*  </dd>
* </dl>
*
* <!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~->
* @version	API 2.0 $Revision: 1.6 $ $Date: 2010/07/12 21:27:40 $
* @since	API 1.0, 2007-02-28
* @author	David R. Tribble (david&#64;tribble.com).
*	<p>
*	Copyright ©2007-2010 by David R. Tribble, all rights reserved.<br/
*	Permission is granted to any person or entity except those designated
*	by the United States Department of State as a terrorist, or terrorist
*	government or agency, to use and distribute this source code provided
*	that the original copyright notice remains present and unaltered.
*/

public interface FTPSimpleClientI
{
    /** Revision information. */
    static final String		REV =
        "@(#)tribble/net/ftp/FTPSimpleClientI.java API 2.0 $Revision: 1.6 $ $Date: 2010/07/12 21:27:40 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Methods

    /***************************************************************************
    * Retrieve the remote FTP host name.
    *
    * @return
    * FTP system host name or IP address.
    *
    * @see	#setHost setHost()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract String getHost();


    /***************************************************************************
    * Set the remote FTP host (system) name.
    *
    * @param	host
    * FTP system host name or IP address.
    *
    * @see	#getHost getHost()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void setHost(String host);


    /***************************************************************************
    * Retrieve the FTP command port number.
    *
    * @return
    * FTP command port number.
    *
    * @see	#setCommandPort setCommandPort()
    * @see	#getDataPort getDataPort()
    *
    * @since	1.1, 2006-03-22
    */
    public abstract int getCommandPort();


    /***************************************************************************
    * Set the remote FTP command port number.
    *
    * @param	port
    * FTP command port number.  (The default FTP port is 21.)
    *
    * @see	#getCommandPort getCommandPort()
    * @see	#setDataPort setDataPort()
    *
    * @since	1.1, 2006-03-22
    */
    public abstract void setCommandPort(int port);


    /***************************************************************************
    * Retrieve the FTP data port number.
    *
    * @return
    * FTP data port number.
    *
    * @see	#setDataPort setDataPort()
    * @see	#getCommandPort getCommandPort()
    *
    * @since	1.1, 2006-03-22
    */
    public abstract int getDataPort();


    /***************************************************************************
    * Set the remote FTP data port number.
    *
    * @param	port
    * FTP data port number.  Setting this to zero or a negative number causes
    * the data ports to be chosen (randomly) by the local system when operating
    * in non-passive mode.  (The default FTP port is 0.)
    *
    * @see	#getDataPort getDataPort()
    * @see	#setCommandPort setCommandPort()
    *
    * @since	1.1, 2006-03-22
    */
    public abstract void setDataPort(int port);


    /***************************************************************************
    * Retrieve the FTP I/O time-out.
    *
    * @return
    * FTP I/O time-out, in seconds.
    *
    * @see	#setTimeOut setTimeOut()
    * @see	#getCommandPort getCommandPort()
    * @see	#getDataPort getDataPort()
    *
    * @since	1.1, 2006-06-02
    */
    public abstract int getTimeOut();


    /***************************************************************************
    * Set the remote FTP I/O time-out.
    *
    * @param	secs
    * FTP I/O time-out, in seconds.
    *
    * @see	#getTimeOut getTimeOut()
    * @see	#setCommandPort setCommandPort()
    * @see	#setDataPort setDataPort()
    *
    * @since	1.1, 2006-06-02
    */
    public abstract void setTimeOut(int secs);


    /***************************************************************************
    * Set the size of the FTP data transfer buffer.
    *
    * @param	len
    * New buffer size.
    * Values between 1K (1,024) and 16K (16,384) are probably optimal for most
    * applications.
    * Classes that implement this interface may choose to ignore this setting.
    *
    * @return
    * The previous buffer size setting.
    *
    * @throws	IllegalArgumentException (unchecked)
    * Thrown if <tt>len</tt> is less than 1.
    *
    * @see	#appendFile(File, String) appendFile()
    * @see	#getFile(String, File) getFile()
    * @see	#putFile(File, String) putFile()
    *
    * @since	1.5, 2008-09-18
    */
    public abstract int setBufferSize(int len);


    /***************************************************************************
    * Retrieve the user-ID.
    *
    * @see	#setUserID setUserID()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract String getUserID();


    /***************************************************************************
    * Set the user name (user-ID).
    *
    * @param	id
    * User-ID.
    *
    * @see	#getUserID getUserID()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void setUserID(String id);


    /***************************************************************************
    * Retrieve the user password.
    *
    * @return
    * User password.
    *
    * @see	#setPassword setPassword()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract String getPassword();


    /***************************************************************************
    * Set the user password.
    *
    * @param	pwd
    * User password.
    *
    * @see	#getPassword getPassword()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void setPassword(String pwd);


    /***************************************************************************
    * Set this FTP client to operate (or not) in passive data transfer mode.
    * Passive mode allows the remote FTP system to assign the data ports, while
    * non-passive mode allows the client to assign them.
    *
    * @param	flag
    * If true, the data transfer mode is set to passive, otherwise it is set to
    * non-passive (active listen) mode.
    *
    * @return
    * The previous mode setting.
    *
    * @since	1.1, 2006-03-17
    */
    public abstract boolean setPassive(boolean flag);


    /***************************************************************************
    * Connect to the remote FTP system.
    *
    * @throws	IOException
    * Thrown if unable to connect to the remote FTP system.
    *
    * @see	#disconnect disconnect()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void connect()
        throws IOException;


    /***************************************************************************
    * Disconnect from the remote FTP system.
    * Note that this method does not throw {@link IOException}.
    *
    * @see	#connect connect()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void disconnect();


    /***************************************************************************
    * Determine if this client is connected to the remote FTP system.
    *
    * @return
    * True if this client has connected to a remote FTP system, otherwise false.
    *
    * @see	#connect connect()
    * @see	#disconnect disconnect()
    *
    * @since	1.1, 2006-04-06
    */
    public abstract boolean isConnected();


    /***************************************************************************
    * Log on to the remote FTP system.
    * This uses the last setting of the user-ID and password.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @see	#connect connect()
    * @see	#setUserID setUserID()
    * @see	#setPassword setPassword()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void login()
        throws IOException;


    /***************************************************************************
    * Determine if this client is logged to the remote FTP system.
    *
    * @return
    * True if this client has connected and a user if logged into a remote FTP
    * system, otherwise false.
    *
    * @see	#login() login()
    *
    * @since	1.1, 2006-04-06
    */
    public abstract boolean isLoggedIn();


    /***************************************************************************
    * Set the transfer mode to text (ASCII) or binary.
    * In ASCII mode, files are transferred as text files, so that newline
    * sequences (CR, LF, or CR/LF) are converted into the local native newline
    * sequence (which is determined by the
    * <tt>System.getProperty("line.separator")</tt> setting).
    *
    * @param	flag
    * If true, the transfer mode is set to "ASCII" (text), otherwise it is set
    * to "binary".
    *
    * @return
    * The previous mode setting.
    *
    * @since	1.4, 2007-07-26
    */
    public abstract boolean setTextMode(boolean flag);


    /***************************************************************************
    * Set the working directory on the remote FTP system.
    *
    * @param	dir
    * Remote directory name.
    *
    * @return
    * The new current remote directory name.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @see	#getRemoteDir getRemoteDir()
    * @see	#setLocalDir setLocalDir()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract String setRemoteDir(String dir)
        throws IOException;


    /***************************************************************************
    * Set the working directory on the remote FTP system to the parent directory
    * of the current working directory.
    * In other words, change the directory to be one level up from the current
    * setting.
    *
    * @return
    * The new current remote directory name.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @see	#getRemoteDir getRemoteDir()
    * @see	#setRemoteDir setRemoteDir()
    * @see	#setLocalDir setLocalDir()
    *
    * @since	1.1, 2006-04-01
    */
    public abstract String setRemoteDirUp()
        throws IOException;


    /***************************************************************************
    * Retrieve the working directory of the remote FTP system.
    *
    * @return
    * The current remote directory name.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @see	#setRemoteDir setRemoteDir()
    * @see	#getLocalDir getLocalDir()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract String getRemoteDir()
        throws	IOException;


    /***************************************************************************
    * Set the working directory on the local system.
    * Note that this does not actually change the current working directory for
    * the Java program, but only establishes the default directory prefix to use
    * for local files sent or received by this FTP session.
    *
    * @param	dir
    * Local directory name.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @see	#getLocalDir getLocalDir()
    * @see	#setRemoteDir setRemoteDir()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void setLocalDir(String dir)
        throws IOException;


    /***************************************************************************
    * Retrieve the working directory of the local system.
    *
    * @return
    * The current local directory name.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @see	#setLocalDir setLocalDir()
    * @see	#getRemoteDir getRemoteDir()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract String getLocalDir()
        throws IOException;


    /***************************************************************************
    * Get (receive) a file from the remote FTP system to the local system.
    *
    * @param	src
    * Remote source filename.  If this does not contain a directory prefix, the
    * current remote working directory is assumed.
    *
    * @param	dst
    * Local source filename.  If this does not contain a directory prefix, the
    * current local working directory is assumed.  This may be null, in which
    * case the base filename of <tt>src</tt> (without the directory prefix) is
    * used.
    *
    * @throws	IOException
    * Thrown if the file could not be transmitted or if any other error occurs.
    *
    * @see	#getFile(String, OutputStream) getFile()
    * @see	#putFile(File, String) putFile()
    * @see	#appendFile(File, String) appendFile()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void getFile(String src, File dst)
        throws IOException;


    /***************************************************************************
    * Get (receive) a file from the remote FTP system to the local system.
    *
    * @param	src
    * Remote source filename.  If this does not contain a directory prefix, the
    * current remote working directory is assumed.
    *
    * @param	out
    * Output stream to write the contents of the file retrieved from the remote
    * FTP system to.  Note that this stream is flushed but is <i>not</i> closed
    * after the contents have been transmitted.
    *
    * @throws	IOException
    * Thrown if the file could not be transmitted or if any other error occurs.
    *
    * @see	#getFile(String, File) getFile()
    * @see	#putFile(InputStream, String) putFile()
    * @see	#appendFile(InputStream, String) appendFile()
    *
    * @since	1.1, 2006-04-10
    */
    public abstract void getFile(String src, OutputStream out)
        throws IOException;


    /***************************************************************************
    * Put (send) a file from the local system to the remote FTP system.
    *
    * @param	src
    * Local source filename.  If this does not contain a directory prefix, the
    * current local working directory is assumed.
    *
    * @param	dst
    * Remote target filename.  If this does not contain a directory prefix, the
    * current remote working directory is assumed.  This may be null, in which
    * case the base filename of <tt>src</tt> (without the directory prefix) is
    * used.
    *
    * @throws	IOException
    * Thrown if the file could not be transmitted or if any other error occurs.
    *
    * @see	#putFile(InputStream, String) putFile()
    * @see	#appendFile(File, String) appendFile()
    * @see	#getFile(String, File) getFile()
    *
    * @since	1.1, 2001-04-14
    */
    public abstract void putFile(File src, String dst)
        throws IOException;


    /***************************************************************************
    * Put (send) a file from the local system to the remote FTP system.
    *
    * @param	in
    * Input stream containing the contents of the file to send to the remote FTP
    * system.  Note that this stream is <i>not</i> closed after the contents
    * have been transmitted.
    *
    * @param	dst
    * Remote target filename.  If this does not contain a directory prefix, the
    * current remote working directory is assumed.  This may be null, in which
    * case the base filename of <tt>src</tt> (without the directory prefix) is
    * used.
    *
    * @throws	IOException
    * Thrown if the file could not be transmitted or if any other error occurs.
    *
    * @see	#putFile(File, String) putFile()
    * @see	#appendFile(InputStream, String) appendFile()
    * @see	#getFile(String, OutputStream) getFile()
    *
    * @since	1.1, 2006-04-10
    */
    public abstract void putFile(InputStream in, String dst)
        throws IOException;


    /***************************************************************************
    * Append (send) a file from the local system to a file on the remote FTP
    * system.
    *
    * @param	src
    * Local source filename.  If this does not contain a directory prefix, the
    * current local working directory is assumed.
    *
    * @param	dst
    * Remote target filename.  If this does not contain a directory prefix, the
    * current remote working directory is assumed.  This may be null, in which
    * case the base filename of <tt>src</tt> (without the directory prefix) is
    * used.
    *
    * @throws	IOException
    * Thrown if the file could not be transmitted or if any other error occurs.
    *
    * @see	#appendFile(InputStream, String) appendFile()
    * @see	#putFile(File, String) putFile()
    * @see	#getFile(String, File) getFile()
    *
    * @since	1.3, 2007-07-21
    */
    public abstract void appendFile(File src, String dst)
        throws IOException;


    /***************************************************************************
    * Append (send) a file from the local system to a file on the remote FTP
    * system.
    *
    * @param	in
    * Input stream containing the contents of the file to send to the remote FTP
    * system.  Note that this stream is <i>not</i> closed after the contents
    * have been transmitted.
    *
    * @param	dst
    * Remote target filename.  If this does not contain a directory prefix, the
    * current remote working directory is assumed.  This may be null, in which
    * case the base filename of <tt>src</tt> (without the directory prefix) is
    * used.
    *
    * @throws	IOException
    * Thrown if the file could not be transmitted or if any other error occurs.
    *
    * @see	#appendFile(File, String) appendFile()
    * @see	#putFile(InputStream, String) putFile()
    * @see	#getFile(String, OutputStream) getFile()
    *
    * @since	1.3, 2007-07-21
    */
    public abstract void appendFile(InputStream in, String dst)
        throws IOException;


    /***************************************************************************
    * Get (receive) a list of filenames in a directory on the remote FTP system.
    *
    * @param	path
    * The remote directory or filename to list.  If this is empty
    * (<tt>""</tt>), the current remote working directory is assumed.
    *
    * @param	max
    * Maximum number of filenames to list.  A value of zero (0) specifies that
    * there is no maximum.
    *
    * @return
    * A vector of <tt>String</tt>s containing the filenames in the remote
    * directory.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	1.1, 2007-02-28
    */
    public abstract ArrayList<String> getDirectoryNames(String path, int max)
        throws IOException;


    /***************************************************************************
    * Get (receive) a list of filenames in a directory on the remote FTP system.
    *
    * @param	path
    * The remote directory or filename to list.  If this is empty
    * (<tt>""</tt>), the current remote working directory is assumed.
    *
    * @param	filt
    * Filer to apply to the filenames.  Only filenames that are accepted by the
    * filter will appear in the returned vector.  If this is null, no filtering
    * is applied to the filenames.  This object's <tt>accept()</tt> method is
    * called for each filename in the directory, being passed a null directory
    * (first argument) and the found filename (second argument).
    *
    * @param	max
    * Maximum number of filenames to return.  A value of zero (0) specifies that
    * there is no maximum.
    *
    * @return
    * A vector of <tt>String</tt>s containing the filenames in the remote
    * directory.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	1.2, 2007-04-15
    */
    public abstract ArrayList<String> getDirectoryNames(String path,
        FilenameFilter filt, int max)
        throws IOException;


    /***************************************************************************
    * Rename a file or directory on the remote FTP system.
    *
    * @param	from
    * Old (existing) remote file or directory name to rename.
    *
    * @param	to
    * New name to rename the remote file or directory to.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	1.1, 2006-03-16
    */
    public abstract void rename(String from, String to)
        throws IOException;


    /***************************************************************************
    * Remove a file on the remote FTP system.
    *
    * @param	file
    * Name of the file to delete.  If this specifies a relative filename, the
    * file is assumed to be located in the current remote working directory.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	1.1, 2006-03-16
    */
    public abstract void removeFile(String file)
        throws IOException;


    /***************************************************************************
    * Create a directory on the remote FTP system.
    *
    * @param	dir
    * Name of the directory to create.  If this specifies a relative directory
    * name, the directory is created in the current remote working directory.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	1.1, 2006-03-16
    */
    public abstract void createDirectory(String dir)
        throws IOException;


    /***************************************************************************
    * Remove a directory on the remote FTP system.
    *
    * @param	dir
    * Name of the directory to delete.  If this specifies a relative directory
    * name, the directory is assumed to be located in the current remote working
    * directory.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	1.1, 2006-03-16
    */
    public abstract void removeDirectory(String dir)
        throws IOException;
}

// End FTPSimpleClientI.java