* Copyright ©2007-2008 by David R. Tribble, all rights reserved.
* 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
{
// Identification
/** Revision information. */
static final String REV =
"@(#)tribble/net/ftp/FTPSimpleClientI.java $Revision: 1.5 $ $Date: 2008/09/18 21:45:34 $\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 len 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
* System.getProperty("line.separator") 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 src (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 not 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 src (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 not 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 src (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 src (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 not 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 src (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
* (""), 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 Strings containing the filenames in the remote
* directory.
*
* @throws IOException
* Thrown if an error occurs.
*
* @since 1.1, 2007-02-28
*/
public abstract ArrayList 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
* (""), 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 accept() 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 Strings containing the filenames in the remote
* directory.
*
* @throws IOException
* Thrown if an error occurs.
*
* @since 1.2, 2007-04-15
*/
public abstract ArrayList 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