Package com.enterprisedt.net.ftp

Interface FTPClientInterface

All Known Subinterfaces:
ProFTPClientInterface
All Known Implementing Classes:
FTPClient, ProFTPClient, SSHFTPClient, SSLFTPClient
public interface FTPClientInterface
Defines operations in common with a number of FTP implementations.
Version:
$Revision$
Author:
Hans Andersen

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancelResume()
    Cancel the resume.
    void
    cancelTransfer()
    Cancels the current transfer.
    void
    cdup()
    Change the remote working directory to the parent directory
    void
    chdir(String dir)
    Change the remote working directory to that supplied
    void
    connect()
    Connects to the server at the address and port number defined in the constructor.
    boolean
    connected()
    Is the client currently connected?
    void
    delete(String remoteFile)
    Delete the specified remote file
    String[]
    dir()
    List current directory's contents as an array of strings of filenames.
    String[]
    dir(String dirname)
    List a directory's contents as an array of strings of filenames.
    String[]
    dir(String dirname, boolean full)
    List a directory's contents as an array of strings.
    FTPFile[]
    dirDetails(String dirname)
    List a directory's contents as an array of FTPFile objects.
    void
    dirDetails(String dirname, DirectoryListCallback lister)
    List a directory's contents via a callback.
    String
    executeCommand(String command)
    Request that the remote server execute the literal command supplied.
    boolean
    exists(String remoteFile)
    Does the named file exist in the current server directory?
    void
    get(OutputStream destStream, String remoteFile)
    Get data from the FTP server.
    byte[]
    get(String remoteFile)
    Get data from the FTP server.
    void
    get(String localPath, String remoteFile)
    Get data from the FTP server.
    int
    getDeleteCount()
    Get the number of files deleted since the count was reset
    boolean
    getDetectTransferMode()
    Get the detect transfer mode
    int
    getDownloadCount()
    Get the number of files downloaded since the count was reset
    boolean
    getFileLockingEnabled()
    Determine if file locking on local downloaded files is being used or not.
    String
    getId()
    Get the identifying string for this instance
    long
    getMonitorInterval()
    Get the bytes transferred between each callback on the progress monitor
    int
    getNetworkBufferSize()
    Get the size of the network buffers (SO_SNDBUF and SO_RCVBUF).
    String
    getRemoteHost()
    Returns the IP address or name of the remote host.
    int
    getRemotePort()
    Returns the port being connected to on the remote server.
    int
    getTimeout()
    Get the timeout used for sockets and other resources
    FTPTransferType
    getType()
    Get the current transfer type
    int
    getUploadCount()
    Get the number of files uploaded since the count was reset
    void
    keepAlive()
    Tries to keep the current connection alive by some means, usually by sending an innocuous commmand.
    void
    mkdir(String dir)
    Create the specified remote working directory
    Date
    modtime(String remoteFile)
    Get modification time for a remote file.
    String
    put(byte[] bytes, String remoteFile)
    Put data onto the FTP server.
    String
    put(byte[] bytes, String remoteFile, boolean append)
    Put data onto the FTP server.
    String
    put(InputStream srcStream, String remoteFile)
    Put a stream of data onto the FTP server.
    String
    put(InputStream srcStream, String remoteFile, boolean append)
    Put a stream of data onto the FTP server.
    String
    put(String localPath, String remoteFile)
    Put a local file onto the FTP server.
    String
    put(String localPath, String remoteFile, boolean append)
    Put a local file onto the FTP server.
    String
    pwd()
    Get the current remote working directory
    void
    quit()
    Quit the FTP session
    void
    quitImmediately()
    Quit the FTP session immediately.
    void
    rename(String from, String to)
    Rename a file or directory
    void
    resetDeleteCount()
    Reset the count of deleted files to zero.
    void
    resetDownloadCount()
    Reset the count of downloaded files to zero.
    void
    resetUploadCount()
    Reset the count of uploaded files to zero.
    void
    resume()
    Make the next file transfer (put or get) resume.
    void
    resumeNextDownload(long offset)
    Make the next download resume at a specific point.
    void
    rmdir(String dir)
    Delete the specified remote working directory
    void
    setControlEncoding(String controlEncoding)
    Set the encoding used on the control channel.
    void
    setDetectTransferMode(boolean detectTransferMode)
    Set autodetect of filetypes on or off.
    void
    setFileLockingEnabled(boolean lockingEnabled)
    Set file locking to enabled or disabled.
    void
    setId(String id)
    Set the identifying string for this instance
    void
    setModTime(String path, Date modTime)
    Set the last modified time (UTC) for the supplied file.
    void
    setNetworkBufferSize(int networkBufferSize)
    Set the size of the network buffers (SO_SNDBUF and SO_RCVBUF).
    void
    setProgressMonitor(FTPProgressMonitor monitor)
    Set a progress monitor for callbacks.
    void
    setProgressMonitor(FTPProgressMonitor monitor, long interval)
    Set a progress monitor for callbacks.
    void
    setRemoteHost(String remoteHost)
    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.
    void
    setRemotePort(int remotePort)
    Set the port to connect to on the remote server.
    void
    setTimeout(int millis)
    Set the timeout on the underlying sockets and other resources that may be used.
    void
    setType(FTPTransferType type)
    Set the transfer type
    long
    size(String remoteFile)
    Get the size of a remote file.
    String
    system()
    Get a string representing the remote system

  • Method Details

    • getId

      String getId()
      Get the identifying string for this instance
      Returns:
      identifying string

    • setId

      void setId(String id)
      Set the identifying string for this instance
      Parameters:
      id - identifying string

    • getRemoteHost

      String getRemoteHost()
      Returns the IP address or name of the remote host.
      Returns:
      Returns the remote host.

    • setRemoteHost

      void setRemoteHost(String remoteHost) throws IOException, FTPException
      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.
      Parameters:
      remoteHost - The IP address or name of the remote host
      Throws:
      FTPException - Thrown if the client is already connected to the server.
      IOException

    • getRemotePort

      int getRemotePort()
      Returns the port being connected to on the remote server.
      Returns:
      Returns the port being connected to on the remote server.

    • setRemotePort

      void setRemotePort(int remotePort) throws FTPException
      Set the port to connect to on the remote server. Can only do this if not already connected.
      Parameters:
      remotePort - The port to use.
      Throws:
      FTPException - Thrown if the client is already connected to the server.

    • getTimeout

      int getTimeout()
      Get the timeout used for sockets and other resources
      Returns:
      timeout that is used, in milliseconds

    • setTimeout

      void setTimeout(int millis) throws IOException, FTPException
      Set the timeout on the underlying sockets and other resources that may be used. A timeout of 0 should not be used - for an infinite timeout use a large number. 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 result in an IOException being thrown. The default is 60,000 (60 seconds).
      Parameters:
      millis - The length of the timeout, in milliseconds
      Throws:
      IOException
      FTPException

    • getNetworkBufferSize

      int getNetworkBufferSize()
      Get the size of the network buffers (SO_SNDBUF and SO_RCVBUF).
      Returns:
      network buffer size

    • setNetworkBufferSize

      void setNetworkBufferSize(int networkBufferSize)
      Set the size of the network buffers (SO_SNDBUF and SO_RCVBUF).
      Parameters:
      networkBufferSize - new buffer size to set

    • setProgressMonitor

      void setProgressMonitor(FTPProgressMonitor monitor, long interval)
      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.
      Parameters:
      monitor - the monitor object
      interval - bytes transferred in between callbacks

    • setProgressMonitor

      void setProgressMonitor(FTPProgressMonitor monitor)
      Set a progress monitor for callbacks. Uses default callback interval
      Parameters:
      monitor - the monitor object

    • getMonitorInterval

      long getMonitorInterval()
      Get the bytes transferred between each callback on the progress monitor
      Returns:
      long bytes to be transferred before a callback

    • setDetectTransferMode

      void setDetectTransferMode(boolean detectTransferMode)
      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
      Parameters:
      detectTransferMode - true if detecting transfer mode, false if not

    • getDetectTransferMode

      boolean getDetectTransferMode()
      Get the detect transfer mode
      Returns:
      true if we are detecting binary and ASCII transfers from the file type

    • setFileLockingEnabled

      void setFileLockingEnabled(boolean lockingEnabled)
      Set file locking to enabled or disabled. When downloading files, by default the local file is locked for exclusive writing to prevent other processes corrupting it. Sometimes this needs to be disabled, e.g. tryLock() fails on NFS drives in versions of Java prior to 7.
      Parameters:
      lockingEnabled - true to enable locking, false to disable

    • getFileLockingEnabled

      boolean getFileLockingEnabled()
      Determine if file locking on local downloaded files is being used or not. Default is true.
      Returns:
      true if file locking is enabled, false otherwise

    • setControlEncoding

      void setControlEncoding(String controlEncoding) throws FTPException
      Set the encoding used on the control channel. Can only do this if not connected
      Parameters:
      controlEncoding - The controlEncoding to set, which is the name of a Charset
      Throws:
      FTPException
      See Also:

    • connect

      void connect() throws IOException, 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.
      FTPException - Thrown if there is an error related to the FTP protocol.

    • connected

      boolean connected()
      Is the client currently connected?
      Returns:
      true if connected, false otherwise

    • size

      long size(String remoteFile) throws IOException, FTPException
      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)
      Parameters:
      remoteFile - name or path of remote file in current directory
      Returns:
      size of file in bytes
      Throws:
      IOException
      FTPException

    • exists

      boolean exists(String remoteFile) throws IOException, FTPException
      Does the named file exist in the current server directory?
      Parameters:
      remoteFile - name of remote file
      Returns:
      true if exists, false otherwise
      Throws:
      IOException
      FTPException

    • executeCommand

      String executeCommand(String command) throws FTPException, IOException
      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.

      It is up to the user to send a sensible command.

      Parameters:
      command - command string
      Returns:
      result string by server
      Throws:
      FTPException
      IOException

    • system

      String system() throws FTPException, IOException
      Get a string representing the remote system
      Returns:
      system string
      Throws:
      FTPException
      IOException

    • getType

      FTPTransferType getType()
      Get the current transfer type
      Returns:
      the current type of the transfer, i.e. BINARY or ASCII

    • setType

      void setType(FTPTransferType type) throws IOException, FTPException
      Set the transfer type
      Parameters:
      type - the transfer type to set the server to
      Throws:
      IOException
      FTPException

    • resume

      void resume() throws 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

    • resumeNextDownload

      void resumeNextDownload(long offset) throws FTPException
      Make the next download resume at a specific point. This resume method allows the resume offset to be set explicitly for downloads. Offset bytes are skipped before downloading the file. This means you can download only the last few bytes of the file rather than the whole file, irrespective of the size of the local file. Currently resume is only supported for BINARY transfers (which is generally what it is most useful for).
      Throws:
      FTPException

    • cancelResume

      void cancelResume() throws IOException, FTPException
      Cancel the resume. Use this method if something goes wrong and the server is left in an inconsistent state
      Throws:
      IOException
      FTPException

    • cancelTransfer

      void cancelTransfer()
      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.

    • put

      String put(String localPath, String remoteFile) 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.
      Parameters:
      localPath - path of the local file
      remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server
      Returns:
      The name of the remote file - normally the name supplied, or else the unique name generated by the server.
      Throws:
      IOException
      FTPException

    • put

      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.
      Parameters:
      srcStream - input stream of data to put
      remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server
      Returns:
      The name of the remote file - normally the name supplied, or else the unique name generated by the server.
      Throws:
      IOException
      FTPException

    • put

      String put(InputStream srcStream, String remoteFile, boolean append) 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.
      Parameters:
      srcStream - input stream of data to put
      remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server
      append - true if appending, false otherwise
      Returns:
      The name of the remote file - normally the name supplied, or else the unique name generated by the server.
      Throws:
      IOException
      FTPException

    • put

      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.
      Parameters:
      bytes - array of bytes
      remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server
      Returns:
      The name of the remote file - normally the name supplied, or else the unique name generated by the server.
      Throws:
      IOException
      FTPException

    • put

      String put(byte[] bytes, 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. Allows appending if current file exists.
      Parameters:
      bytes - array of bytes
      remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server
      append - true if appending, false otherwise
      Returns:
      The name of the remote file - normally the name supplied, or else the unique name generated by the server.
      Throws:
      IOException
      FTPException

    • put

      String put(String localPath, 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.
      Parameters:
      localPath - path of the local file
      remoteFile - name of remote file in current directory, or null if a unique filename is to be generated by the server
      append - true if appending, false otherwise
      Returns:
      The name of the remote file - normally the name supplied, or else the unique name generated by the server.
      Throws:
      IOException
      FTPException

    • get

      void get(String localPath, String remoteFile) throws IOException, FTPException
      Get data from the FTP server. Uses the currently set transfer mode.
      Parameters:
      localPath - local file to put data in
      remoteFile - name of remote file in current directory
      Throws:
      IOException
      FTPException

    • get

      void get(OutputStream destStream, String remoteFile) throws IOException, FTPException
      Get data from the FTP server. Uses the currently set transfer mode.
      Parameters:
      destStream - data stream to write data to
      remoteFile - name of remote file in current directory
      Throws:
      IOException
      FTPException

    • get

      byte[] get(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.
      Parameters:
      remoteFile - name of remote file in current directory
      Throws:
      IOException
      FTPException

    • getDownloadCount

      int getDownloadCount()
      Get the number of files downloaded since the count was reset
      Returns:
      download file count

    • resetDownloadCount

      void resetDownloadCount()
      Reset the count of downloaded files to zero.

    • getUploadCount

      int getUploadCount()
      Get the number of files uploaded since the count was reset
      Returns:
      upload file count

    • resetUploadCount

      void resetUploadCount()
      Reset the count of uploaded files to zero.

    • getDeleteCount

      int getDeleteCount()
      Get the number of files deleted since the count was reset
      Returns:
      deleted file count

    • resetDeleteCount

      void resetDeleteCount()
      Reset the count of deleted files to zero.

    • dirDetails

      void dirDetails(String dirname, DirectoryListCallback lister) throws IOException, FTPException, ParseException
      List a directory's contents via a callback. The callback is notified for each directory entry, meaning they can be processed individually. It also avoids out of memory problems if the directory is huge, and an array of thousands of FTPFile objects would otherwise be returned. Most servers return an empty directory listing if a directory does not exist, and this is also what this method does. To establish whether or not a directory exists, try changing into it.
      Parameters:
      dirname - name of directory (some servers permit a filemask)
      lister - callback to be notified of errors
      Throws:
      IOException
      FTPException
      ParseException

    • dirDetails

      FTPFile[] dirDetails(String dirname) throws IOException, FTPException, ParseException
      List a directory's contents as an array of FTPFile objects. Most servers return an empty directory listing if a directory does not exist, and this is also what this method does. To establish whether or not a directory exists, try changing into it. 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).
      Parameters:
      dirname - name of directory (some servers permit a filemask)
      Returns:
      an array of FTPFile objects
      Throws:
      IOException
      FTPException
      ParseException

    • dir

      String[] dir() throws IOException, FTPException
      List current directory's contents as an array of strings of filenames. Most servers return an empty directory listing if a directory does not exist, and this is also what this method does. To establish whether or not a directory exists, try changing into it.
      Returns:
      an array of current directory listing strings
      Throws:
      IOException
      FTPException

    • dir

      String[] dir(String dirname) throws IOException, FTPException
      List a directory's contents as an array of strings of filenames. Most servers return an empty directory listing if a directory does not exist, and this is also what this method does. To establish whether or not a directory exists, try changing into it.
      Parameters:
      dirname - name of directory OR filemask
      Returns:
      an array of directory listing strings
      Throws:
      IOException
      FTPException

    • dir

      String[] dir(String dirname, boolean full) 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. Most servers return an empty directory listing if a directory does not exist, and this is also what this method does. To establish whether or not a directory exists, try changing into it.
      Parameters:
      dirname - name of directory OR filemask
      full - true if detailed listing required false otherwise
      Returns:
      an array of directory listing strings
      Throws:
      IOException
      FTPException

    • delete

      void delete(String remoteFile) throws IOException, FTPException
      Delete the specified remote file
      Parameters:
      remoteFile - name of remote file to delete
      Throws:
      IOException
      FTPException

    • rename

      void rename(String from, String to) throws IOException, FTPException
      Rename a file or directory
      Parameters:
      from - name of file or directory to rename
      to - intended name
      Throws:
      IOException
      FTPException

    • rmdir

      void rmdir(String dir) throws IOException, FTPException
      Delete the specified remote working directory
      Parameters:
      dir - name of remote directory to delete
      Throws:
      IOException
      FTPException

    • mkdir

      void mkdir(String dir) throws IOException, FTPException
      Create the specified remote working directory
      Parameters:
      dir - name of remote directory to create
      Throws:
      IOException
      FTPException

    • chdir

      void chdir(String dir) throws IOException, FTPException
      Change the remote working directory to that supplied
      Parameters:
      dir - name of remote directory to change to
      Throws:
      IOException
      FTPException

    • cdup

      void cdup() throws IOException, FTPException
      Change the remote working directory to the parent directory
      Throws:
      IOException
      FTPException

    • modtime

      Date modtime(String remoteFile) 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.
      Parameters:
      remoteFile - name of remote file
      Throws:
      IOException
      FTPException

    • setModTime

      void setModTime(String path, Date modTime) throws IOException, FTPException
      Set the last modified time (UTC) for the supplied file. This is not supported by all servers.
      Parameters:
      path - the path to the file/directory on the remote server
      modTime - the time stamp to set the modified time to in UTC
      Throws:
      IOException
      FTPException

    • pwd

      String pwd() throws IOException, FTPException
      Get the current remote working directory
      Returns:
      the current working directory
      Throws:
      IOException
      FTPException

    • keepAlive

      void keepAlive() throws IOException, FTPException
      Tries to keep the current connection alive by some means, usually by sending an innocuous commmand.
      Throws:
      IOException
      FTPException

    • quit

      void quit() throws IOException, FTPException
      Quit the FTP session
      Throws:
      IOException
      FTPException

    • quitImmediately

      void quitImmediately() throws IOException, FTPException
      Quit the FTP session immediately. If a transfer is underway it will be terminated.
      Throws:
      IOException
      FTPException