com.ibm.as400.access
Class FTP

java.lang.Object
  |
  +--com.ibm.as400.access.FTP
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AS400FTP

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

The FTP class represents a generic ftp client. Methods on the FTP class allow you to connect to an ftp server, send commands to the server, list files on the server, get files from the server, and put files to the server.

Most methods that communicate with the server return a boolean to indicate if the request was successful. The message returned from the server is also available. getLastMessage() is used to retrieve the message from the previous request.

By default, FTP command are sent via server port 21. The initial data transfer type is ASCII. Passive mode is used.

No encryption is provided by this class. The user and password flow un-encrypted to the server. This class is not SSL enabled.

The forward slash is the separator character for paths sent to the FTP server.

Trace information is available by using the com.ibm.as400.access.Trace class. When trace is turned on via that class, FTP will produce debug information.

The following example copies a set of files from a directory on the server.

See Also:
Serialized Form

Field Summary
static int ASCII
          Transfer files in ASCII mode.
static int BINARY
          Transfer files in binary mode.
 
Constructor Summary
FTP()
          Constructs an FTP object.
FTP(java.lang.String server)
          Constructs an FTP object.
FTP(java.lang.String server, java.lang.String user, java.lang.String password)
          Constructs an FTP object.
 
Method Summary
 void addFTPListener(FTPListener listener)
          Adds a listener to be notified when an FTP event is fired.
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a listener to be notified when the value of any bound property is changed.
 void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
          Adds a listener to be notified when the value of any constrained property is changed.
 boolean cd(java.lang.String directory)
          Sets the current directory on the server to directory.
 boolean connect()
          Connects to the server.
 java.lang.String[] dir()
          Lists the contents of the current working directory.
 java.lang.String[] dir(java.lang.String criteria)
          Lists the contents of the current directory.
 void disconnect()
          Closes the connection with the server.
protected  void finalize()
          Closes all streams and sockets before this object is garbage collected.
 java.io.InputStream get(java.lang.String fileName)
          Starts the process of getting a file from the server.
 boolean get(java.lang.String sourceFileName, java.io.File targetFile)
          Gets a file from the server.
 boolean get(java.lang.String sourceFileName, java.lang.String targetFileName)
          Gets a file from the server.
 int getBufferSize()
          Returns the size of the buffer used when transferring files.
 java.lang.String getCurrentDirectory()
          Returns the current directory on the server.
 java.lang.String getLastMessage()
          Returns the text of the last reply returned from the server.
 int getPort()
          Returns the port used to connect to the system.
 java.lang.String getServer()
          Returns the name of the server.
 java.lang.String getUser()
          Returns the user.
 java.lang.String issueCommand(java.lang.String cmd)
          Sends a command to the server, returning the reply from the server.
 java.lang.String[] ls()
          Lists the contents of the current working directory.
 java.lang.String[] ls(java.lang.String criteria)
          Lists the contents of the current working directory.
 boolean noop()
          Sends the NOOP (no operation) command to the server.
 boolean put(java.io.File sourceFileName, java.lang.String targetFileName)
          Puts a file to the server.
 java.io.OutputStream put(java.lang.String fileName)
          Starts the process of putting a file to the server.
 boolean put(java.lang.String sourceFileName, java.lang.String targetFileName)
          Puts a file to the server.
 java.lang.String pwd()
          Returns the current directory on the server.
 void removeFTPListener(FTPListener listener)
          Removes a listener from the list.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes this listener from being notified when a bound property changes.
 void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
          Removes this listener from being notified when a constrained property changes.
 void setBufferSize(int bufferSize)
          Sets the buffer size used when transferring files.
 boolean setCurrentDirectory(java.lang.String directory)
          Sets the current directory on the server to directory.
 void setDataTransferType(int transferType)
          Sets the data transfer type.
 void setPassword(java.lang.String password)
          Sets the password.
 void setPort(int port)
          Sets the port to use when connecting to the server.
 void setServer(java.lang.String server)
          Sets the name of the server.
 void setUser(java.lang.String user)
          Sets the user identifier used when connecting to the server.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ASCII

public static final int ASCII
Transfer files in ASCII mode.

BINARY

public static final int BINARY
Transfer files in binary mode.
Constructor Detail

FTP

public FTP()
Constructs an FTP object. The server name, user and password must be set before requests are sent to the server.

FTP

public FTP(java.lang.String server)
Constructs an FTP object. The user and password must be set before requests are sent to the server.
Parameters:
server - The system to which to connect.

FTP

public FTP(java.lang.String server,
           java.lang.String user,
           java.lang.String password)
Constructs an FTP object.
Parameters:
server - The system to which to connect.
user - The userid to use during the login.
password - The password to use during the login.
Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds a listener to be notified when the value of any bound property is changed. It can be removed with removePropertyChangeListener.
Parameters:
listener - The PropertyChangeListener.

addFTPListener

public void addFTPListener(FTPListener listener)
Adds a listener to be notified when an FTP event is fired.
Parameters:
listener - The object listener.

addVetoableChangeListener

public void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
Adds a listener to be notified when the value of any constrained property is changed.
Parameters:
listener - The VetoableChangeListener.

cd

public boolean cd(java.lang.String directory)
           throws java.io.IOException
Sets the current directory on the server to directory. The method is the same as setCurrentDirectory(). The message returned from the server is saved. Use getLastMessage() to retrieve it.
Throws SecurityException if userid or password is invalid.
Parameters:
directory - The current directory to set on the server.
Returns:
true if directory changed; false otherwise.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

connect

public boolean connect()
                throws java.net.UnknownHostException,
                       java.io.IOException,
                       java.lang.IllegalStateException
Connects to the server. The connection is via port port. The user and password must be set before calling this method. Calling connect is optional. Methods that communicate with the server such as get, put, cd, and ls call connect() if necessary. The message returned from the server is saved. Use getLastMessage() to retrieve it.
Throws SecurityException if userid or password is invalid.
Returns:
true if connection is successful; false otherwise.
Throws:
java.net.UnknownHostException - If a path to the server cannot be found.
java.io.IOException - If an error occurs while connecting to the server.
java.lang.IllegalStateException - If called before user and password are set.

dir

public java.lang.String[] dir()
                       throws java.io.IOException
Lists the contents of the current working directory. File name and attributes are returned for each entry in the directory. An array of length zero is returned if the directory is empty.
Returns:
The contents of the directory as an array of Strings.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

dir

public java.lang.String[] dir(java.lang.String criteria)
                       throws java.io.IOException
Lists the contents of the current directory. File name and attributes are returned for each entry in the directory. A zero length array is returned if the directory is empty or if no files meet the search criteria.
Parameters:
criteria - The search criteria.
Returns:
The contents of the directory as an array of Strings.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

disconnect

public void disconnect()
                throws java.io.IOException
Closes the connection with the server. The connection is closed by sending the quit command to the server. The message returned from the server is saved. Use getLastMessage() to retrieve it.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

finalize

protected void finalize()
                 throws java.lang.Throwable
Closes all streams and sockets before this object is garbage collected.
Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable - If an error occurs during cleanup.

get

public java.io.InputStream get(java.lang.String fileName)
                        throws java.io.IOException,
                               java.io.FileNotFoundException
Starts the process of getting a file from the server. FTP opens the data connection to the server, then opens the file on the server and returns an input stream to the caller. The caller reads the file's data from the input stream. The source file is on the server, accessed via FTP so the path separator character (if any) must be a forward slash.
Throws SecurityException if userid or password is invalid.
Parameters:
fileName - The file to get.
Returns:
An input stream to the file. The caller uses the input stream to read the data from the file. Null is returned if the connection to the server fails.
Throws:
java.io.IOException - If an error occurs while communicating with the server.
java.io.FileNotFoundException - If the name is a directory or the name is not found.

get

public boolean get(java.lang.String sourceFileName,
                   java.lang.String targetFileName)
            throws java.io.IOException,
                   java.io.FileNotFoundException
Gets a file from the server. The source file is on the server, accessed via FTP so the path separator character (if any) must be a forward slash. The target file is on the client, accessed via java.io so the path separator character (if any) must be client specific.
Parameters:
sourceFileName - The file to get on the server.
targetFileName - The file on the target file system.
Returns:
true if the copy was successful; false otherwise.
Throws:
java.io.IOException - If an error occurs while communicating with the server.
java.io.FileNotFoundException - If the source file or the targe file cannot be accessed.

get

public boolean get(java.lang.String sourceFileName,
                   java.io.File targetFile)
            throws java.io.IOException,
                   java.io.FileNotFoundException
Gets a file from the server. The source file is on the server, accessed via FTP so the path separator character (if any) must be a forward slash. The target file is an instance of Java.io.file.
Throws SecurityException if userid or password is invalid.
Parameters:
sourceFileName - The file to get on the server.
targetFileName - The file on the target file system.
Returns:
true if the copy was successful; false otherwise.
Throws:
java.io.IOException - If an error occurs while communicating with the server.
java.io.FileNotFoundException - If the source file or the targe file cannot be accessed.

getBufferSize

public int getBufferSize()
Returns the size of the buffer used when transferring files. When this class copies data between the source file and target file, a buffer of this size is used. The default buffer size is 4096 bytes.
Returns:
The buffer size used when transferring files.

getCurrentDirectory

public java.lang.String getCurrentDirectory()
                                     throws java.io.IOException
Returns the current directory on the server.
Returns:
The current directory on the server. Null is returned if the connection to the server fails.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

getLastMessage

public java.lang.String getLastMessage()
Returns the text of the last reply returned from the server. Empty string is returned if no request has been sent.
Returns:
The text of the last reply returned from the server.

getPort

public int getPort()
Returns the port used to connect to the system.
Returns:
The port used to connect to the system.

getServer

public java.lang.String getServer()
Returns the name of the server. Null is returned if no system has been set.
Returns:
The name of the server to which this object connects.

getUser

public java.lang.String getUser()
Returns the user. Null is returned if no user has been set.
Returns:
The name of the user.

issueCommand

public java.lang.String issueCommand(java.lang.String cmd)
                              throws java.io.IOException
Sends a command to the server, returning the reply from the server.

The command is not altered before sending it to the server so it much be recognized by the server. Many FTP applications change commands so they are recognized by the server. For example, the command to get a list of files from the server is NLST, not ls. Many FTP applications convert ls to NLST before sending the command to the server. This method will not do the conversion.
Throws SecurityException if userid or password is invalid.

Parameters:
command - The command to send to the server.
Returns:
The reply to the command. Null is returned if the connection to the server fails.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

ls

public java.lang.String[] ls()
                      throws java.io.IOException
Lists the contents of the current working directory. If the directory is empty, an empty list is returned.
Returns:
The contents of the directory as an array of Strings.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

ls

public java.lang.String[] ls(java.lang.String criteria)
                      throws java.io.IOException
Lists the contents of the current working directory. If the directory is empty or no files match the search criteria, an empty list is returned.
Parameters:
criteria - The search criteria.
Returns:
The contents of the directory as an array of Strings.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

noop

public boolean noop()
             throws java.io.IOException
Sends the NOOP (no operation) command to the server. This request is most useful to see if the connection to the server is still active.
Throws SecurityException if userid or password is invalid.
Returns:
true if the request was successful, false otherwise.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

put

public java.io.OutputStream put(java.lang.String fileName)
                         throws java.io.IOException
Starts the process of putting a file to the server. FTP opens the data connection to the server, then opens the file on the server and returns an output stream to the caller. The caller then writes the file's data to the output stream.
Throws SecurityException if userid or password is invalid.
Parameters:
fileName - The file to put.
Returns:
An output stream to the file. The caller uses the output stream to write data to the file. Null is returned if the connection to the server fails.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

put

public boolean put(java.lang.String sourceFileName,
                   java.lang.String targetFileName)
            throws java.io.IOException
Puts a file to the server.
Parameters:
sourceFileName - The file to put.
targetFileName - The file on the server.
Returns:
true if the copy was successful; false otherwise.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

put

public boolean put(java.io.File sourceFileName,
                   java.lang.String targetFileName)
            throws java.io.IOException
Puts a file to the server.
Throws SecurityException if userid or password is invalid.
Parameters:
sourceFileName - The file to put.
targetFileName - The file on the server.
Returns:
true if the copy was successful; false otherwise.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

pwd

public java.lang.String pwd()
                     throws java.io.IOException
Returns the current directory on the server. PWD is the ftp command Print Working Directory.
Throws SecurityException if userid or password is invalid.
Returns:
The current directory on the server. Null is returned if the connection to the server fails.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes this listener from being notified when a bound property changes.
Parameters:
listener - The PropertyChangeListener.

removeFTPListener

public void removeFTPListener(FTPListener listener)
Removes a listener from the list.
Parameters:
listener - The FTP listener.

removeVetoableChangeListener

public void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
Removes this listener from being notified when a constrained property changes.
Parameters:
listener - The VetoableChangeListener.

setBufferSize

public void setBufferSize(int bufferSize)
                   throws java.beans.PropertyVetoException
Sets the buffer size used when transferring files. The default buffer size is 4096 bytes.
Parameters:
size - The size of the buffer used when transferring files.
Throws:
java.beans.PropertyVetoException - If the change is vetoed.

setCurrentDirectory

public boolean setCurrentDirectory(java.lang.String directory)
                            throws java.io.IOException
Sets the current directory on the server to directory. The method is the same as cd(). The message returned from the server is saved. Use getLastMessage() to retrieve it.
Parameters:
directory - The current directory to set on the server.
Returns:
true if directory changed; false otherwise.
Throws:
java.io.IOException - If an error occurs while communicating with the server.

setDataTransferType

public void setDataTransferType(int transferType)
                         throws java.io.IOException
Sets the data transfer type. Valid values are:

If a connection does not already exist, a connection is made to the server. The message returned from the server is saved. Use getLastMessage() to retrieve it.
Throws SecurityException if userid or password is invalid.

Throws:
java.io.IOException - If an error occurs while communicating with the server.

setPassword

public void setPassword(java.lang.String password)
Sets the password. The password cannot be changed once a connection is made to the server.
Parameters:
The - password for the user.

setPort

public void setPort(int port)
             throws java.beans.PropertyVetoException
Sets the port to use when connecting to the server. The port cannot be changed once a connection is made to the server.
Parameters:
Port - The port to use when connecting to the server.
Throws:
java.beans.PropertyVetoException - If the change is vetoed.

setServer

public void setServer(java.lang.String server)
               throws java.beans.PropertyVetoException
Sets the name of the server. The system name cannot be changed once a connection is made to the server.
Parameters:
The - name of the server to which this object connects.
Throws:
java.beans.PropertyVetoException - If the change is vetoed.

setUser

public void setUser(java.lang.String user)
             throws java.beans.PropertyVetoException
Sets the user identifier used when connecting to the server. If the client is connected to the server, this method will disconnect the connection
Parameters:
user - The user identifier used when connecting to the server.
Throws:
java.beans.PropertyVetoException - If the change is vetoed.
java.lang.IllegalStateException - If connection already established to the server.