com.enterprisedt.net.ftp
Class FTPClient

java.lang.Object
  extended bycom.enterprisedt.net.ftp.FTPClient

public class FTPClient
extends java.lang.Object

Supports client-side FTP. Most common FTP operations are present in this class.

Version:
$Revision: 1.15 $
Author:
Bruce Blackshaw

Field Summary
protected  FTPControlSocket control
          Socket responsible for controlling the connection
protected  FTPDataSocket data
          Socket responsible for transferring the data
protected  FTPReply lastValidReply
          Holds the last valid reply from the server on the control socket
 
Constructor Summary
protected FTPClient()
          Default constructor for use by subclasses
  FTPClient(java.net.InetAddress remoteAddr)
          Constructor.
  FTPClient(java.net.InetAddress remoteAddr, int controlPort)
          Constructor.
  FTPClient(java.net.InetAddress remoteAddr, int controlPort, java.io.PrintWriter log, int timeout)
          Constructor.
  FTPClient(java.net.InetAddress remoteAddr, java.io.PrintWriter log, int timeout)
          Constructor.
  FTPClient(java.lang.String remoteHost)
          Constructor.
  FTPClient(java.lang.String remoteHost, int controlPort)
          Constructor.
  FTPClient(java.lang.String remoteHost, int controlPort, java.io.PrintWriter log, int timeout)
          Constructor.
  FTPClient(java.lang.String remoteHost, java.io.PrintWriter log, int timeout)
          Constructor.
 
Method Summary
 void cancelTransfer()
          Cancels the current transfer.
 void chdir(java.lang.String dir)
          Change the remote working directory to that supplied
 void debugResponses(boolean on)
          Switch debug of responses on or off
 void delete(java.lang.String remoteFile)
          Delete the specified remote file
 java.lang.String[] dir()
          List current directory's contents as an array of strings of filenames.
 java.lang.String[] dir(java.lang.String dirname)
          List a directory's contents as an array of strings of filenames.
 java.lang.String[] dir(java.lang.String dirname, boolean full)
          List a directory's contents as an array of strings.
 FTPFile[] dirDetails(java.lang.String dirname)
          List a directory's contents as an array of strings of filenames.
 void get(java.io.OutputStream destStream, java.lang.String remoteFile)
          Get data from the FTP server.
 byte[] get(java.lang.String remoteFile)
          Get data from the FTP server.
 void get(java.lang.String localPath, java.lang.String remoteFile)
          Get data from the FTP server.
 FTPReply getLastValidReply()
          Gets the latest valid reply from the server
 long getMonitorInterval()
          Get the bytes transferred between each callback on the progress monitor
 FTPTransferType getType()
          Get the current transfer type
 java.lang.String help(java.lang.String command)
          Get the help text for the specified command
protected  void initialize(FTPControlSocket control)
          Set the control socket explicitly
static void initSOCKS(java.lang.String port, java.lang.String host)
          Set up SOCKS v4/v5 proxy settings.
static void initSOCKSAuthentication(java.lang.String username, java.lang.String password)
          Set up SOCKS username and password for SOCKS username/password authentication.
 java.lang.String list(java.lang.String dirname)
          Deprecated. As of FTP 1.1, replaced by dir(String)
 java.lang.String list(java.lang.String dirname, boolean full)
          Deprecated. As of FTP 1.1, replaced by dir(String,boolean)
 void login(java.lang.String user, java.lang.String password)
          Login into an account on the FTP server.
 void mkdir(java.lang.String dir)
          Create the specified remote working directory
 java.util.Date modtime(java.lang.String remoteFile)
          Get modification time for a remote file
 void password(java.lang.String password)
          Supplies the password for a previously supplied username to log into the FTP server.
 void put(byte[] bytes, java.lang.String remoteFile)
          Put data onto the FTP server.
 void put(byte[] bytes, java.lang.String remoteFile, boolean append)
          Put data onto the FTP server.
 void put(java.io.InputStream srcStream, java.lang.String remoteFile)
          Put a stream of data onto the FTP server.
 void put(java.io.InputStream srcStream, java.lang.String remoteFile, boolean append)
          Put a stream of data onto the FTP server.
 void put(java.lang.String localPath, java.lang.String remoteFile)
          Put a local file onto the FTP server.
 void put(java.lang.String localPath, java.lang.String remoteFile, boolean append)
          Put a local file onto the FTP server.
 java.lang.String pwd()
          Get the current remote working directory
 void quit()
          Quit the FTP session
 java.lang.String quote(java.lang.String command, java.lang.String[] validCodes)
          Issue arbitrary ftp commands to the FTP server.
protected  int readChar(java.io.LineNumberReader in)
          Attempts to read a single character from the given InputStream.
protected  int readChunk(java.io.BufferedInputStream in, byte[] chunk, int chunksize)
          Attempts to read a specified number of bytes from the given InputStream and place it in the given byte-array.
protected  java.lang.String readLine(java.io.LineNumberReader in)
          Attempts to read a single line from the given InputStream.
 void rename(java.lang.String from, java.lang.String to)
          Rename a file or directory
 void rmdir(java.lang.String dir)
          Delete the specified remote working directory
 void setConnectMode(FTPConnectMode mode)
          Set the connect mode
 void setLogStream(java.io.PrintWriter log)
          Set the logging stream, replacing stdout
 void setProgressMonitor(FTPProgressMonitor monitor)
          Set a progress monitor for callbacks.
 void setProgressMonitor(FTPProgressMonitor monitor, long interval)
          Set a progress monitor for callbacks.
 void setTimeout(int millis)
          Set the TCP timeout on the underlying socket.
 void setType(FTPTransferType type)
          Set the transfer type
 boolean site(java.lang.String command)
          Run a site-specific command on the server.
 long size(java.lang.String remoteFile)
          Get the size of a remote file.
 java.lang.String system()
          Get the type of the OS at the server
 void user(java.lang.String user)
          Supply the user name to log into an account on the FTP server.
 void validateTransfer()
          Validate that the put() or get() was successful
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

control

protected FTPControlSocket control
Socket responsible for controlling the connection


data

protected FTPDataSocket data
Socket responsible for transferring the data


lastValidReply

protected FTPReply lastValidReply
Holds the last valid reply from the server on the control socket

Constructor Detail

FTPClient

public FTPClient(java.lang.String remoteHost)
          throws java.io.IOException,
                 FTPException
Constructor. Creates the control socket

Parameters:
remoteHost - the remote hostname

FTPClient

public FTPClient(java.lang.String remoteHost,
                 int controlPort)
          throws java.io.IOException,
                 FTPException
Constructor. Creates the control socket

Parameters:
remoteHost - the remote hostname
controlPort - port for control stream

FTPClient

public FTPClient(java.net.InetAddress remoteAddr)
          throws java.io.IOException,
                 FTPException
Constructor. Creates the control socket

Parameters:
remoteAddr - the address of the remote host

FTPClient

public FTPClient(java.net.InetAddress remoteAddr,
                 int controlPort)
          throws java.io.IOException,
                 FTPException
Constructor. Creates the control socket. Allows setting of control port (normally set by default to 21).

Parameters:
remoteAddr - the address of the remote host
controlPort - port for control stream

FTPClient

public FTPClient(java.lang.String remoteHost,
                 java.io.PrintWriter log,
                 int timeout)
          throws java.io.IOException,
                 FTPException
Constructor. Creates the control socket

Parameters:
remoteHost - the remote hostname
timeout - the length of the timeout, in milliseconds

FTPClient

public FTPClient(java.lang.String remoteHost,
                 int controlPort,
                 java.io.PrintWriter log,
                 int timeout)
          throws java.io.IOException,
                 FTPException
Constructor. Creates the control socket

Parameters:
remoteHost - the remote hostname
controlPort - port for control stream
timeout - the length of the timeout, in milliseconds

FTPClient

public FTPClient(java.net.InetAddress remoteAddr,
                 java.io.PrintWriter log,
                 int timeout)
          throws java.io.IOException,
                 FTPException
Constructor. Creates the control socket

Parameters:
remoteAddr - the address of the remote host
timeout - the length of the timeout, in milliseconds

FTPClient

public FTPClient(java.net.InetAddress remoteAddr,
                 int controlPort,
                 java.io.PrintWriter log,
                 int timeout)
          throws java.io.IOException,
                 FTPException
Constructor. Creates the control socket. Allows setting of control port (normally set by default to 21).

Parameters:
remoteAddr - the address of the remote host
controlPort - port for control stream
timeout - the length of the timeout, in milliseconds

FTPClient

protected FTPClient()
             throws java.io.IOException,
                    FTPException
Default constructor for use by subclasses

Method Detail

initialize

protected void initialize(FTPControlSocket control)
Set the control socket explicitly

Parameters:
control - control socket reference

setTimeout

public void setTimeout(int millis)
                throws java.io.IOException
Set the TCP timeout on the underlying socket. If a timeout is set, then any operation which takes longer than the timeout value will be killed with a java.io.InterruptedException. We set both the control and data connections

Parameters:
millis - The length of the timeout, in milliseconds
Throws:
java.io.IOException

setConnectMode

public void setConnectMode(FTPConnectMode mode)
Set the connect mode

Parameters:
mode - ACTIVE or PASV mode

setProgressMonitor

public 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.

Parameters:
monitor - the monitor object
interval - bytes transferred in between callbacks

setProgressMonitor

public void setProgressMonitor(FTPProgressMonitor monitor)
Set a progress monitor for callbacks. Uses default callback interval

Parameters:
monitor - the monitor object

getMonitorInterval

public long getMonitorInterval()
Get the bytes transferred between each callback on the progress monitor

Returns:
long bytes to be transferred before a callback

cancelTransfer

public void cancelTransfer()
Cancels the current transfer. Must be 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


login

public void login(java.lang.String user,
                  java.lang.String password)
           throws java.io.IOException,
                  FTPException
Login into an account on the FTP server. This call completes the entire login process

Parameters:
user - user name
password - user's password
Throws:
java.io.IOException
FTPException

user

public void user(java.lang.String user)
          throws java.io.IOException,
                 FTPException
Supply the user name to log into an account on the FTP server. Must be followed by the password() method - but we allow for

Parameters:
user - user name
Throws:
java.io.IOException
FTPException

password

public void password(java.lang.String password)
              throws java.io.IOException,
                     FTPException
Supplies the password for a previously supplied username to log into the FTP server. Must be preceeded by the user() method

Parameters:
password - The password.
Throws:
java.io.IOException
FTPException

initSOCKS

public static void initSOCKS(java.lang.String port,
                             java.lang.String host)
Set up SOCKS v4/v5 proxy settings. This can be used if there is a SOCKS proxy server in place that must be connected thru. Note that setting these properties directs all TCP sockets in this JVM to the SOCKS proxy

Parameters:
port - SOCKS proxy port
host - SOCKS proxy hostname

initSOCKSAuthentication

public static void initSOCKSAuthentication(java.lang.String username,
                                           java.lang.String password)
Set up SOCKS username and password for SOCKS username/password authentication. Often, no authentication will be required but the SOCKS server may be configured to request these.

Parameters:
username - the SOCKS username
password - the SOCKS password

quote

public java.lang.String quote(java.lang.String command,
                              java.lang.String[] validCodes)
                       throws java.io.IOException,
                              FTPException
Issue arbitrary ftp commands to the FTP server.

Parameters:
command - ftp command to be sent to server
validCodes - valid return codes for this command
Returns:
the text returned by the FTP server
Throws:
java.io.IOException
FTPException

size

public long size(java.lang.String remoteFile)
          throws java.io.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:
java.io.IOException
FTPException

put

public void put(java.lang.String localPath,
                java.lang.String remoteFile)
         throws java.io.IOException,
                FTPException
Put a local file onto the FTP server. It is placed in the current directory.

Parameters:
localPath - path of the local file
remoteFile - name of remote file in current directory
Throws:
java.io.IOException
FTPException

put

public void put(java.io.InputStream srcStream,
                java.lang.String remoteFile)
         throws java.io.IOException,
                FTPException
Put a stream of data onto the FTP server. It is placed in the current directory.

Parameters:
srcStream - input stream of data to put
remoteFile - name of remote file in current directory
Throws:
java.io.IOException
FTPException

put

public void put(java.lang.String localPath,
                java.lang.String remoteFile,
                boolean append)
         throws java.io.IOException,
                FTPException
Put a local file onto the FTP server. It is placed in the current directory. Allows appending if current file exists

Parameters:
localPath - path of the local file
remoteFile - name of remote file in current directory
append - true if appending, false otherwise
Throws:
java.io.IOException
FTPException

put

public void put(java.io.InputStream srcStream,
                java.lang.String remoteFile,
                boolean append)
         throws java.io.IOException,
                FTPException
Put a stream of data onto the FTP server. It is placed in the current directory. Allows appending if current file exists

Parameters:
srcStream - input stream of data to put
remoteFile - name of remote file in current directory
append - true if appending, false otherwise
Throws:
java.io.IOException
FTPException

validateTransfer

public void validateTransfer()
                      throws java.io.IOException,
                             FTPException
Validate that the put() or get() was successful

Throws:
java.io.IOException
FTPException

put

public void put(byte[] bytes,
                java.lang.String remoteFile)
         throws java.io.IOException,
                FTPException
Put data onto the FTP server. It is placed in the current directory.

Parameters:
bytes - array of bytes
remoteFile - name of remote file in current directory
Throws:
java.io.IOException
FTPException

put

public void put(byte[] bytes,
                java.lang.String remoteFile,
                boolean append)
         throws java.io.IOException,
                FTPException
Put data onto the FTP server. It is placed in the current directory. Allows appending if current file exists

Parameters:
bytes - array of bytes
remoteFile - name of remote file in current directory
append - true if appending, false otherwise
Throws:
java.io.IOException
FTPException

get

public void get(java.lang.String localPath,
                java.lang.String remoteFile)
         throws java.io.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:
java.io.IOException
FTPException

get

public void get(java.io.OutputStream destStream,
                java.lang.String remoteFile)
         throws java.io.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:
java.io.IOException
FTPException

get

public byte[] get(java.lang.String remoteFile)
           throws java.io.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:
java.io.IOException
FTPException

site

public boolean site(java.lang.String command)
             throws java.io.IOException,
                    FTPException
Run a site-specific command on the server. Support for commands is dependent on the server

Parameters:
command - the site command to run
Returns:
true if command ok, false if command not implemented
Throws:
java.io.IOException
FTPException

list

public java.lang.String list(java.lang.String dirname)
                      throws java.io.IOException,
                             FTPException
Deprecated. As of FTP 1.1, replaced by dir(String)

List a directory's contents

Parameters:
dirname - the name of the directory (not a file mask)
Returns:
a string containing the line separated directory listing
Throws:
java.io.IOException
FTPException

list

public java.lang.String list(java.lang.String dirname,
                             boolean full)
                      throws java.io.IOException,
                             FTPException
Deprecated. As of FTP 1.1, replaced by dir(String,boolean)

List a directory's contents as one string. A detailed listing is available, otherwise just filenames are provided. The detailed listing varies in details depending on OS and FTP server.

Parameters:
dirname - the name of the directory(not a file mask)
full - true if detailed listing required false otherwise
Returns:
a string containing the line separated directory listing
Throws:
java.io.IOException
FTPException

dirDetails

public FTPFile[] dirDetails(java.lang.String dirname)
                     throws java.io.IOException,
                            FTPException,
                            java.text.ParseException
List a directory's contents as an array of strings of filenames. Should work for Windows and most Unix FTP servers - let us know about unusual formats (support@enterprisedt.com)

Parameters:
dirname - name of directory(not a file mask)
Returns:
an array of FTPFile objects
Throws:
java.io.IOException
FTPException
java.text.ParseException

dir

public java.lang.String[] dir()
                       throws java.io.IOException,
                              FTPException
List current directory's contents as an array of strings of filenames.

Returns:
an array of current directory listing strings
Throws:
java.io.IOException
FTPException

dir

public java.lang.String[] dir(java.lang.String dirname)
                       throws java.io.IOException,
                              FTPException
List a directory's contents as an array of strings of filenames.

Parameters:
dirname - name of directory(not a file mask)
Returns:
an array of directory listing strings
Throws:
java.io.IOException
FTPException

dir

public java.lang.String[] dir(java.lang.String dirname,
                              boolean full)
                       throws java.io.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

Parameters:
dirname - name of directory (not a file mask)
full - true if detailed listing required false otherwise
Returns:
an array of directory listing strings
Throws:
java.io.IOException
FTPException

readChunk

protected int readChunk(java.io.BufferedInputStream in,
                        byte[] chunk,
                        int chunksize)
                 throws java.io.IOException
Attempts to read a specified number of bytes from the given InputStream and place it in the given byte-array. The purpose of this method is to permit subclasses to execute any additional code necessary when performing this operation.

Parameters:
in - The InputStream to read from.
chunk - The byte-array to place read bytes in.
chunksize - Number of bytes to read.
Returns:
Number of bytes actually read.
Throws:
java.io.IOException - Thrown if there was an error while reading.

readChar

protected int readChar(java.io.LineNumberReader in)
                throws java.io.IOException
Attempts to read a single character from the given InputStream. The purpose of this method is to permit subclasses to execute any additional code necessary when performing this operation.

Parameters:
in - The LineNumberReader to read from.
Returns:
The character read.
Throws:
java.io.IOException - Thrown if there was an error while reading.

readLine

protected java.lang.String readLine(java.io.LineNumberReader in)
                             throws java.io.IOException
Attempts to read a single line from the given InputStream. The purpose of this method is to permit subclasses to execute any additional code necessary when performing this operation.

Parameters:
in - The LineNumberReader to read from.
Returns:
The string read.
Throws:
java.io.IOException - Thrown if there was an error while reading.

getLastValidReply

public FTPReply getLastValidReply()
Gets the latest valid reply from the server

Returns:
reply object encapsulating last valid server response

debugResponses

public void debugResponses(boolean on)
Switch debug of responses on or off

Parameters:
on - true if you wish to have responses to the log stream, false otherwise

setLogStream

public void setLogStream(java.io.PrintWriter log)
Set the logging stream, replacing stdout

Parameters:
log - the new logging stream

getType

public FTPTransferType getType()
Get the current transfer type

Returns:
the current type of the transfer, i.e. BINARY or ASCII

setType

public void setType(FTPTransferType type)
             throws java.io.IOException,
                    FTPException
Set the transfer type

Parameters:
type - the transfer type to set the server to
Throws:
java.io.IOException
FTPException

delete

public void delete(java.lang.String remoteFile)
            throws java.io.IOException,
                   FTPException
Delete the specified remote file

Parameters:
remoteFile - name of remote file to delete
Throws:
java.io.IOException
FTPException

rename

public void rename(java.lang.String from,
                   java.lang.String to)
            throws java.io.IOException,
                   FTPException
Rename a file or directory

Parameters:
from - name of file or directory to rename
to - intended name
Throws:
java.io.IOException
FTPException

rmdir

public void rmdir(java.lang.String dir)
           throws java.io.IOException,
                  FTPException
Delete the specified remote working directory

Parameters:
dir - name of remote directory to delete
Throws:
java.io.IOException
FTPException

mkdir

public void mkdir(java.lang.String dir)
           throws java.io.IOException,
                  FTPException
Create the specified remote working directory

Parameters:
dir - name of remote directory to create
Throws:
java.io.IOException
FTPException

chdir

public void chdir(java.lang.String dir)
           throws java.io.IOException,
                  FTPException
Change the remote working directory to that supplied

Parameters:
dir - name of remote directory to change to
Throws:
java.io.IOException
FTPException

modtime

public java.util.Date modtime(java.lang.String remoteFile)
                       throws java.io.IOException,
                              FTPException
Get modification time for a remote file

Parameters:
remoteFile - name of remote file
Returns:
modification time of file as a date
Throws:
java.io.IOException
FTPException

pwd

public java.lang.String pwd()
                     throws java.io.IOException,
                            FTPException
Get the current remote working directory

Returns:
the current working directory
Throws:
java.io.IOException
FTPException

system

public java.lang.String system()
                        throws java.io.IOException,
                               FTPException
Get the type of the OS at the server

Returns:
the type of server OS
Throws:
java.io.IOException
FTPException

help

public java.lang.String help(java.lang.String command)
                      throws java.io.IOException,
                             FTPException
Get the help text for the specified command

Parameters:
command - name of the command to get help on
Returns:
help text from the server for the supplied command
Throws:
java.io.IOException
FTPException

quit

public void quit()
          throws java.io.IOException,
                 FTPException
Quit the FTP session

Throws:
java.io.IOException
FTPException


Copyright (c) 2001-2004 Enterprise Distributed Technologies Ltd. All Rights Reserved.