com.lamatek.protobeans
Class FTPBean

java.lang.Object
  com.lamatek.protobeans.FTPBean

All Implemented Interfaces:

java.io.Serializable

public class FTPBean
extends java.lang.Object
implements java.io.Serializable

FTPBean provides a consistent interface to an FTP Server. It provides all command submission, reponse handling and file transfer functions for the user, removing the tiresome task of error checking.

The FTPBean connects to the FTP server when instantiated, and is instantly ready for command submission or file transfer.

File transfers are handled through a different dataport than the communications port, and is determined using the PASV command.

Typical use of the FTPBean to transfer a file would be programmed as such:

try {
FTPBean remote = new FTPBean(getCodeBase().getHost(), 21, "myName", "myPassword");
remote.setDirectory("my/directory");
remote.storeFile("remotefilename.ext", "localfile.ext", FTPBean.ASCII);
remote.logout();
}
catch(FTPException ftp) {
System.out.println("Error occured during file transmission:\r\n" + ftp.getMessage());
}

As you can see, the entire process can be handled using only one try/catch loop. With all possible errors being extended by FTPException.

See Also:

Serialized Form

Field Summary

static int	ASCII Static variable used to define ASCII content.
static int	BINARY Static variable used to define BINARY content.

Constructor Summary

FTPBean(boolean verbose)
This no argument constructor creates an initially unlogged FTPBean.

FTPBean(java.lang.String server, int port, boolean verbose)
This constructor creates an FTPBean with the initial socket connection already established.

FTPBean(java.lang.String server, int port, java.lang.String username, java.lang.String password, boolean verbose)
This constructor for the FTPBean provides all login and dataSocket functions during initialization.

Method Summary

boolean	appendFile(java.lang.String filename, java.lang.String file, int type) This method is similar to the storeFile method, only it appends the data to an already existing file, or if a file with the give name cannot be found, then it creates a new one.
boolean	appendText(java.lang.String filename, java.lang.String data) This method is similar to the storeText method, only it appends the data to an already existing file, or if a file with the give name cannot be found, then it creates a new one.
java.lang.String	completeDownload() This method is an accessory method that reads any leftover text in the control port's input stream.
boolean	deleteFile(java.lang.String filename) This method removes the specified file from the FTP Server.
java.lang.String	getDirectoryTree() This method requests the directory structure from the FTP server using the current directory as the top.
java.lang.String	getLastResponse() This method returns the last reponse received from the FTP Server.
java.lang.String	getRemoteDirectory() Reads the current directory on the remote FTP server.
boolean	login(java.lang.String username, java.lang.String password) This method attempts to login in to the remote FTP server using the supplied username and password arguments.
void	logout() This method performs the required logging out functions.
boolean	makeDirectory(java.lang.String directory) This method creates a new directory on the FTP Server.
boolean	removeDirectory(java.lang.String directory) This method removes a directory from the remote FTP server.
boolean	renameFile(java.lang.String oldname, java.lang.String newname) This method renames a file on the FTP Server.
boolean	retrieveFile(java.lang.String filename, int type) This method retrieves a file from the remote server and saves it to the current directory with the same filename.
java.lang.Object	retrieveObject(java.lang.String filename, boolean save) This method retrieves a remote Java object and either returns it as an instance of Object (if save = false) or stores it locally in a file in the current directory with the same name (if save = true).
java.lang.String	retrieveText(java.lang.String filename, boolean save) This method reads a text file and either returns it as a String (if save = false) or saves it to a file in the current directory with the same name (if save = true);
boolean	setRemote(java.lang.String server, int port) This method sets the remote server and port number, creating the required input and output streams for command submission and reads connection reponse from server and puts the reponse in the lastreply String variable.
boolean	setRemoteDirectory(java.lang.String directory) Sets the remote directory on the FTP server.
boolean	storeFile(java.lang.String remote, java.lang.String local, int type) This command reads data from the supplied file and saves it to the server with the filename supplied.
boolean	storeObject(java.lang.String filename, java.lang.Object object) This method is used to persistently store a Java object to a remote server.
boolean	storeText(java.lang.String filename, java.lang.String data) This command the supplied text to the server with the given filename.

Methods inherited from class java.lang.Object

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

Field Detail

ASCII

public static final int ASCII

Static variable used to define ASCII content.

See Also:

Constant Field Values

BINARY

public static final int BINARY

Static variable used to define BINARY content.

See Also:

Constant Field Values

Constructor Detail

FTPBean

public FTPBean(boolean verbose)

This no argument constructor creates an initially unlogged FTPBean. Before it can be used for file transfer, the setRemote and login methods must be called.

FTPBean

public FTPBean(java.lang.String server,
               int port,
               boolean verbose)
        throws FTPException

This constructor creates an FTPBean with the initial socket connection already established. Before it can be used for file transfer, the login method must be called.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

FTPBean

public FTPBean(java.lang.String server,
               int port,
               java.lang.String username,
               java.lang.String password,
               boolean verbose)
        throws FTPException

This constructor for the FTPBean provides all login and dataSocket functions during initialization.

Parameters:

server - The string representation of the FTP host. (From an applet this will almost always be obtained using the Applet.getCodeBase().getHost() method.)

port - The FTP port of the Host server. (Usually 21).

username - The FTP login name to be used.

password - The FTP password that correlates to the FTP login name.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

Method Detail

setRemote

public boolean setRemote(java.lang.String server,
                         int port)
                  throws FTPException

This method sets the remote server and port number, creating the required input and output streams for command submission and reads connection reponse from server and puts the reponse in the lastreply String variable.

Parameters:

server - The String representation of the FTP Server Host (in an Applet this value will almost always be obtained through Applet.getCodeBae().getHost()).

port - The FTP port of the remote server (usually 21).

Returns:

True if the server connection was accepted or False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

login

public boolean login(java.lang.String username,
                     java.lang.String password)
              throws FTPException

This method attempts to login in to the remote FTP server using the supplied username and password arguments.

NOTE: This method must be preceeded with a successful call to setRemote

Parameters:

username - FTP login name

password - FTP password

Returns:

True if the login was accepted or False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

logout

public void logout()
            throws FTPException

This method performs the required logging out functions.

Throws:

FTPException - If an error code is received during logout.

getLastResponse

public java.lang.String getLastResponse()

This method returns the last reponse received from the FTP Server. This method is useful after receipt of an FTPException, to view the server's actual rejected response.

Returns:

The last reponse from the FTP Server.

setRemoteDirectory

public boolean setRemoteDirectory(java.lang.String directory)
                           throws FTPException

Sets the remote directory on the FTP server.

Parameters:

directory - The desired remote directory.

Returns:

True if the remote directory was set or False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

getRemoteDirectory

public java.lang.String getRemoteDirectory()
                                    throws FTPException

Reads the current directory on the remote FTP server.

Returns:

The current directory on the FTP Server.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

storeFile

public boolean storeFile(java.lang.String remote,
                         java.lang.String local,
                         int type)
                  throws FTPException

This command reads data from the supplied file and saves it to the server with the filename supplied.

Parameters:

remote - the remote filename to be used to store the file.

local - The local filename to read data from.

type - Data type. Either FTPBean.ASCII or FTPBean.BINARY.

Returns:

True if the file was saved or False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

storeText

public boolean storeText(java.lang.String filename,
                         java.lang.String data)
                  throws FTPException

This command the supplied text to the server with the given filename.

Parameters:

filename - the filename to be used to store the file

data - the java.lang.String to store in the remote file.

Returns:

True if the file was saved or False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

storeObject

public boolean storeObject(java.lang.String filename,
                           java.lang.Object object)
                    throws FTPException

This method is used to persistently store a Java object to a remote server.

Returns:

True if the file transfer was successful, False if it was not.

Throws:

FTPException - If an error code is received during Object transfer.

appendFile

public boolean appendFile(java.lang.String filename,
                          java.lang.String file,
                          int type)
                   throws FTPException

This method is similar to the storeFile method, only it appends the data to an already existing file, or if a file with the give name cannot be found, then it creates a new one.

Parameters:

filename - The name of the existing remote file to append to.

file - An instance of java.io.File that points to a local file that is to be read from.

type - The file type. Either FTPBean.ASCII or FTPBean.BINARY.

Returns:

True if the file transfer succeeded or False if it did not

Throws:

FTPException - If an error code was received from the Server during transport.

appendText

public boolean appendText(java.lang.String filename,
                          java.lang.String data)
                   throws FTPException

This method is similar to the storeText method, only it appends the data to an already existing file, or if a file with the give name cannot be found, then it creates a new one.

Returns:

True if the file transfer succeeded or False if it did not

Throws:

FTPException - If an error code was received from the Server during transport.

getDirectoryTree

public java.lang.String getDirectoryTree()
                                  throws FTPException

This method requests the directory structure from the FTP server using the current directory as the top.

Returns:

A String representation of the remote directory structure.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

removeDirectory

public boolean removeDirectory(java.lang.String directory)
                        throws FTPException

This method removes a directory from the remote FTP server.

Parameters:

directory - The directory to remote (can be either absolute or relative)

Returns:

True if the directory was removed or False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

makeDirectory

public boolean makeDirectory(java.lang.String directory)
                      throws FTPException

This method creates a new directory on the FTP Server.

Parameters:

directory - The name of the new directory. (can be relative or absolute)

Returns:

True if the directory was created or False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

deleteFile

public boolean deleteFile(java.lang.String filename)
                   throws FTPException

This method removes the specified file from the FTP Server.

NOTE: it is assumed that the class implementing FTPBean provides all necessary assurances that the file should be deleted.

Parameters:

filename - The file to remove (can be absolute or relative)

Returns:

True if the file was deleted or False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

renameFile

public boolean renameFile(java.lang.String oldname,
                          java.lang.String newname)
                   throws FTPException

This method renames a file on the FTP Server.

NOTE: It is assumed that the class file implementing this FTPBean has performed all necessary checks before this method is called.

Parameters:

oldname - The current name of the remote file.

newname - The new name for the remote file.

Returns:

True if the file was renamed or False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

retrieveFile

public boolean retrieveFile(java.lang.String filename,
                            int type)
                     throws FTPException

This method retrieves a file from the remote server and saves it to the current directory with the same filename.

Parameters:

filename - The file to retrieve

type - The file type to read. Either FTPBean.ASCII or FTPBean.BINARY

Returns:

True if the file download was successful, False if it was not.

Throws:

FTPException - If an error code is received from the FTP Server during processing.

retrieveObject

public java.lang.Object retrieveObject(java.lang.String filename,
                                       boolean save)
                                throws FTPException

This method retrieves a remote Java object and either returns it as an instance of Object (if save = false) or stores it locally in a file in the current directory with the same name (if save = true).

Parameters:

filename - The remote and local filename (if applicable)

save - True if you wish to save in a file, or false if you want the object returned for future use.

Returns:

An Object that is either the requested object or a String that reads "true" or "false" depending on success or failure.

Throws:

FTPException - If an error occurs during object loading.

retrieveText

public java.lang.String retrieveText(java.lang.String filename,
                                     boolean save)
                              throws FTPException

This method reads a text file and either returns it as a String (if save = false) or saves it to a file in the current directory with the same name (if save = true);

Parameters:

filename - The remote file to read from

save - True to save to file or False to return as a String

Returns:

An instance of java.lang.String that either contains the file contents (if save = false) or "true" or "false" depending on file transfer success.

Throws:

FTPException - If an error occurs during file download.

completeDownload

public java.lang.String completeDownload()
                                  throws FTPException

This method is an accessory method that reads any leftover text in the control port's input stream. A call to this method is necessary after a call to retrieveFile.

Returns:

The last server response

Throws:

FTPException - If the control port's input stream is null.