ftpclientinterface.java

java编写的非常详尽的基于ftp协议的上传下载源码

    
    /**
     *  Cancels the current transfer. Generally called from a separate
     *  thread. Note that this may leave partially written files on the
     *  server or on local disk, and should not be used unless absolutely
     *  necessary. After the transfer is cancelled the connection may be in
     *  an inconsistent state, therefore it is best to quit and reconnect.
     *  It may cause exceptions to be thrown depending on the underlying protocol
     *  being used. Note that this can also be used to cancel directory listings,
     *  which can involve large amounts of data for directories containing many
     *  files.
     */
    public void cancelTransfer();

	/**
	 *  Put a local file onto the FTP server. It
	 *  is placed in the current directory. If a remote file name is supplied,
     *  it is stored as that name on the server. If null is supplied, the server
     *  will generate a unique filename (via STOU) if it supports this option.
	 *
	 *  @param  localPath   path of the local file
	 *  @param  remoteFile  name of remote file in
	 *                      current directory, or null if 
     *                       a unique filename is to be generated by the server
     *  @return The name of the remote file - normally the name supplied, or else
     *           the unique name generated by the server.
	 */
	public String put(String localPath, String remoteFile)
			throws IOException, FTPException;

	/**
	 *  Put a stream of data onto the FTP server. It
	 *  is placed in the current directory. If a remote file name is supplied,
     *  it is stored as that name on the server. If null is supplied, the server
     *  will generate a unique filename (via STOU) if it supports this option.
	 *
	 *  @param  srcStream   input stream of data to put
	 *  @param  remoteFile  name of remote file in
	 *                      current directory, or null if 
     *                       a unique filename is to be generated by the server
     *  @return The name of the remote file - normally the name supplied, or else
     *           the unique name generated by the server.
	 */
	public String put(InputStream srcStream, String remoteFile)
			throws IOException, FTPException;
    
    /**
     *  Put a stream of data onto the FTP server. It
     *  is placed in the current directory. If a remote file name is supplied,
     *  it is stored as that name on the server. If null is supplied, the server
     *  will generate a unique filename (via STOU) if it supports this option.
     *  Allows appending if current file exists. 
     *
     *  @param  srcStream   input stream of data to put
     *  @param  remoteFile  name of remote file in
     *                      current directory, or null if 
     *                       a unique filename is to be generated by the server
     *  @param  append      true if appending, false otherwise
     *  @return The name of the remote file - normally the name supplied, or else
     *           the unique name generated by the server.
     */
    public String put(InputStream srcStream, String remoteFile,
                    boolean append)
        throws IOException, FTPException;

	/**
	 *  Put data onto the FTP server. It
	 *  is placed in the current directory. If a remote file name is supplied,
     *  it is stored as that name on the server. If null is supplied, the server
     *  will generate a unique filename (via STOU) if it supports this option.
	 *
	 *  @param  bytes        array of bytes
	 *  @param  remoteFile  name of remote file in
	 *                      current directory, or null if 
     *                       a unique filename is to be generated by the server
     *  @return The name of the remote file - normally the name supplied, or else
     *           the unique name generated by the server.
	 */
	public String put(byte[] bytes, String remoteFile)
			throws IOException, FTPException;
    
    /**
     *  Put data onto the FTP server. It
     *  is placed in the current directory. If a remote file name is supplied,
     *  it is stored as that name on the server. If null is supplied, the server
     *  will generate a unique filename (via STOU) if it supports this option.
     *  Allows appending if current file exists.
     *
     *  @param  bytes        array of bytes
     *  @param  remoteFile  name of remote file in
     *                      current directory, or null if 
     *                       a unique filename is to be generated by the server
     *  @param  append      true if appending, false otherwise
     *  @return The name of the remote file - normally the name supplied, or else
     *           the unique name generated by the server.
     */
    public String put(byte[] bytes, String remoteFile, boolean append)
        throws IOException, FTPException;   

    /**
     *  Put a local file onto the FTP server. It
     *  is placed in the current directory. If a remote file name is supplied,
     *  it is stored as that name on the server. If null is supplied, the server
     *  will generate a unique filename (via STOU) if it supports this option. 
     *  Allows appending if current file exists.
     *
     *  @param  localPath   path of the local file
     *  @param  remoteFile  name of remote file in current directory, or null if 
     *                       a unique filename is to be generated by the server
     *  @param  append      true if appending, false otherwise
     *  @return The name of the remote file - normally the name supplied, or else
     *           the unique name generated by the server.
     */
    public String put(String localPath, String remoteFile,
                    boolean append)
        throws IOException, FTPException;
    
	/**
	 *  Get data from the FTP server. Uses the currently
	 *  set transfer mode.
	 *
	 *  @param  localPath   local file to put data in
	 *  @param  remoteFile  name of remote file in
	 *                      current directory
	 */
	public void get(String localPath, String remoteFile)
			throws IOException, FTPException;

	/**
	 *  Get data from the FTP server. Uses the currently
	 *  set transfer mode.
	 *
	 *  @param  destStream  data stream to write data to
	 *  @param  remoteFile  name of remote file in
	 *                      current directory
	 */
	public void get(OutputStream destStream, String remoteFile)
			throws IOException, FTPException;

	/**
	 *  Get data from the FTP server. Transfers in
	 *  whatever mode we are in. Retrieve as a byte array. Note
	 *  that we may experience memory limitations as the
	 *  entire file must be held in memory at one time.
	 *
	 *  @param  remoteFile  name of remote file in
	 *                      current directory
	 */
	public byte[] get(String remoteFile) throws IOException,
			FTPException;
    
    /**
     * Get the number of files downloaded since the count was
     * reset
     * 
     * @return  download file count
     */
    public int getDownloadCount();
    
    /**
     * Reset the count of downloaded files to zero.
     *
     */
    public void resetDownloadCount();
    
    /**
     * Get the number of files uploaded since the count was
     * reset
     * 
     * @return  upload file count
     */
    public int getUploadCount();
    
    /**
     * Reset the count of uploaded files to zero.
     *
     */
    public void resetUploadCount();
    
    /**
     * Get the number of files deleted since the count was
     * reset
     * 
     * @return  deleted file count
     */
    public int getDeleteCount();
    
    /**
     * Reset the count of deleted files to zero.
     *
     */
    public void resetDeleteCount();

	/**
	 *  List a directory's contents as an array of FTPFile objects.
	 *  Should work for Windows and most Unix FTP servers - let us know
	 *  about unusual formats (http://www.enterprisedt.com/forums/index.php).
     *  If accurate timestamps are required (i.e. to the second), it is 
     *  generally better to use @see #modtime(String).
	 *
	 *  @param   dirname  name of directory (some servers permit a filemask)
	 *  @return  an array of FTPFile objects
	 */
	public FTPFile[] dirDetails(String dirname) throws IOException,
			FTPException, ParseException;

	/**
	 *  List current directory's contents as an array of strings of
	 *  filenames.
	 *
	 *  @return  an array of current directory listing strings
	 */
	public String[] dir() throws IOException, FTPException;

	/**
	 *  List a directory's contents as an array of strings of filenames.
	 *
	 *  @param   dirname  name of directory OR filemask
	 *  @return  an array of directory listing strings
	 */
	public String[] dir(String dirname) throws IOException,
			FTPException;

	/**
	 *  List a directory's contents as an array of strings. A detailed
	 *  listing is available, otherwise just filenames are provided.
	 *  The detailed listing varies in details depending on OS and
	 *  FTP server. Note that a full listing can be used on a file
	 *  name to obtain information about a file
	 *
	 *  @param  dirname  name of directory OR filemask
	 *  @param  full     true if detailed listing required
	 *                   false otherwise
	 *  @return  an array of directory listing strings
	 */
	public String[] dir(String dirname, boolean full)
			throws IOException, FTPException;

	/**
	 *  Delete the specified remote file
	 *
	 *  @param  remoteFile  name of remote file to
	 *                      delete
	 */
	public void delete(String remoteFile) throws IOException,
			FTPException;

	/**
	 *  Rename a file or directory
	 *
	 * @param from  name of file or directory to rename
	 * @param to    intended name
	 */
	public void rename(String from, String to) throws IOException,
			FTPException;

	/**
	 *  Delete the specified remote working directory
	 *
	 *  @param  dir  name of remote directory to
	 *               delete
	 */
	public void rmdir(String dir) throws IOException, FTPException;

	/**
	 *  Create the specified remote working directory
	 *
	 *  @param  dir  name of remote directory to
	 *               create
	 */
	public void mkdir(String dir) throws IOException, FTPException;

	/**
	 *  Change the remote working directory to
	 *  that supplied
	 *
	 *  @param  dir  name of remote directory to
	 *               change to
	 */
	public void chdir(String dir) throws IOException, FTPException;
    
    /**
     *  Change the remote working directory to
     *  the parent directory
     */
    public void cdup() throws IOException, FTPException;

	/**
	 *  Get modification time for a remote file. For accurate
     *  modification times (e.g. to the second) this method is to
     *  be preferred over @see #dirDetails(java.lang.String) which
     *  parses a listing returned by the server. The time zone is UTC.
	 *
	 *  @param    remoteFile   name of remote file
	 */
	public Date modtime(String remoteFile) throws IOException,
			FTPException;
	
	/**
     * Set the last modified time (UTC) for the supplied file. This is 
     * not supported by all servers.
     * 
     * @param path    the path to the file/directory on the remote server
     * @param modTime   the time stamp to set the modified time to in UTC
     * @return Date that it has been set to (UTC)
     * @throws IOException
     * @throws FTPException
     */
    public void setModTime(String path, Date modTime) throws IOException, FTPException;

	/**
	 *  Get the current remote working directory
	 *
	 *  @return   the current working directory
	 */
	public String pwd() throws IOException, FTPException;
    
    /**
     *  Tries to keep the current connection alive by 
     *  some means, usually by sending an innocuous commmand.
     */
    public void keepAlive() throws IOException, FTPException;

	/**
	 *  Quit the FTP session
	 *
	 */
	public void quit() throws IOException, FTPException;
    
    /**
     *  Quit the FTP session immediately. If a transfer is underway
     *  it will be terminated.
     *
     */
    public void quitImmediately() throws IOException, FTPException; 
    
}