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.
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 |
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
Ftp
public Ftp()
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)
Copyright (c) 1995-2000 by /n software inc. - All rights reserved.