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
    Represents a generic FTP client. Methods on this class allow you to connect to an FTP server, send commands to the system, list files on the system, get files from the system, and put files to the system.

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

    By default, FTP commands are sent via 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 system. 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 system.

     FTP client = new FTP("mysystem", "myUID", "myPWD");
     client.cd("/myDir");
     client.setDataTransferType(FTP.BINARY);
     String [] entries = client.ls();
    
     for (int i = 0; i < entries.length; i++)
     {
        System.out.println("Copying " + entries[i]);
        try
        {
           client.get(entries[i], "c:\\ftptest\\" + entries[i]);
        }
        catch (Exception e)
        {
           System.out.println("  copy failed, likely this is a directory");
        }
     }
    
     client.disconnect();
    
     
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static int ACTIVE_MODE
      Use active mode transfers with the system.
      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 system.
    • Constructor Summary

      Constructors 
      Constructor and Description
      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

      Methods 
      Modifier and Type Method and Description
      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 append(java.io.File sourceFileName, java.lang.String targetFileName)
      Appends data to a file on the system.
      java.io.OutputStream append(java.lang.String fileName)
      Starts the process of appending data to a file on the system.
      boolean append(java.lang.String sourceFileName, java.lang.String targetFileName)
      Appends data to a file on the system.
      boolean cd(java.lang.String directory)
      Sets the current directory on the system to directory.
      boolean connect()
      Connects to the system.
      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 system.
      protected void finalize()
      Closes all streams and sockets before this object is garbage collected.
      static java.lang.String generateNewName(java.lang.String fromName, java.lang.String toName)
      Returns a new file name constructed out of the old file name and a simple expression containing asterisks.
      java.io.InputStream get(java.lang.String fileName)
      Starts the process of getting a file from the system.
      boolean get(java.lang.String sourceFileName, java.io.File targetFile)
      Gets a file from the system.
      boolean get(java.lang.String sourceFileName, java.lang.String targetFileName)
      Gets a file from the system.
      int getBufferSize()
      Returns the size of the buffer used when transferring files.
      java.lang.String getCurrentDirectory()
      Returns the current directory on the system.
      java.lang.String getLastMessage()
      Returns the text of the last reply returned from the system.
      int getMode()
      Returns the current transfer mode.
      int getPort()
      Returns the port used to connect to the system.
      java.lang.String getServer()
      Returns the name of the system.
      java.lang.String getUser()
      Returns the user.
      boolean isReuseSocket()
      Indicates whether the socket is reused for multiple file transfers, when in active mode.
      java.lang.String issueCommand(java.lang.String cmd)
      Sends a command to the system, returning the reply from the system.
      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 system.
      boolean put(java.io.File sourceFileName, java.lang.String targetFileName)
      Puts a file to the system.
      java.io.OutputStream put(java.lang.String fileName)
      Starts the process of putting a file to the system.
      boolean put(java.lang.String sourceFileName, java.lang.String targetFileName)
      Puts a file to the system.
      java.lang.String pwd()
      Returns the current directory on the system.
      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.
      int ren(java.lang.String fromName, java.lang.String toName)
      Renames one or more files on the system, according to a specified pattern.
      void setBufferSize(int bufferSize)
      Sets the buffer size used when transferring files.
      boolean setCurrentDirectory(java.lang.String directory)
      Sets the current directory on the system to directory.
      void setDataTransferType(int transferType)
      Sets the data transfer type.
      void setMode(int mode)
      Sets the transfer mode.
      void setPassword(java.lang.String password)
      Sets the password.
      void setPort(int port)
      Sets the port to use when connecting to the system.
      void setReuseSocket(boolean reuse)
      Indicates whether to reuse a socket for multiple file transfers, when in active mode.
      void setServer(java.lang.String server)
      Sets the name of the system.
      void setTimeOut(int socketTimeOut) 
      void setUser(java.lang.String user)
      Sets the user identifier used when connecting to the system.
      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • ACTIVE_MODE

        public static final int ACTIVE_MODE
        Use active mode transfers with the system.
        See Also:
        Constant Field Values
      • PASSIVE_MODE

        public static final int PASSIVE_MODE
        Use passive mode transfers with the system. This is the default.
        See Also:
        Constant Field Values
    • Constructor Detail

      • FTP

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

        public FTP(java.lang.String server)
        Constructs an FTP object. The user and password must be set before requests are sent to the system.
        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.
      • append

        public java.io.OutputStream append(java.lang.String fileName)
                                    throws java.io.IOException
        Starts the process of appending data to a file on the system. FTP opens the data connection to the system, then opens the file on the system 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 system fails.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • append

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

        public boolean append(java.io.File sourceFileName,
                     java.lang.String targetFileName)
                       throws java.io.IOException
        Appends data to a file on the system.
        Throws SecurityException if userid or password is invalid.
        Parameters:
        sourceFileName - The file to put.
        targetFileName - The file on the system.
        Returns:
        true if the copy was successful; false otherwise.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • 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 system to directory. The method is the same as setCurrentDirectory(). The message returned from the system is saved. Use getLastMessage() to retrieve it.
        Throws SecurityException if userid or password is invalid.
        Parameters:
        directory - The current directory to set on the system.
        Returns:
        true if directory changed; false otherwise.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • connect

        public boolean connect()
                        throws java.net.UnknownHostException,
                               java.io.IOException,
                               java.lang.IllegalStateException
        Connects to the system. 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 system such as get, put, cd, and ls call connect() if necessary. The message returned from the system 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 system cannot be found.
        java.io.IOException - If an error occurs while connecting to the system.
        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 system.
      • 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 system.
      • disconnect

        public void disconnect()
                        throws java.io.IOException
        Closes the connection with the system. The connection is closed by sending the quit command to the system. The message returned from the system is saved. Use getLastMessage() to retrieve it.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • 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 system. FTP opens the data connection to the system, then opens the file on the system 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 system, 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 system fails.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
        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 system. The source file is on the system, 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 system.
        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 system.
        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 system. The source file is on the system, 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 system.
        targetFile - 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 system.
        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 system.
        Returns:
        The current directory on the system. Null is returned if the connection to the system fails.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • getLastMessage

        public java.lang.String getLastMessage()
        Returns the text of the last reply returned from the system. Empty string is returned if no request has been sent.
        Returns:
        The text of the last reply returned from the system.
      • 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 java.lang.String getServer()
        Returns the name of the system. Null is returned if no system has been set.
        Returns:
        The name of the system 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.
      • 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 java.lang.String issueCommand(java.lang.String cmd)
                                      throws java.io.IOException
        Sends a command to the system, returning the reply from the system.

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

        Parameters:
        cmd - The command to send to the system.
        Returns:
        The reply to the command. Null is returned if the connection to the system fails.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • 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 system.
      • 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 system.
      • noop

        public boolean noop()
                     throws java.io.IOException
        Sends the NOOP (no operation) command to the system. This request is most useful to see if the connection to the system 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 system.
      • put

        public java.io.OutputStream put(java.lang.String fileName)
                                 throws java.io.IOException
        Starts the process of putting a file to the system. FTP opens the data connection to the system, then opens the file on the system 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 system fails.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • put

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

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

        public java.lang.String pwd()
                             throws java.io.IOException
        Returns the current directory on the system. PWD is the ftp command Print Working Directory.
        Throws SecurityException if userid or password is invalid.
        Returns:
        The current directory on the system. Null is returned if the connection to the system fails.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • 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:
        bufferSize - 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 system to directory. The method is the same as cd(). The message returned from the system is saved. Use getLastMessage() to retrieve it.
        Parameters:
        directory - The current directory to set on the system.
        Returns:
        true if directory changed; false otherwise.
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • 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 system. The message returned from the system is saved. Use getLastMessage() to retrieve it.
        Throws SecurityException if userid or password is invalid.

        Parameters:
        transferType - ASCII or BINARY
        Throws:
        java.io.IOException - If an error occurs while communicating with the system.
      • 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(java.lang.String password)
        Sets the password. The password cannot be changed once a connection is made to the system.
        Parameters:
        password - The password for the user.
      • setPort

        public void setPort(int port)
                     throws java.beans.PropertyVetoException
        Sets the port to use when connecting to the system. The port cannot be changed once a connection is made to the system.
        Parameters:
        port - The port to use when connecting to the system.
        Throws:
        java.beans.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 system.
        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(java.lang.String server)
                       throws java.beans.PropertyVetoException
        Sets the name of the system. The system name cannot be changed once a connection is made to the system.
        Parameters:
        server - The name of the system 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 system. If the client is connected to the system, this method will disconnect the connection
        Parameters:
        user - The user identifier used when connecting to the system.
        Throws:
        java.beans.PropertyVetoException - If the change is vetoed.
        java.lang.IllegalStateException - If connection already established to the system.
      • ren

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

        For example:

        • ren("*.txt","*.DONE") renames "file1.txt" to "file1.DONE", and so on
        • ren("*.txt","*_DONE.*) renames "file1.txt" to "file1_DONE.txt", and so on
        • ren("*.txt","*_1055am") renames "file1.txt" to "file1.txt_1055am", and so on
        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:
        java.io.IOException - If an error occurs while communicating with the system.
      • generateNewName

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

        For example:

        • generateNewName("file.txt","*.DONE") returns "file.DONE"
        • generateNewName("file.txt","*_DONE.*) returns "file_DONE.txt"
        • generateNewName("file.txt","*_1055am") returns "file.txt_1055am"
        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:
        java.lang.NullPointerException - if the fromName or toName parameters are null.
        java.lang.IllegalArgumentException - if fromName or toName is null, or if the toName contains an invalid expression.
      • setTimeOut

        public void setTimeOut(int socketTimeOut)