gnu.inet.ftp
Class FtpClientProtocol

java.lang.Object
  |
  +--gnu.inet.ftp.FtpClientProtocol

Direct Known Subclasses:

FtpClient, HylaFAXClientProtocol

public class FtpClientProtocol

extends java.lang.Object

This is the core implementation of the FTP client protocol, RFC0959. You should be able to find the document via searches on the World Wide Web. At the time of this writing, RFCs could be found at www.faqs.org.

The purpose of this class is to implement the FTP client protocol as simply and straight-forward as possible.

This package was started as an implementation of the HylaFAX client protocol so the features that overlap with the HylaFAX protocol will be the first implemented and most tested.

Method names are not my choosing for the most part. They have been largely pulled straight from the protocol and man pages. I expect that convenience classes and methods, with more developer friendly names will be built on top of this raw protocol implementation as time passes.

Most developers should use the higher-level FtpClient to perform some actions rather than this class directly.

Version:

$Id: FtpClientProtocol.java,v 1.5 2006/01/20 03:30:01 sjardine Exp $

Field Summary

static int	DEFAULT_PORT default FTP server port.
protected char	fileType
protected java.lang.String	greeting
protected java.io.BufferedReader	istream
static java.lang.String	MDTM_TIME_FORMAT1
static java.lang.String	MDTM_TIME_FORMAT2
static char	MODE_BLOCK data transfer mode is BLOCK mode
static char	MODE_COMPRESSED data transfer mode is COMPRESSED, as in UNIX compress.
static char	MODE_STREAM data transfer mode is STREAM
static char	MODE_ZLIB data transfer mode is ZLIB, as in zlib compression.
protected java.io.OutputStreamWriter	ostream
protected int	port
protected java.net.Socket	sock
static char	STRU_FILE the file structure is FILE.
static char	STRU_PAGE the file structure is PAGE based.
static char	STRU_RECORD the file structure is RECORD based.
static char	STRU_TIFF the file structure is TIFF.
static char	TYPE_ASCII the file type is ASCII
static char	TYPE_EBCDIC the file type is EBCDIC
static char	TYPE_IMAGE the file type is an 'image'.
static char	TYPE_LOCAL the file type is a local type

Constructor Summary

FtpClientProtocol()
default constructor.

Method Summary

void	abor() abort the last command
void	abor(java.lang.String modem) abort the last command on the given modem.
void	cdup() change to parent of current working directory
protected void	connect(java.lang.String host, int portnumber) connect to the given host at the given port number.
void	cwd(java.lang.String value) change current working directory
void	dele(java.lang.String pathname) delete the given file.
boolean	getDebug() Returns true if ConsoleLogger is in debug mode.
java.lang.String	getGreeting()
java.net.InetAddress	getInetAddress() get the local ip address of the control connection socket.
char	getType() Return the file type for transfer.
long	idle() get the current idle timeout in seconds
void	idle(long timeout) set the idle timeout value to the given number of seconds
void	list() get list of files in current directory.
void	list(java.lang.String path) get a list of files in a directory.
java.util.Date	mdtm(java.lang.String pathname) Returns the last modified time of the given file.
void	mode(char value) set the data transfer mode.
void	nlst() get name list of files in directory.
void	nlst(java.lang.String path) get name list of files in directory.
void	noop() perform server No Operation could be used as a keep-alive
void	open() open a connection to the localhost on the default port
void	open(java.lang.String host) open a connection to a given server at default port this is an alias for connect()
void	open(java.lang.String host, int portnumber) open a connection to a given server and port this is an alias for connect()
void	pass(java.lang.String password) send the password for this username and session
PassiveParameters	pasv() prepare for server-to-server transfer (passive mode)
void	port(java.net.InetAddress address, int port) tell the server which address/port we will listen on
java.lang.String	pwd() return current directory
void	quit() end session
protected java.lang.String	readResponse(java.io.BufferedReader input) read a (multi-line) response
void	retr(java.lang.String path) retrieve the given file
void	rnfr(java.lang.String pathname) Specifies a file to be renamed.
void	rnto(java.lang.String pathname) Renames a previously specified file to the given name.
void	setDebug(boolean value) Sets the ConsoleLogger's debug output.
long	size(java.lang.String pathname) Returns the size (in bytes) of the given regular file.
java.util.Vector	stat() Returns the server status message.
java.util.Vector	stat(java.lang.String path) Returns the status of the named file or directory.
void	stor(java.io.InputStream in, java.lang.String pathname) store a file.
java.lang.String	stot(java.io.InputStream data) store temp file, the file is stored in a uniquely named file on the server.
java.lang.String	stou(java.io.InputStream in) store a file with a unique name.
void	stru(char value) set the file structure.
java.lang.String	syst() get system type returns the string that the server sends (not sure how to handle it yet) on a Debian GNU/Linux 2.1 (slink) system, the result string is: "UNIX Type: L8 Version: SVR4"
void	type(char value) Set the file type for transfer.
boolean	user(java.lang.String username) send the user name for this session

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

sock

protected java.net.Socket sock

port

protected int port

istream

protected java.io.BufferedReader istream

ostream

protected java.io.OutputStreamWriter ostream

greeting

protected java.lang.String greeting

fileType

protected char fileType

DEFAULT_PORT

public static int DEFAULT_PORT

default FTP server port.

TYPE_ASCII

public static final char TYPE_ASCII

the file type is ASCII

TYPE_EBCDIC

public static final char TYPE_EBCDIC

the file type is EBCDIC

TYPE_IMAGE

public static final char TYPE_IMAGE

the file type is an 'image'. the file is binary data.

TYPE_LOCAL

public static final char TYPE_LOCAL

the file type is a local type

MODE_STREAM

public static final char MODE_STREAM

data transfer mode is STREAM

MODE_BLOCK

public static final char MODE_BLOCK

data transfer mode is BLOCK mode

MODE_COMPRESSED

public static final char MODE_COMPRESSED

data transfer mode is COMPRESSED, as in UNIX compress.

MODE_ZLIB

public static final char MODE_ZLIB

data transfer mode is ZLIB, as in zlib compression.

STRU_FILE

public static final char STRU_FILE

the file structure is FILE.

STRU_RECORD

public static final char STRU_RECORD

the file structure is RECORD based.

STRU_PAGE

public static final char STRU_PAGE

the file structure is PAGE based.

STRU_TIFF

public static final char STRU_TIFF

the file structure is TIFF.

MDTM_TIME_FORMAT1

public static final java.lang.String MDTM_TIME_FORMAT1

MDTM_TIME_FORMAT2

public static final java.lang.String MDTM_TIME_FORMAT2

Constructor Detail

FtpClientProtocol

public FtpClientProtocol()

default constructor. sets up the initial class state.

Method Detail

getInetAddress

public java.net.InetAddress getInetAddress()

get the local ip address of the control connection socket.

Returns:

control connection ip address

open

public void open(java.lang.String host,
                 int portnumber)
          throws java.net.UnknownHostException,
                 java.io.IOException,
                 ServerResponseException

open a connection to a given server and port this is an alias for connect()

Parameters:

host - the hostname of the HylaFAX server

portnumber - the port the server is listening on

Throws:

java.net.UnknownHostException - cannot resolve the given hostname

java.io.IOException - IO error occurred

ServerResponseException - the server replied with an error code

open

public void open(java.lang.String host)
          throws java.net.UnknownHostException,
                 java.io.IOException,
                 ServerResponseException

open a connection to a given server at default port this is an alias for connect()

Parameters:

host - the hostname of the HylaFAX server

Throws:

java.net.UnknownHostException - cannot resolve the given hostname

java.io.IOException - IO error occurred

ServerResponseException - the server replied with an error code

open

public void open()
          throws java.net.UnknownHostException,
                 java.io.IOException,
                 ServerResponseException

open a connection to the localhost on the default port

Throws:

java.net.UnknownHostException - cannot resolve the given hostname

java.io.IOException - IO error occurred

ServerResponseException - the server replied with an error code

user

public boolean user(java.lang.String username)
             throws java.io.IOException,
                    ServerResponseException

send the user name for this session

Parameters:

username - name of the user to login as

Returns:

true if a password is required, false if no password is required

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

pass

public void pass(java.lang.String password)
          throws java.io.IOException,
                 ServerResponseException

send the password for this username and session

Parameters:

password - the password to login with

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

noop

public void noop()
          throws java.io.IOException,
                 ServerResponseException

perform server No Operation could be used as a keep-alive

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

pwd

public java.lang.String pwd()
                     throws java.io.IOException,
                            ServerResponseException

return current directory

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

cwd

public void cwd(java.lang.String value)
         throws java.io.IOException,
                ServerResponseException

change current working directory

Parameters:

value - directory to set to current working directory

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

cdup

public void cdup()
          throws java.io.IOException,
                 ServerResponseException

change to parent of current working directory

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with error code

idle

public long idle()
          throws java.io.IOException,
                 ServerResponseException

get the current idle timeout in seconds

Returns:

server's idle timeout in seconds

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

idle

public void idle(long timeout)
          throws java.io.IOException,
                 ServerResponseException

set the idle timeout value to the given number of seconds

Parameters:

timeout - new timeout value in seconds (MAX = 7200)

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

dele

public void dele(java.lang.String pathname)
          throws java.io.IOException,
                 ServerResponseException

delete the given file.

Parameters:

pathname - the name of the file to delete

Throws:

java.io.IOException - a socket IO error happened

ServerResponseException - the server replied with an error code

type

public void type(char value)
          throws java.io.IOException,
                 ServerResponseException

Set the file type for transfer. File types can be TYPE_ASCII, TYPE_EBCDIC, TYPE_IMAGE or TYPE_LOCAL. This may affect how the client and server interpret file data during transfers. The default type is TYPE_ASCII per RFC 959.

Parameters:

value - new type

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with error code

getType

public char getType()

Return the file type for transfer. File types can be TYPE_ASCII, TYPE_EBCDIC, TYPE_IMAGE, or TYPE_LOCAL.

Returns:

current file transfer type

mode

public void mode(char value)
          throws java.io.IOException,
                 ServerResponseException

set the data transfer mode. Valid modes are MODE_STREAM, MODE_BLOCK, MODE_COMPRESSED and MODE_ZLIB. NOTE: only MODE_STREAM (default) has been used to date.

Parameters:

value - new data transfer mode

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

abor

public void abor()
          throws java.io.IOException,
                 ServerResponseException

abort the last command

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error code

abor

public void abor(java.lang.String modem)
          throws java.io.IOException,
                 ServerResponseException

abort the last command on the given modem. experience shows that this requires ADMIN priviledges.

Parameters:

modem - the modem to abort the command on

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error

port

public void port(java.net.InetAddress address,
                 int port)
          throws java.io.IOException,
                 ServerResponseException

tell the server which address/port we will listen on

Parameters:

address - address that we'll be listening on

port - port on given address we'll be listening on

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

stot

public java.lang.String stot(java.io.InputStream data)
                      throws java.io.IOException,
                             ServerResponseException

store temp file, the file is stored in a uniquely named file on the server. The remote temp file is deleted when the connection is closed.

Returns:

the filename of the temp file

Throws:

java.io.IOException - io error occurred talking to the server

ServerResponseException - server replied with error code

stou

public java.lang.String stou(java.io.InputStream in)
                      throws java.io.IOException,
                             ServerResponseException

store a file with a unique name.

Returns:

the name of the file created

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error code

stor

public void stor(java.io.InputStream in,
                 java.lang.String pathname)
          throws java.io.IOException,
                 ServerResponseException

store a file.

Parameters:

pathname - name of file to store on server (where to put the file on the server)

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server responded with an error

syst

public java.lang.String syst()
                      throws java.io.IOException,
                             ServerResponseException

get system type returns the string that the server sends (not sure how to handle it yet) on a Debian GNU/Linux 2.1 (slink) system, the result string is: "UNIX Type: L8 Version: SVR4"

Returns:

the system type string

Throws:

java.io.IOException - a socket IO error occurred

ServerResponseException - the server replied with an error code

stru

public void stru(char value)
          throws java.io.IOException,
                 ServerResponseException

set the file structure. valid file structure settings are STRU_FILE, STRU_RECORD, STRU_PAGE and STRU_TIFF. NOTE: only STRU_FILE has been tested to date. I have no idea when you would use the other settings.

Parameters:

value - file structure setting

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

list

public void list(java.lang.String path)
          throws java.io.IOException,
                 java.io.FileNotFoundException,
                 ServerResponseException

get a list of files in a directory. Like nlst() but with more information per line. The difference is more like ls vs. ls -l. With FTP servers, I know the output is very system dependant but since there aren't too many different implementations of the HylaFAX server, it's probably not much of an issue here. Still, beware.

This method relies on a data port (passive or active) to receive the list data. it is recommended that you use the getList() wrapper method rather than this method directly.

Parameters:

path - path of file or directory to get listing. A null path will get the listing of the current directory.

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

java.io.FileNotFoundException - the given path does not exist

list

public void list()
          throws java.io.IOException,
                 java.io.FileNotFoundException,
                 ServerResponseException

get list of files in current directory.

NOTE: uses list() with the null path.

This method relies on a data socket of some sort to receive the list data. It is recommended that you use the getList() convenience method rather than this one directly.

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

java.io.FileNotFoundException - server could not find the specified file

nlst

public void nlst(java.lang.String path)
          throws java.io.IOException,
                 ServerResponseException,
                 java.io.FileNotFoundException

get name list of files in directory. Similar to list() but names only.

This method requires a data socket to receive the name list data. It is recommended that you use the getNameList() method instead of this method directly.

Parameters:

path - path of the file or directory to list, passing in null will result in listing the current directory

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

java.io.FileNotFoundException - server could not find the specified file

nlst

public void nlst()
          throws java.io.IOException,
                 java.io.FileNotFoundException,
                 ServerResponseException

get name list of files in directory. Similar to list() but names only. NOTE: uses the null path as the argument to nlst(String)

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

java.io.FileNotFoundException - server could not find the specified file

retr

public void retr(java.lang.String path)
          throws java.io.IOException,
                 java.io.FileNotFoundException,
                 ServerResponseException

retrieve the given file

Parameters:

path - the relative or absolute path to the file to retrieve

Throws:

java.io.IOException - caused by a socket IO error

ServerResponseException - caused by a server response indicating an error

java.io.FileNotFoundException - the given path does not exist

size

public long size(java.lang.String pathname)
          throws java.io.IOException,
                 java.io.FileNotFoundException,
                 ServerResponseException

Returns the size (in bytes) of the given regular file. This is the size on the server and may not accurately represent the file size once the file has been transferred (particularly via ASCII mode)

Parameters:

pathname - the name of the file to get the size for

Throws:

java.io.IOException - caused by a socket IO error

ServerResponseException - caused by a server response indicating an error

java.io.FileNotFoundException - the given path does not exist

mdtm

public java.util.Date mdtm(java.lang.String pathname)
                    throws java.io.IOException,
                           java.io.FileNotFoundException,
                           ServerResponseException,
                           java.text.ParseException

Returns the last modified time of the given file. This command is specified in the FTPEXT Working Group draft currently available at http://www.ietf.org/internet-drafts/draft-ietf-ftpext-mlst-15.txt.

The date is returned in GMT in a string of the following format: YYYYMMDDhhmmss.ddd where .ddd is an optional suffix reporting milliseconds. This method attempts to parse the string returned by the server and present the caller with a java.util.Date instance.

Parameters:

pathname - the name of the file to get the last-modified time for

Throws:

java.io.IOException - caused by a socket IO error

ServerResponseException - caused by a server response indicating an error

java.io.FileNotFoundException - the given path does not exist

java.text.ParseException - the server returned an unrecognized date format

rnfr

public void rnfr(java.lang.String pathname)
          throws java.io.IOException,
                 java.io.FileNotFoundException,
                 ServerResponseException

Specifies a file to be renamed. This command must be immediately followed by a RNTO command. It is recommended that you use the rename() convenience method rather than this one directly.

Parameters:

pathname - the name of the file to be renamed

Throws:

java.io.IOException - caused by a socket IO error

ServerResponseException - caused by a server response indicating an error

java.io.FileNotFoundException - the given path does not exist

rnto

public void rnto(java.lang.String pathname)
          throws java.io.IOException,
                 ServerResponseException

Renames a previously specified file to the given name. This command must be immediately preceded by a RNFR command. It is recommended that you use the rename() convenience method rather than this one directly.

Parameters:

pathname - the name of the file to be renamed

Throws:

java.io.IOException - caused by a socket IO error

ServerResponseException - caused by a server response indicating an error

stat

public java.util.Vector stat(java.lang.String path)
                      throws java.io.IOException,
                             java.io.FileNotFoundException,
                             ServerResponseException

Returns the status of the named file or directory.

Parameters:

path - the directory or file to get the status of, using a null path will cause this method to return the server status information

Returns:

a Vector of String objects, each String being a single line of the status message from the server

Throws:

java.io.IOException - caused by a socket IO error

java.io.FileNotFoundException - the given path or file does not exist

ServerResponseException - caused by a server response indicating an error

stat

public java.util.Vector stat()
                      throws java.io.IOException,
                             ServerResponseException

Returns the server status message. This is equivalent to using stat(null).

Returns:

a Vector of String objects, each String being a single line of the status message from the server

Throws:

java.io.IOException - caused by a socket IO error

ServerResponseException - caused by a server response indicating an error

pasv

public PassiveParameters pasv()
                       throws java.io.IOException,
                              ServerResponseException

prepare for server-to-server transfer (passive mode)

Returns:

tuple containing the server IP address and port number

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

quit

public void quit()
          throws java.io.IOException,
                 ServerResponseException

end session

Throws:

java.io.IOException - io error occurred

ServerResponseException - server replied with an error code

getGreeting

public java.lang.String getGreeting()

setDebug

public void setDebug(boolean value)

Sets the ConsoleLogger's debug output. Does nothing for log4j. Log4j needs to be configured using log4j.properties

Parameters:

value - new debug flag value

getDebug

public boolean getDebug()

Returns true if ConsoleLogger is in debug mode. This is only provided for backward compatibility and should not be used. Loggers can be defined in the etc/log4j.properties files.

Returns:

debug flag value (true|false)

readResponse

protected java.lang.String readResponse(java.io.BufferedReader input)
                                 throws java.io.IOException

read a (multi-line) response

Parameters:

input - the BufferedReader to read data from

Returns:

the response in a Vector of Strings

Throws:

java.io.IOException - an IO error occurred

connect

protected void connect(java.lang.String host,
                       int portnumber)
                throws java.net.UnknownHostException,
                       java.io.IOException,
                       ServerResponseException

connect to the given host at the given port number.

Parameters:

host - the hostname of the server to connect to

portnumber - the port that the server is listening on

Throws:

java.net.UnknownHostException - the given host name cannot be resolved

java.io.IOException - an IO error occurred

ServerResponseException - the server responded with an error