com.ibm.as400.access
Class FTP

java.lang.Object
  extended bycom.ibm.as400.access.FTP
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AS400FTP

public class FTP
extends Object
implements 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 ACTIVE_MODE
          Use active mode transfers with the server.
static int ASCII
          Transfer files in ASCII mode.
static int BINARY
          Transfer files in binary mode.
static int PASSIVE_MODE
          Use passive mode transfers with the server.
 
Constructor Summary
FTP()
          Constructs an FTP object.
FTP(String server)
          Constructs an FTP object.
FTP(String server, String user, 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(PropertyChangeListener listener)
          Adds a listener to be notified when the value of any bound property is changed.
 void addVetoableChangeListener(VetoableChangeListener listener)
          Adds a listener to be notified when the value of any constrained property is changed.
 boolean append(File sourceFileName, String targetFileName)
          Appends data to a file on the server.
 OutputStream append(String fileName)
          Starts the process of appending data to a file on the server.
 boolean append(String sourceFileName, String targetFileName)
          Appends data to a file on the server.
 boolean cd(String directory)
          Sets the current directory on the server to directory.
 boolean connect()
          Connects to the server.
 String[] dir()
          Lists the contents of the current working directory.
 String[] dir(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.
static String generateNewName(String fromName, String toName)
          Returns a new file name constructed out of the old file name and a simple expression containing asterisks.
 InputStream get(String fileName)
          Starts the process of getting a file from the server.
 boolean get(String sourceFileName, File targetFile)
          Gets a file from the server.
 boolean get(String sourceFileName, String targetFileName)
          Gets a file from the server.
 int getBufferSize()
          Returns the size of the buffer used when transferring files.
 String getCurrentDirectory()
          Returns the current directory on the server.
 String getLastMessage()
          Returns the text of the last reply returned from the server.
 int getMode()
          Returns the current transfer mode.
 int getPort()
          Returns the port used to connect to the system.
 String getServer()
          Returns the name of the server.
 String getUser()
          Returns the user.
 boolean isReuseSocket()
          Indicates whether the socket is reused for multiple file transfers, when in active mode.
 String issueCommand(String cmd)
          Sends a command to the server, returning the reply from the server.
 String[] ls()
          Lists the contents of the current working directory.
 String[] ls(String criteria)
          Lists the contents of the current working directory.
 boolean noop()
          Sends the NOOP (no operation) command to the server.
 boolean put(File sourceFileName, String targetFileName)
          Puts a file to the server.
 OutputStream put(String fileName)
          Starts the process of putting a file to the server.
 boolean put(String sourceFileName, String targetFileName)
          Puts a file to the server.
 String pwd()
          Returns the current directory on the server.
 void removeFTPListener(FTPListener listener)
          Removes a listener from the list.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Removes this listener from being notified when a bound property changes.
 void removeVetoableChangeListener(VetoableChangeListener listener)
          Removes this listener from being notified when a constrained property changes.
 int ren(String fromName, String toName)
          Renames one or more files on the server, according to a specified pattern.
 void setBufferSize(int bufferSize)
          Sets the buffer size used when transferring files.
 boolean setCurrentDirectory(String directory)
          Sets the current directory on the server to directory.
 void setDataTransferType(int transferType)
          Sets the data transfer type.
 void setMode(int mode)
          Sets the transfer mode.
 void setPassword(String password)
          Sets the password.
 void setPort(int port)
          Sets the port to use when connecting to the server.
 void setReuseSocket(boolean reuse)
          Indicates whether to reuse a socket for multiple file transfers, when in active mode.
 void setServer(String server)
          Sets the name of the server.
 void setUser(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.

See Also:
Constant Field Values

BINARY

public static final int BINARY
Transfer files in binary mode.

See Also:
Constant Field Values

ACTIVE_MODE

public static final int ACTIVE_MODE
Use active mode transfers with the server.

See Also:
Constant Field Values

PASSIVE_MODE

public static final int PASSIVE_MODE
Use passive mode transfers with the server. This is the default.

See Also:
Constant Field Values
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(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(String server,
           String user,
           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(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.

append

public OutputStream append(String fileName)
                    throws IOException
Starts the process of appending data to a file on 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:
IOException - If an error occurs while communicating with the server.

append

public boolean append(String sourceFileName,
                      String targetFileName)
               throws IOException
Appends data to a file on the server.

Parameters:
sourceFileName - The file to put.
targetFileName - The file on the server.
Returns:
true if the copy was successful; false otherwise.
Throws:
IOException - If an error occurs while communicating with the server.

append

public boolean append(File sourceFileName,
                      String targetFileName)
               throws IOException
Appends data to a file on 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:
IOException - If an error occurs while communicating with the server.

addVetoableChangeListener

public void addVetoableChangeListener(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(String directory)
           throws 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:
IOException - If an error occurs while communicating with the server.

connect

public boolean connect()
                throws UnknownHostException,
                       IOException,
                       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:
UnknownHostException - If a path to the server cannot be found.
IOException - If an error occurs while connecting to the server.
IllegalStateException - If called before user and password are set.

dir

public String[] dir()
             throws 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:
IOException - If an error occurs while communicating with the server.

dir

public String[] dir(String criteria)
             throws 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:
IOException - If an error occurs while communicating with the server.

disconnect

public void disconnect()
                throws 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:
IOException - If an error occurs while communicating with the server.

finalize

protected void finalize()
                 throws Throwable
Closes all streams and sockets before this object is garbage collected.

Throws:
Throwable - If an error occurs during cleanup.

get

public InputStream get(String fileName)
                throws IOException,
                       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:
IOException - If an error occurs while communicating with the server.
FileNotFoundException - If the name is a directory or the name is not found.

get

public boolean get(String sourceFileName,
                   String targetFileName)
            throws IOException,
                   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:
IOException - If an error occurs while communicating with the server.
FileNotFoundException - If the source file or the targe file cannot be accessed.

get

public boolean get(String sourceFileName,
                   File targetFile)
            throws IOException,
                   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.
targetFile - The file on the target file system.
Returns:
true if the copy was successful; false otherwise.
Throws:
IOException - If an error occurs while communicating with the server.
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 String getCurrentDirectory()
                           throws 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:
IOException - If an error occurs while communicating with the server.

getLastMessage

public 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.

getMode

public int getMode()
Returns the current transfer mode.

Returns:
The transfer mode. Valid values are ACTIVE_MODE or PASSIVE_MODE. The default is PASSIVE_MODE.

getPort

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

Returns:
The port used to connect to the system.

getServer

public 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 String getUser()
Returns the user. Null is returned if no user has been set.

Returns:
The name of the user.

isReuseSocket

public boolean isReuseSocket()
Indicates whether the socket is reused for multiple file transfers, when in active mode.

Returns:
true if the socket is reused; false if a new socket is created.
See Also:
setMode(int)

issueCommand

public String issueCommand(String cmd)
                    throws 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 must 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:
cmd - The command to send to the server.
Returns:
The reply to the command. Null is returned if the connection to the server fails.
Throws:
IOException - If an error occurs while communicating with the server.

ls

public String[] ls()
            throws 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:
IOException - If an error occurs while communicating with the server.

ls

public String[] ls(String criteria)
            throws 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:
IOException - If an error occurs while communicating with the server.

noop

public boolean noop()
             throws 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:
IOException - If an error occurs while communicating with the server.

put

public OutputStream put(String fileName)
                 throws 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:
IOException - If an error occurs while communicating with the server.

put

public boolean put(String sourceFileName,
                   String targetFileName)
            throws 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:
IOException - If an error occurs while communicating with the server.

put

public boolean put(File sourceFileName,
                   String targetFileName)
            throws 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:
IOException - If an error occurs while communicating with the server.

pwd

public String pwd()
           throws 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:
IOException - If an error occurs while communicating with the server.

removePropertyChangeListener

public void removePropertyChangeListener(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(VetoableChangeListener listener)
Removes this listener from being notified when a constrained property changes.

Parameters:
listener - The VetoableChangeListener.

setBufferSize

public void setBufferSize(int bufferSize)
                   throws PropertyVetoException
Sets the buffer size used when transferring files. The default buffer size is 4096 bytes.

Parameters:
bufferSize - The size of the buffer used when transferring files.
Throws:
PropertyVetoException - If the change is vetoed.

setCurrentDirectory

public boolean setCurrentDirectory(String directory)
                            throws 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:
IOException - If an error occurs while communicating with the server.

setDataTransferType

public void setDataTransferType(int transferType)
                         throws 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:
IOException - If an error occurs while communicating with the server.

setMode

public void setMode(int mode)
Sets the transfer mode.

Parameters:
mode - The mode. Valid values are ACTIVE_MODE or PASSIVE_MODE.

setPassword

public void setPassword(String password)
Sets the password. The password cannot be changed once a connection is made to the server.

Parameters:
password - The password for the user.

setPort

public void setPort(int port)
             throws 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:
PropertyVetoException - If the change is vetoed.

setReuseSocket

public void setReuseSocket(boolean reuse)
Indicates whether to reuse a socket for multiple file transfers, when in active mode. By default, the "reuse socket" attribute is set to the value of the com.ibm.as400.access.FTP.reuseSocket property. If the property is not set, the default is true (sockets are reused). The "reuse socket" attribute (of an FTP object) cannot be reset after that object has connected to the server.

Parameters:
reuse - If true, the socket is reused. If false, a new socket is created for each subsequent file transfer.
See Also:
setMode(int)

setServer

public void setServer(String server)
               throws PropertyVetoException
Sets the name of the server. The system name cannot be changed once a connection is made to the server.

Parameters:
server - The name of the server to which this object connects.
Throws:
PropertyVetoException - If the change is vetoed.

setUser

public void setUser(String user)
             throws 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:
PropertyVetoException - If the change is vetoed.
IllegalStateException - If connection already established to the server.

ren

public int ren(String fromName,
               String toName)
        throws IOException
Renames one or more files on the server, according to a specified pattern.

For example:

Parameters:
fromName - A pattern specifying the file(s) to be renamed. The syntax of the pattern is similar to the syntax for ls().
toName - The new file name, or a simple pattern describing how to construct the new name out of fromName. toName can contain up to two asterisks, one on each side of the ".".
Returns:
The number of files renamed.
Throws:
IOException - If an error occurs while communicating with the server.

generateNewName

public static String generateNewName(String fromName,
                                     String toName)
Returns a new file name constructed out of the old file name and a simple expression containing asterisks.

For example:

Parameters:
fromName - The original file name
toName - The new file name, or a simple pattern describing how to construct the new name out of fromName. toName can contain up to two asterisks, one on each side of the ".".
Returns:
The new file name.
Throws:
NullPointerException - if the fromName or toName parameters are null.
IllegalArgumentException - if fromName or toName is null, or if the toName contains an invalid expression.