IP*Works!

ipworks
Class Ftp

java.lang.Object
  |
  +--ipworks.Ftp

public class Ftp
extends java.lang.Object

The FTP class can be used to transfer files to and from FTP servers using the FTP Protocol.

The FTP class implements a standard FTP client as specified in RFC 959 and RFC 1579.

The first step in using the class is specifying the RemoteHost , User and Password . The file to upload to or download from is given by the RemoteFile property. The file to download to or upload from is specified by LocalFile . The current path in the server is specified by the RemotePath property. The Passive property is especially useful if the client is behind a firewall which inhibits incoming connections to higher ports.

The class operates by setting appropriate values to the Action property. If LocalFile is set to something other than an empty string, then files are received in LocalFile , otherwise the data is received through the Transfer event. StartTransfer and EndTransfer are fired at the beginning and end of transmission.

The PITrail event traces the interaction between the client and the server (the FTP Protocol Interface connection).

Directory listings are received through the DirList event.


Field Summary
static int a_Abort
           
static int a_Append
           
static int a_DeleteFile
           
static int a_Download
           
static int a_Idle
           
static int a_ListDirectory
           
static int a_ListDirectoryLong
           
static int a_Logoff
           
static int a_Logon
           
static int a_MakeDirectory
           
static int a_RemoveDirectory
           
static int a_RenameFile
           
static int a_StoreUnique
           
static int a_Upload
           
static int tm_ASCII
           
static int tm_Binary
           
static int tm_Default
           
 
Constructor Summary
Ftp()
           
 
Method Summary
 void addFtpEventListener(FtpEventListener l)
           
 void fireDirList(java.lang.String dirEntry, java.lang.String fileName, boolean isDir, int fileSize, java.lang.String fileTime)
          Fired when a directory entry is received.
 void fireEndTransfer()
          Fired when a file completes downloading/uploading.
 void fireError(int errorCode, java.lang.String description)
          Information about errors during data delivery.
 void firePITrail(int direction, java.lang.String message)
          Traces the commands sent to the ftp server, and the respective replies.
 void fireStartTransfer()
          Fired when a file starts downloading/uploading.
 void fireTransfer(int bytesTransferred, byte[] text)
          Fired during file download/upload.
 int getAction()
          An action code for the component.
 java.lang.String getAltFile()
          The new name for RemoteFile when Action is set to Rename .
 java.lang.String getLastReply()
          The last reply from the server.
 java.lang.String getLocalFile()
          The path to a local file for download/upload.
 java.lang.String getLocalHost()
          The name of the local host.
 java.lang.String getPassword()
          The password to login with.
 java.lang.String getRemoteFile()
          The name of the remote file for uploading/downloading.
 java.lang.String getRemoteHost()
          The domain name or IP address of the FTP server.
 java.lang.String getRemotePath()
          The current path in the FTP server.
 int getRemotePort()
          The port for the FTP service (default is 21).
 int getStartByte()
          The byte index in RemoteFile and LocalFile where to start the transmission.
 int getTransferMode()
          The transfer mode (ASCII or Binary).
 java.lang.String getUser()
          The user id to login as.
 boolean isPassive()
          Controls whether to direct the server into passive mode especially if behind a firewall.
 void removeFtpEventListener(FtpEventListener l)
           
 void setAction(int action)
          An action code for the component.
 void setAltFile(java.lang.String altFile)
          The new name for RemoteFile when Action is set to Rename .
 void setCommand(java.lang.String command)
          Can be used to send additional commands directly to the FTP server.
 void setLocalFile(java.lang.String localFile)
          The path to a local file for download/upload.
 void setPassive(boolean passive)
          Controls whether to direct the server into passive mode especially if behind a firewall.
 void setPassword(java.lang.String password)
          The password to login with.
 void setRemoteFile(java.lang.String remoteFile)
          The name of the remote file for uploading/downloading.
 void setRemoteHost(java.lang.String remoteHost)
          The domain name or IP address of the FTP server.
 void setRemotePath(java.lang.String remotePath)
          The current path in the FTP server.
 void setRemotePort(int remotePort)
          The port for the FTP service (default is 21).
 void setStartByte(int startByte)
          The byte index in RemoteFile and LocalFile where to start the transmission.
 void setTransferMode(int transferMode)
          The transfer mode (ASCII or Binary).
 void setUser(java.lang.String user)
          The user id to login as.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

a_Idle

public static final int a_Idle

a_Abort

public static final int a_Abort

a_Logon

public static final int a_Logon

a_Logoff

public static final int a_Logoff

a_Download

public static final int a_Download

a_Upload

public static final int a_Upload

a_DeleteFile

public static final int a_DeleteFile

a_RenameFile

public static final int a_RenameFile

a_ListDirectory

public static final int a_ListDirectory

a_ListDirectoryLong

public static final int a_ListDirectoryLong

a_MakeDirectory

public static final int a_MakeDirectory

a_RemoveDirectory

public static final int a_RemoveDirectory

a_Append

public static final int a_Append

a_StoreUnique

public static final int a_StoreUnique

tm_Default

public static final int tm_Default

tm_ASCII

public static final int tm_ASCII

tm_Binary

public static final int tm_Binary
Constructor Detail

Ftp

public Ftp()
Method Detail

getAction

public int getAction()
An action code for the component. Setting the Action property to a valid action code makes the class perform the associated action. If the action completes successfully, execution continues normally, and Action is reset to 0 (Idle). If an error happens, then an IPWorksException exception is raised.

The following are the possible values for the Action property and the corresponding descriptions:

a_Idle
Default action. It can also be used to interrupt the current operation.
a_Abort
Sends an ABOR command to the FTP server. It is used to interrupt file uploads/downloads.
a_Logon
Logon to the FTP server using the current User and Password . If TransferMode is not 0 (Default), then the FTP transfer mode is set to the appropriate value.
a_Logoff
Logoff from the FTP server by posting a QUIT command. If that fails, the connection is terminated by the local host.
a_Download
The remote file specified by RemoteFile is downloaded to the local file specified by LocalFile , or it is retrieved through the Transfer event, if the LocalFile property is "" (empty string). RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_Upload
The local file specified by LocalFile is uploaded to the remote file specified by RemoteFile . RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon . Check also the Append action for appending a file to the server.
a_DeleteFile
The remote file(s) specified by RemoteFile are deleted. RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_RenameFile
The name of remote file specified by RemoteFile is changed to the value of AltFile . RemoteFile and AltFile are either absolute paths on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_ListDirectory
A listing is requested for the directory (or file mask) specified in RemoteFile . RemoteFile is either an absolute path on the server, or a path relative to RemotePath . The file listing is received through the DirList event. Only file names are returned. If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_ListDirectoryLong
A listing is requested for the directory (or file mask) specified in RemoteFile . RemoteFile is either an absolute path on the server, or a path relative to RemotePath . The file listing is received through the DirList event. Extended file information is returned. If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_MakeDirectory
A directory with path specified by RemoteFile is created on the FTP server. RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_RemoveDirectory
A directory with path specified by RemoteFile is deleted on the FTP server. RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_Append
This command causes the server-DTP to accept the data transferred via the data connection and to store the data in a file at the server site. If the file specified in the pathname exists at the server site, then the data shall be appended to that file; otherwise the file specified in the pathname shall be created at the server site. Similar to the Upload action but the local file specified by LocalFile is appended to RemoteFile on the server as opposed to replacing it as done by the Upload action. RemoteFile is either an absolute path on the server, or a path relative to RemotePath . The server will create a file with that name if it doesn't already exist (similar to Upload). If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_StoreUnique
Similar to the Upload Action but the server determines a unique name for the LocalFile to be saved on the current directory given by RemotePath . The server includes the new name of the file in its response. The user should check the PITrail event, or LastReply property to retrieve this generated filename.


setAction

public void setAction(int action)
               throws IPWorksException
An action code for the component. Setting the Action property to a valid action code makes the class perform the associated action. If the action completes successfully, execution continues normally, and Action is reset to 0 (Idle). If an error happens, then an IPWorksException exception is raised.

The following are the possible values for the Action property and the corresponding descriptions:

a_Idle
Default action. It can also be used to interrupt the current operation.
a_Abort
Sends an ABOR command to the FTP server. It is used to interrupt file uploads/downloads.
a_Logon
Logon to the FTP server using the current User and Password . If TransferMode is not 0 (Default), then the FTP transfer mode is set to the appropriate value.
a_Logoff
Logoff from the FTP server by posting a QUIT command. If that fails, the connection is terminated by the local host.
a_Download
The remote file specified by RemoteFile is downloaded to the local file specified by LocalFile , or it is retrieved through the Transfer event, if the LocalFile property is "" (empty string). RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_Upload
The local file specified by LocalFile is uploaded to the remote file specified by RemoteFile . RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon . Check also the Append action for appending a file to the server.
a_DeleteFile
The remote file(s) specified by RemoteFile are deleted. RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_RenameFile
The name of remote file specified by RemoteFile is changed to the value of AltFile . RemoteFile and AltFile are either absolute paths on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_ListDirectory
A listing is requested for the directory (or file mask) specified in RemoteFile . RemoteFile is either an absolute path on the server, or a path relative to RemotePath . The file listing is received through the DirList event. Only file names are returned. If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_ListDirectoryLong
A listing is requested for the directory (or file mask) specified in RemoteFile . RemoteFile is either an absolute path on the server, or a path relative to RemotePath . The file listing is received through the DirList event. Extended file information is returned. If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_MakeDirectory
A directory with path specified by RemoteFile is created on the FTP server. RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_RemoveDirectory
A directory with path specified by RemoteFile is deleted on the FTP server. RemoteFile is either an absolute path on the server, or a path relative to RemotePath . If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_Append
This command causes the server-DTP to accept the data transferred via the data connection and to store the data in a file at the server site. If the file specified in the pathname exists at the server site, then the data shall be appended to that file; otherwise the file specified in the pathname shall be created at the server site. Similar to the Upload action but the local file specified by LocalFile is appended to RemoteFile on the server as opposed to replacing it as done by the Upload action. RemoteFile is either an absolute path on the server, or a path relative to RemotePath . The server will create a file with that name if it doesn't already exist (similar to Upload). If there is no FTP session in place, one is automatically created by first setting Action to Logon .
a_StoreUnique
Similar to the Upload Action but the server determines a unique name for the LocalFile to be saved on the current directory given by RemotePath . The server includes the new name of the file in its response. The user should check the PITrail event, or LastReply property to retrieve this generated filename.


getAltFile

public java.lang.String getAltFile()
The new name for RemoteFile when Action is set to Rename . See the description of the Action property for more information.


setAltFile

public void setAltFile(java.lang.String altFile)
                throws IPWorksException
The new name for RemoteFile when Action is set to Rename . See the description of the Action property for more information.


setCommand

public void setCommand(java.lang.String command)
                throws IPWorksException
Can be used to send additional commands directly to the FTP server. Check the LastReply property and/or trap the PITrail events comming from the server to get the response.


getLastReply

public java.lang.String getLastReply()
The last reply from the server. This is the last reply received from the server. It can be used for information purposes. The same information and more can also be retrieved through the PITrail event.


getLocalFile

public java.lang.String getLocalFile()
The path to a local file for download/upload. If the file exists, it is overwritten. The LocalFile property is used by the Upload and Download actions. See the description of the Action property for more information.


setLocalFile

public void setLocalFile(java.lang.String localFile)
                  throws IPWorksException
The path to a local file for download/upload. If the file exists, it is overwritten. The LocalFile property is used by the Upload and Download actions. See the description of the Action property for more information.


getLocalHost

public java.lang.String getLocalHost()
The name of the local host. When connected, the IP address of the interface through which the connection was made. The LocalHost property contains the name of the local host as obtained by the gethostname() Winsock call.

If the class is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).


isPassive

public boolean isPassive()
Controls whether to direct the server into passive mode especially if behind a firewall. Many firewalls will not allow the FTP server to open a connection from outside to the higher ports where the FTP client class expects them. If Passive is set to TRUE , the class will use the PASV instead of the PORT command and will thus direct the server into passive mode: connections are initiated only by the client.


setPassive

public void setPassive(boolean passive)
                throws IPWorksException
Controls whether to direct the server into passive mode especially if behind a firewall. Many firewalls will not allow the FTP server to open a connection from outside to the higher ports where the FTP client class expects them. If Passive is set to TRUE , the class will use the PASV instead of the PORT command and will thus direct the server into passive mode: connections are initiated only by the client.


getPassword

public java.lang.String getPassword()
The password to login with. This property must be set before the class connects to the FTP server.


setPassword

public void setPassword(java.lang.String password)
                 throws IPWorksException
The password to login with. This property must be set before the class connects to the FTP server.


getRemoteFile

public java.lang.String getRemoteFile()
The name of the remote file for uploading/downloading. The RemoteFile is either an absolute file path, or a relative path based on RemotePath .

A number of actions use RemoteFile as an argument. See the description of the Action property for more information.


setRemoteFile

public void setRemoteFile(java.lang.String remoteFile)
                   throws IPWorksException
The name of the remote file for uploading/downloading. The RemoteFile is either an absolute file path, or a relative path based on RemotePath .

A number of actions use RemoteFile as an argument. See the description of the Action property for more information.


getRemoteHost

public java.lang.String getRemoteHost()
The domain name or IP address of the FTP server. The RemoteHost property specifies the IP address (IP number in dotted internet format) or Domain Name of the FTP server. It is set before a connection is attempted and cannot be changed once a connection is in progress.

If the RemoteHost property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the RemoteHost property is set to the corresponding address. If the search is not successful, an error is returned.


setRemoteHost

public void setRemoteHost(java.lang.String remoteHost)
                   throws IPWorksException
The domain name or IP address of the FTP server. The RemoteHost property specifies the IP address (IP number in dotted internet format) or Domain Name of the FTP server. It is set before a connection is attempted and cannot be changed once a connection is in progress.

If the RemoteHost property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the RemoteHost property is set to the corresponding address. If the search is not successful, an error is returned.


getRemotePath

public java.lang.String getRemotePath()
The current path in the FTP server. The RemotePath shows the current working directory on the FTP server. It can also be used to change the working directory by setting it to an absolute directory path, or a relative path with respect to the existing value of RemotePath .

If the first two characters of the new path are "..", then a change to one level above in the directory tree is performed.

Setting RemotePath causes the class to sent the appropriate command to the remote server only if connected.


setRemotePath

public void setRemotePath(java.lang.String remotePath)
                   throws IPWorksException
The current path in the FTP server. The RemotePath shows the current working directory on the FTP server. It can also be used to change the working directory by setting it to an absolute directory path, or a relative path with respect to the existing value of RemotePath .

If the first two characters of the new path are "..", then a change to one level above in the directory tree is performed.

Setting RemotePath causes the class to sent the appropriate command to the remote server only if connected.


getRemotePort

public int getRemotePort()
The port for the FTP service (default is 21). A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed while a connection is in progress. Any attempt to change the RemotePort while connected will fail with an error.


setRemotePort

public void setRemotePort(int remotePort)
                   throws IPWorksException
The port for the FTP service (default is 21). A valid port number (a value between 1 and 65535) is required for the connection to take place. The property must be set before a connection is attempted and cannot be changed while a connection is in progress. Any attempt to change the RemotePort while connected will fail with an error.


getStartByte

public int getStartByte()
The byte index in RemoteFile and LocalFile where to start the transmission. The StartByte contains a zero-based index in both RemoteFile and LocalFile that determines the point where the transmission of data starts from. This is useful for resuming interrupted downloads and uploads of files from FTP servers.

Once set, the StartByte index is used for all future downloads/uploads. The property must be reset to 0 for normal downloads/uploads.

In the Transfer event, the TransferredBytes parameter will include the bytes skipped (i.e. it will show StartByte more bytes than actually transferred).

(NOTE: some FTP servers may not support the FTP 'REST' command. If that is the case with the server you are accessing, you will not be able to use the StartByte property.)


setStartByte

public void setStartByte(int startByte)
                  throws IPWorksException
The byte index in RemoteFile and LocalFile where to start the transmission. The StartByte contains a zero-based index in both RemoteFile and LocalFile that determines the point where the transmission of data starts from. This is useful for resuming interrupted downloads and uploads of files from FTP servers.

Once set, the StartByte index is used for all future downloads/uploads. The property must be reset to 0 for normal downloads/uploads.

In the Transfer event, the TransferredBytes parameter will include the bytes skipped (i.e. it will show StartByte more bytes than actually transferred).

(NOTE: some FTP servers may not support the FTP 'REST' command. If that is the case with the server you are accessing, you will not be able to use the StartByte property.)


getTransferMode

public int getTransferMode()
The transfer mode (ASCII or Binary). If the value is 0 (default), the initial server mode will be used. The valid options for the TransferMode property are as follows:
tm_Default
The initial mode of the FTP server is taken. No change.
tm_ASCII
Files are transferred in ASCII mode (TYPE A).
tm_Binary
Files are transferred in Binary mode (TYPE I).


setTransferMode

public void setTransferMode(int transferMode)
                     throws IPWorksException
The transfer mode (ASCII or Binary). If the value is 0 (default), the initial server mode will be used. The valid options for the TransferMode property are as follows:
tm_Default
The initial mode of the FTP server is taken. No change.
tm_ASCII
Files are transferred in ASCII mode (TYPE A).
tm_Binary
Files are transferred in Binary mode (TYPE I).


getUser

public java.lang.String getUser()
The user id to login as. This property must be set before the class connects to the FTP server.


setUser

public void setUser(java.lang.String user)
             throws IPWorksException
The user id to login as. This property must be set before the class connects to the FTP server.


fireDirList

public void fireDirList(java.lang.String dirEntry,
                        java.lang.String fileName,
                        boolean isDir,
                        int fileSize,
                        java.lang.String fileTime)
Fired when a directory entry is received. (Called internally to dispatch the event.)
See Also:
FtpDirListEvent

fireEndTransfer

public void fireEndTransfer()
Fired when a file completes downloading/uploading. (Called internally to dispatch the event.)
See Also:
FtpEndTransferEvent

fireError

public void fireError(int errorCode,
                      java.lang.String description)
Information about errors during data delivery. (Called internally to dispatch the event.)
See Also:
FtpErrorEvent

firePITrail

public void firePITrail(int direction,
                        java.lang.String message)
Traces the commands sent to the ftp server, and the respective replies. (Called internally to dispatch the event.)
See Also:
FtpPITrailEvent

fireStartTransfer

public void fireStartTransfer()
Fired when a file starts downloading/uploading. (Called internally to dispatch the event.)
See Also:
FtpStartTransferEvent

fireTransfer

public void fireTransfer(int bytesTransferred,
                         byte[] text)
Fired during file download/upload. (Called internally to dispatch the event.)
See Also:
FtpTransferEvent

addFtpEventListener

public void addFtpEventListener(FtpEventListener l)
                         throws java.util.TooManyListenersException

removeFtpEventListener

public void removeFtpEventListener(FtpEventListener l)

IP*Works!

Copyright (c) 1995-2000 by /n software inc. - All rights reserved.