ftpclientinterface.java

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

/**
*
*  edtFTPj
*
*  Copyright (C) 2000-2003  Enterprise Distributed Technologies Ltd
*
*  www.enterprisedt.com
*
*  This library is free software; you can redistribute it and/or
*  modify it under the terms of the GNU Lesser General Public
*  License as published by the Free Software Foundation; either
*  version 2.1 of the License, or (at your option) any later version.
*
*  This library 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
*  Lesser General Public License for more details.
*
*  You should have received a copy of the GNU Lesser General Public
*  License along with this library; if not, write to the Free Software
*  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*
 *  Bug fixes, suggestions and comments should be should posted on 
 *  http://www.enterprisedt.com/forums/index.php
*
*  Change Log:
*
*        $Log: FTPClientInterface.java,v $
*        Revision 1.21  2008-05-02 07:41:30  bruceb
*        setModTime added
*
*        Revision 1.20  2008-04-17 04:51:04  bruceb
*        add setControlEncoding
*
*        Revision 1.19  2008-03-13 04:23:29  bruceb
*        changed to system()
*
*        Revision 1.18  2008-03-13 00:21:57  bruceb
*        added executeCommand
*
*        Revision 1.17  2007-08-07 04:45:04  bruceb
*        added counts for transfers and deletes
*
*        Revision 1.16  2007/03/19 22:06:57  bruceb
*        add connected()
*
*        Revision 1.15  2007/02/07 23:02:55  bruceb
*        added keepAlive() & quitImmediately()
*
*        Revision 1.14  2007/02/01 05:10:32  bruceb
*        enhance comment
*
*        Revision 1.13  2007/01/15 23:04:51  bruceb
*        minor comment change
*
*        Revision 1.12  2007/01/10 02:38:25  bruceb
*        added getId() and modified gets to return filename
*
*        Revision 1.11  2006/11/14 11:40:42  bruceb
*        fix comment
*
*        Revision 1.10  2006/09/11 12:34:00  bruceb
*        added exists() method
*
*        Revision 1.9  2006/02/09 09:02:15  bruceb
*        fixed comment re dirname
*
*        Revision 1.8  2005/11/15 21:02:14  bruceb
*        augment javadoc
*
*        Revision 1.7  2005/11/10 19:45:18  bruceb
*        added resume & cancel methods
*
*        Revision 1.6  2005/11/09 21:15:19  bruceb
*        added set/get for autodetect
*
*        Revision 1.5  2005/10/10 20:42:56  bruceb
*        append now in FTPClientInterface
*
*        Revision 1.4  2005/07/11 21:14:58  bruceb
*        add set/get transfer type
*
*        Revision 1.3  2005/06/16 21:41:34  hans
*        Added RemoteHost and RemotePort accessors as well as connect() method.
*
*        Revision 1.2  2005/06/03 11:26:25  bruceb
*        comment change
*/

package com.enterprisedt.net.ftp;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.text.ParseException;
import java.util.Date;

/**
 * Defines operations in common with a number of FTP implementations.
 * 
 * @author     Hans Andersen
 * @version    $Revision: 1.21 $
 */
public interface FTPClientInterface {
   	
    /**
     * Get the identifying string for this instance
     * 
     * @return identifying string
     */
    public String getId();
    
    /**
     * Set the identifying string for this instance
     * 
     * @param id    identifying string
     */
    public void setId(String id);
    
    /**
     * Returns the IP address or name of the remote host.
     * 
     * @return Returns the remote host.
     */
    public String getRemoteHost();

    /**
     * Set the IP address or name of the remote host
     * 
     * This may only be done if the client is not already connected to the server.
     * 
     * @param remoteHost The IP address or name of the remote host
     * @throws FTPException Thrown if the client is already connected to the server.
     */
    public void setRemoteHost(String remoteHost) throws IOException, FTPException;
    
    /**
     * Returns the port being connected to on the remote server. 
     * 
     * @return Returns the port being connected to on the remote server. 
     */
    public int getRemotePort();
    
    /** 
     * Set the port to connect to on the remote server. Can only do this if
     * not already connected.
     * 
     * @param remotePort The port to use. 
     * @throws FTPException Thrown if the client is already connected to the server.
     */
    public void setRemotePort(int remotePort) throws FTPException;

    /**
     *   Get the TCP timeout on the underlying socket(s).
     * 
     *   A value of 0 (the default) means that there
     *   are no timeouts.
     *  
     *  @return timeout that is used, in milliseconds
     */
    public int getTimeout();
    
	/**
	 *   Set the TCP timeout on the underlying socket(s).
	 *
	 *   Timeouts should be set before connections are made.
	 *   If a timeout is set, then any operation which
	 *   takes longer than the timeout value will be
	 *   killed with a java.io.InterruptedException.
	 *   The default is 0 meaning that the connection
	 *   never times out.  
	 *
	 *   @param millis The length of the timeout, in milliseconds
	 */
	public void setTimeout(int millis) throws IOException, FTPException;

	/**
	 *  Set a progress monitor for callbacks. The bytes transferred in
	 *  between callbacks is only indicative. In many cases, the data is
	 *  read in chunks, and if the interval is set to be smaller than the
	 *  chunk size, the callback will occur after after chunk transfer rather
	 *  than the interval. Depending on the implementation, the chunk size can
     *  be as large as 64K.
	 *
	 *  @param  monitor   the monitor object
	 *  @param  interval  bytes transferred in between callbacks
	 */
	public void setProgressMonitor(FTPProgressMonitor monitor,
			long interval);

	/**
	 *  Set a progress monitor for callbacks. Uses default callback
	 *  interval
	 *
	 *  @param  monitor   the monitor object
	 */
	public void setProgressMonitor(FTPProgressMonitor monitor);

	/**
	 *  Get the bytes transferred between each callback on the
	 *  progress monitor
	 * 
	 * @return long     bytes to be transferred before a callback
	 */
	public long getMonitorInterval();
    
    /**
     * Set autodetect of filetypes on or off. If on, the transfer mode is
     * switched from ASCII to binary and vice versa depending on the extension
     * of the file. After the transfer, the mode is always returned to what it
     * was before the transfer was performed. The default is off.
     * 
     * If the filetype is unknown, the transfer mode is unchanged
     * 
     * @param detectTransferMode    true if detecting transfer mode, false if not
     */
    public void setDetectTransferMode(boolean detectTransferMode);
    
    /**
     * Get the detect transfer mode
     * 
     * @return true if we are detecting binary and ASCII transfers from the file type
     */
    public boolean getDetectTransferMode();   
    
    /**
     * Set the encoding used on the control channel. Can only do this if
     * not connected
     * 
     * @param controlEncoding The controlEncoding to set, which is the name of a Charset
     * @see java.nio.charset.Charset
     * @throws FTPException
     */
    public void setControlEncoding(String controlEncoding) throws FTPException;
    
    
    /**
     * Connects to the server at the address and port number defined
     * in the constructor.
     * 
     * @throws IOException Thrown if there is a TCP/IP-related error.
     * @throws FTPException Thrown if there is an error related to the FTP protocol. 
     */
    public void connect() throws IOException, FTPException;
    
    /**
     * Is the client currently connected?
     * 
     * @return true if connected, false otherwise
     */
    public boolean connected();

	/**
	 *  Get the size of a remote file. This is not a standard FTP command, it
	 *  is defined in "Extensions to FTP", a draft RFC 
	 *  (draft-ietf-ftpext-mlst-16.txt)
	 *
	 *  @param  remoteFile  name or path of remote file in current directory
	 *  @return size of file in bytes      
	 */
	public long size(String remoteFile) throws IOException,
	    FTPException;
    
    /**
     * Does the named file exist in the current server directory?
     * 
     * @param remoteFile        name of remote file
     * @return true if exists, false otherwise
     * @throws IOException
     * @throws FTPException
     */
    public boolean exists(String remoteFile) throws IOException,
        FTPException;
    
    /**
     * Request that the remote server execute the literal command supplied. 
     * In FTP and SFTP, this might be a SITE command, while in SFTP it might
     * be a shell command.
     * <p>
     * It is up to the user to send a sensible command. 
     *  
     * @param command   command string
     * @return result string by server
     * @throws FTPException
     * @throws IOException
     */
    public String executeCommand(String command) 
        throws FTPException, IOException;
    
    /**
     * Get a string representing the remote system
     * 
     * @return system string
     * @throws FTPException
     * @throws IOException
     */
    public String system() 
        throws FTPException, IOException;
    
    /**
     *  Get the current transfer type
     *
     *  @return  the current type of the transfer,
     *           i.e. BINARY or ASCII
     */
    public FTPTransferType getType();
    
    /**
     *  Set the transfer type
     *
     *  @param  type  the transfer type to
     *                set the server to
     */
    public void setType(FTPTransferType type)
        throws IOException, FTPException; 
    
    /**
     * Make the next file transfer (put or get) resume. For puts(), the
     * bytes already transferred are skipped over, while for gets(), if 
     * writing to a file, it is opened in append mode, and only the bytes
     * required are transferred.
     * 
     * Currently resume is only supported for BINARY transfers (which is
     * generally what it is most useful for).
     * 
     * @throws FTPException
     */
    public void resume() throws FTPException;
    
    /**
     * Cancel the resume. Use this method if something goes wrong
     * and the server is left in an inconsistent state
     * 
     * @throws IOException
     * @throws FTPException
     */
    public void cancelResume() throws IOException, FTPException;