tribble.net.ftp
Class FTPClient

java.lang.Object
  extended by tribble.net.ftp.FTPClientAdapter
      extended by tribble.net.ftp.FTPClient
All Implemented Interfaces:
FTPClientI, FTPSimpleClientI
Direct Known Subclasses:
FTPSSLClient

public class FTPClient
extends FTPClientAdapter
implements FTPClientI

Simple FTP client. Allows clients to establish FTP connections, send and receive files, get remote directory listings, etc.

This is a simple, bare-bones, no-nonsense implementation, providing only the most basic FTP capabilities, and performing only minimal error checking and recovery. If your FTP server is well behaved, though, this implementation should meet the basic needs of simple FTP applications.

Usage

This is a simple program that connects to an FTP server, uploads a file, downloads a file, then closes the connection to the server:

    import tribble.net.ftp.*;

    public class MyFtpClient
    {
        public static void main(String[] args)
            throws Exception
        {
            FTPClientI  ftp = null;

            try
            {
                // Connect and login to the FTP server
                ftp = new FTPClient();
                ftp.setHost("ftp.domain.net");
                ftp.connect();
                ftp.login("userid", "password");

                // Upload (put) a text file
                ftp.setTextMode(true);
                ftp.setRemoteDir("incoming");
                ftp.putFile("file.txt", "file.txt");

                // Download (get) a binary file
                ftp.setRemoteDirUp();
                ftp.setRemoteDir("outgoing");
                ftp.setTextMode(false);
                ftp.getFile("file.dat", "file.dat");
            }
            catch (FTPException ex)
            {
                // An error occurred
                System.out.println(ex.getMessage());
                throw ex;
            }
            finally
            {
                // Close the FTP connection
                if (ftp != null)
                    ftp.disconnect();
            }
        }
    }

References

IETF RFC 959 - File Transfer Protocol (FTP)
www.ietf.org/rfc/rfc0959.txt.

Source code:
Available at: http://david.tribble.com/src/java/tribble/net/ftp/FTPClient.java
Documentation:
Available at: http://david.tribble.com/docs/tribble/net/ftp/FTPClient.html

Since:
API 1.0, 2001-04-14
Version:
API 2.0 $Revision: 1.29 $ $Date: 2010/07/12 21:18:03 $
Author:
David R. Tribble (david@tribble.com).

Copyright 2001-2010 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.


Field Summary
 
Fields inherited from class tribble.net.ftp.FTPClientAdapter
m_bufSize, m_cmdPort, m_dataPort, m_debugOut, m_hostName, m_inBytes, m_isConnected, m_isLoggedOn, m_localDir, m_outBytes, m_passiveMode, m_password, m_remoteDir, m_stop, m_textMode, m_timeOut, m_userID
 
Constructor Summary
FTPClient()
          Default constructor.
 
Method Summary
 void appendFile(java.io.InputStream in, java.lang.String dst)
          Append (send) a file from the local system to a file on the remote FTP system.
 void connect()
          Connect to the remote FTP system.
 void createDirectory(java.lang.String dir)
          Create a directory on the remote FTP system.
 void disconnect()
          Disconnect from the remote FTP system.
 void getDirectoryList(java.lang.String path, int max, java.io.OutputStream out)
          Get (receive) a directory listing from the remote FTP system.
 java.util.ArrayList<java.lang.String> getDirectoryNames(java.lang.String path, java.io.FilenameFilter filt, int max)
          Get (receive) a list of filenames in a directory on the remote FTP system.
 void getDirectoryNames(java.lang.String path, int max, java.io.OutputStream out)
          Get (receive) a list of filenames in a directory on the remote FTP system.
 void getFile(java.lang.String src, java.io.OutputStream out)
          Get (receive) a file from the remote FTP system to the local system.
 void getHelp(java.io.OutputStream out)
          Get (receive) a help listing of supported FTP commands from the remote FTP system.
 java.lang.String getRemoteDir()
          Retrieve the current working directory of the remote FTP system.
 void getStatus(java.io.OutputStream out)
          Retrieve the current status of the remote FTP system.
 void getSystemInfo(java.io.OutputStream out)
          Retrieve the identity information of the remote FTP system.
 void login(java.lang.String user, java.lang.String pwd)
          Log on to the remote FTP system.
static void main(java.lang.String[] args)
          Test driver.
 void ping()
          Ping the remote FTP system.
 void putFile(java.io.File src, java.lang.String dst)
          Put (send) a file from the local system to the remote FTP system.
 void putFile(java.io.InputStream in, java.lang.String dst)
          Put (send) a file from the local system to the remote FTP system.
 void removeDirectory(java.lang.String dir)
          Remove a directory on the remote FTP system.
 void removeFile(java.lang.String file)
          Remove a file on the remote FTP system.
 void rename(java.lang.String from, java.lang.String to)
          Rename a file or directory on the remote FTP system.
 boolean setAsciiMode(boolean flag)
          Deprecated. (since 1.26, 2007-07-26) Use setTextMode() instead.
 java.lang.String setRemoteDir(java.lang.String dir)
          Set the working directory on the remote FTP system.
 java.lang.String setRemoteDirUp()
          Set the working directory on the remote FTP system to the parent directory of the current working directory.
 boolean setTextMode(boolean flag)
          Set the transfer mode to text (ASCII) or binary.
 
Methods inherited from class tribble.net.ftp.FTPClientAdapter
appendFile, appendFile, finalize, getCommandPort, getDataPort, getDirectoryList, getDirectoryNames, getDirectoryNames, getDirectoryNames, getFile, getFile, getHost, getInputByteCount, getLocalDir, getOutputByteCount, getPassword, getTimeOut, getUserID, isAbsoluteFilename, isConnected, isLoggedIn, login, putFile, resetStop, setBufferSize, setCommandPort, setDataPort, setHost, setLocalDir, setPassive, setPassword, setTimeOut, setUserID, stop
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface tribble.net.ftp.FTPClientI
appendFile, getDirectoryList, getDirectoryNames, getFile, putFile
 
Methods inherited from interface tribble.net.ftp.FTPSimpleClientI
appendFile, getCommandPort, getDataPort, getDirectoryNames, getFile, getHost, getLocalDir, getPassword, getTimeOut, getUserID, isConnected, isLoggedIn, login, setBufferSize, setCommandPort, setDataPort, setHost, setLocalDir, setPassive, setPassword, setTimeOut, setUserID
 

Constructor Detail

FTPClient

public FTPClient()
Default constructor.

Since:
1.1, 2001-04-14
Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception
Test driver.

Usage

java tribble.net.ftp.FTPClient host port|- user|- password [-action...]

Parameters:
args - Command line arguments.
Throws:
java.lang.Exception
Since:
1.1, 2001-04-14
See Also:
FTPClientRun

connect

public void connect()
             throws java.io.IOException
Connect to the remote FTP system.

Specified by:
connect in interface FTPSimpleClientI
Specified by:
connect in class FTPClientAdapter
Throws:
java.io.IOException - Thrown if unable to connect to the remote FTP system.
Since:
1.1, 2001-04-14
See Also:
disconnect()

disconnect

public void disconnect()
Disconnect from the remote FTP system. Note that this method does not throw IOException.

Specified by:
disconnect in interface FTPSimpleClientI
Specified by:
disconnect in class FTPClientAdapter
Since:
1.1, 2001-04-14
See Also:
connect()

login

public void login(java.lang.String user,
                  java.lang.String pwd)
           throws java.io.IOException
Log on to the remote FTP system.

Specified by:
login in interface FTPClientI
Specified by:
login in class FTPClientAdapter
Parameters:
user - FTP user-ID for the remote system.
pwd - User password. This can be empty ("").
Throws:
java.io.IOException - Thrown if an error occurs.
Since:
1.2, 2006-03-15
See Also:
login(), connect()

setTextMode

public boolean setTextMode(boolean flag)
Set the transfer mode to text (ASCII) or binary. In text (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).

Specified by:
setTextMode in interface FTPSimpleClientI
Overrides:
setTextMode in class FTPClientAdapter
Parameters:
flag - If true, the transfer mode is set to text (ASCII), otherwise it is set to binary.
Returns:
The previous mode setting.
Since:
1.26, 2007-07-26

setAsciiMode

public boolean setAsciiMode(boolean flag)
Deprecated. (since 1.26, 2007-07-26) Use setTextMode() instead.

Set the transfer mode to text (ASCII) or binary.

Parameters:
flag - If true, the transfer mode is set to text (ASCII), otherwise it is set to binary.
Returns:
The previous mode setting.
Since:
1.3, 2006-03-15

ping

public void ping()
          throws java.io.IOException
Ping the remote FTP system. This sends a "NOOP" FTP command to the remote system and receives its reply.

Specified by:
ping in interface FTPClientI
Specified by:
ping in class FTPClientAdapter
Throws:
java.io.IOException - Thrown if an error occurs, e.g., the FTP connection is broken.
Since:
1.4, 2006-03-16

getSystemInfo

public void getSystemInfo(java.io.OutputStream out)
                   throws java.io.IOException
Retrieve the identity information of the remote FTP system.

Specified by:
getSystemInfo in interface FTPClientI
Specified by:
getSystemInfo in class FTPClientAdapter
Parameters:
out - Output stream to which the identification information is to be written.
Throws:
java.io.IOException - Thrown if an I/O error occurs.
FTPStoppedException - Thrown if stop() is called, which terminates the transfer (write) operation prematurely.
Since:
API 2.0, 1.29, 2010-07-12

getStatus

public void getStatus(java.io.OutputStream out)
               throws java.io.IOException
Retrieve the current status of the remote FTP system.

Specified by:
getStatus in interface FTPClientI
Specified by:
getStatus in class FTPClientAdapter
Parameters:
out - Output stream to which the status is to be written.
Throws:
java.io.IOException - Thrown if an I/O error occurs.
FTPStoppedException - Thrown if stop() is called, which terminates the transfer (write) operation prematurely.
Since:
API 2.0, 1.29, 2010-07-12

getHelp

public void getHelp(java.io.OutputStream out)
             throws java.io.IOException
Get (receive) a help listing of supported FTP commands from the remote FTP system.

Specified by:
getHelp in interface FTPClientI
Specified by:
getHelp in class FTPClientAdapter
Parameters:
out - Output stream to which the help listing is to be written.
Throws:
java.io.IOException - Thrown if an error occurs.
FTPStoppedException - Thrown if stop() is called, which terminates the transfer (write) operation prematurely.
Since:
API 2.0, 1.29, 2010-07-12

setRemoteDir

public java.lang.String setRemoteDir(java.lang.String dir)
                              throws java.io.IOException
Set the working directory on the remote FTP system.

Specified by:
setRemoteDir in interface FTPSimpleClientI
Overrides:
setRemoteDir in class FTPClientAdapter
Parameters:
dir - Remote directory name.
Returns:
The new current remote directory name.
Throws:
java.io.IOException - Thrown if an error occurs.
Since:
1.1, 2001-04-14
See Also:
setRemoteDirUp(), getRemoteDir(), setLocalDir()

setRemoteDirUp

public java.lang.String setRemoteDirUp()
                                throws java.io.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.

Specified by:
setRemoteDirUp in interface FTPSimpleClientI
Specified by:
setRemoteDirUp in class FTPClientAdapter
Returns:
The new current remote directory name.
Throws:
java.io.IOException - Thrown if an error occurs.
Since:
1.9, 2006-04-01
See Also:
getRemoteDir(), setRemoteDir(), setLocalDir()

getRemoteDir

public java.lang.String getRemoteDir()
                              throws java.io.IOException
Retrieve the current working directory of the remote FTP system.

Specified by:
getRemoteDir in interface FTPSimpleClientI
Overrides:
getRemoteDir in class FTPClientAdapter
Returns:
Remote directory name.
Throws:
java.io.IOException - Thrown if an error occurs.
Since:
1.1, 2001-04-15
See Also:
setRemoteDir(), setRemoteDirUp(), getLocalDir()

getFile

public void getFile(java.lang.String src,
                    java.io.OutputStream out)
             throws java.io.IOException
Get (receive) a file from the remote FTP system to the local system.

Specified by:
getFile in interface FTPSimpleClientI
Specified by:
getFile in class FTPClientAdapter
Parameters:
src - Remote source filename. If this does not contain a directory prefix, the current remote working directory is assumed.
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:
java.io.IOException - Thrown if the file could not be transmitted or if any other error occurs.
FTPStoppedException - Thrown if stop() is called, which terminates the transfer operation prematurely.
Since:
1.12, 2006-04-10
See Also:
getFile(), getFile(), putFile()

putFile

public void putFile(java.io.File src,
                    java.lang.String dst)
             throws java.io.IOException
Put (send) a file from the local system to the remote FTP system.

Specified by:
putFile in interface FTPSimpleClientI
Overrides:
putFile in class FTPClientAdapter
Parameters:
src - Local source filename. If this does not contain a directory prefix, the current local working directory is assumed.
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:
java.io.IOException - Thrown if the file could not be transmitted or if any other error occurs.
Since:
1.1, 2001-04-14
See Also:
putFile(), putFile(), getFile()

putFile

public void putFile(java.io.InputStream in,
                    java.lang.String dst)
             throws java.io.IOException
Put (send) a file from the local system to the remote FTP system.

Specified by:
putFile in interface FTPSimpleClientI
Specified by:
putFile in class FTPClientAdapter
Parameters:
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.
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:
java.io.IOException - Thrown if the file could not be transmitted or if any other error occurs.
FTPStoppedException - Thrown if stop() is called, which terminates the transfer operation prematurely.
Since:
1.12, 2006-04-10
See Also:
putFile(), putFile(), appendFile(), getFile()

appendFile

public void appendFile(java.io.InputStream in,
                       java.lang.String dst)
                throws java.io.IOException
Append (send) a file from the local system to a file on the remote FTP system.

Specified by:
appendFile in interface FTPSimpleClientI
Specified by:
appendFile in class FTPClientAdapter
Parameters:
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.
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:
java.io.IOException - Thrown if the file could not be transmitted or if any other error occurs.
FTPStoppedException - Thrown if stop() is called, which terminates the transfer operation prematurely.
Since:
1.25, 2007-06-30
See Also:
appendFile(), appendFile(), putFile()

getDirectoryList

public void getDirectoryList(java.lang.String path,
                             int max,
                             java.io.OutputStream out)
                      throws java.io.IOException
Get (receive) a directory listing from the remote FTP system.

Specified by:
getDirectoryList in interface FTPClientI
Specified by:
getDirectoryList in class FTPClientAdapter
Parameters:
path - The remote directory or filename to list. If this is empty (""), the current remote working directory is assumed.
max - Maximum number of filenames (output lines) to list. A value of zero (0) specifies that there is no maximum.
out - Output stream to which the directory listing is to be written.
Throws:
java.io.IOException - Thrown if an error occurs.
FTPStoppedException - Thrown if stop() is called, which terminates the listing (output) operation prematurely.
Since:
API 2.0, 1.29, 2010-07-12

getDirectoryNames

public void getDirectoryNames(java.lang.String path,
                              int max,
                              java.io.OutputStream out)
                       throws java.io.IOException
Get (receive) a list of filenames in a directory on the remote FTP system.

Specified by:
getDirectoryNames in interface FTPClientI
Specified by:
getDirectoryNames in class FTPClientAdapter
Parameters:
path - The remote directory or filename to list. If this is empty (""), the current remote working directory is assumed.
max - Maximum number of filenames to get. A value of zero (0) specifies that there is no maximum.
out - Output stream to which the directory listing is to be written.
Throws:
java.io.IOException - Thrown if an error occurs.
FTPStoppedException - Thrown if stop() is called, which terminates the listing (output) operation prematurely.
Since:
API 2.0, 1.29, 2010-07-12

getDirectoryNames

public java.util.ArrayList<java.lang.String> getDirectoryNames(java.lang.String path,
                                                               java.io.FilenameFilter filt,
                                                               int max)
                                                        throws java.io.IOException
Get (receive) a list of filenames in a directory on the remote FTP system.

Specified by:
getDirectoryNames in interface FTPSimpleClientI
Parameters:
path - The remote directory or filename to list. If this is empty (""), the current remote working directory is assumed.
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).
max - Maximum number of filenames to list. A value of zero (0) specifies that there is no maximum.
Returns:
A vector of Strings containing the filenames in the remote directory. Note that this may contain zero entries.
Throws:
java.io.IOException - Thrown if an error occurs.
FTPStoppedException - Thrown if stop() is called, which terminates the listing operation prematurely.
Since:
1.22, 2007-04-15

rename

public void rename(java.lang.String from,
                   java.lang.String to)
            throws java.io.IOException
Rename a file or directory on the remote FTP system.

Specified by:
rename in interface FTPSimpleClientI
Specified by:
rename in class FTPClientAdapter
Parameters:
from - Old (existing) remote file or directory name to rename.
to - New name to rename the remote file or directory to.
Throws:
java.io.IOException - Thrown if an error occurs.
Since:
1.4, 2006-03-17

removeFile

public void removeFile(java.lang.String file)
                throws java.io.IOException
Remove a file on the remote FTP system.

Specified by:
removeFile in interface FTPSimpleClientI
Specified by:
removeFile in class FTPClientAdapter
Parameters:
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:
java.io.IOException - Thrown if an error occurs.
Since:
1.4, 2006-03-17

createDirectory

public void createDirectory(java.lang.String dir)
                     throws java.io.IOException
Create a directory on the remote FTP system.

Specified by:
createDirectory in interface FTPSimpleClientI
Specified by:
createDirectory in class FTPClientAdapter
Parameters:
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:
java.io.IOException - Thrown if an error occurs.
Since:
1.4, 2006-03-17

removeDirectory

public void removeDirectory(java.lang.String dir)
                     throws java.io.IOException
Remove a directory on the remote FTP system.

Specified by:
removeDirectory in interface FTPSimpleClientI
Specified by:
removeDirectory in class FTPClientAdapter
Parameters:
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:
java.io.IOException - Thrown if an error occurs.
Since:
1.4, 2006-03-17