Class GridFTPClient


  • public class GridFTPClient
    extends FTPClient
    This is the main user interface for GridFTP operations. Use this class for client - server or third party transfers with mode E, parallelism, markers, striping or GSI authentication. Consult the manual for general usage.
    Note: If using with GridFTP servers operations like setMode(), setType(), setDataChannelProtection(), and setDataChannelAuthentication() that affect data channel settings must be called before passive or active data channel mode is set.
    • Field Detail

      • logger

        private static org.apache.commons.logging.Log logger
      • usageString

        protected java.lang.String usageString
    • Constructor Detail

      • GridFTPClient

        public GridFTPClient​(java.lang.String host,
                             int port)
                      throws java.io.IOException,
                             ServerException
        Constructs client and connects it to the remote server.
        Parameters:
        host - remote server host
        port - remote server port
        Throws:
        java.io.IOException
        ServerException
    • Method Detail

      • authenticate

        public void authenticate​(org.ietf.jgss.GSSCredential credential)
                          throws java.io.IOException,
                                 ServerException
        Performs authentication with specified user credentials.
        Parameters:
        credential - user credentials to use.
        Throws:
        java.io.IOException - on i/o error
        ServerException - on server refusal or faulty server behavior
      • setUsageInformation

        public void setUsageInformation​(java.lang.String appName,
                                        java.lang.String appVer)
      • authenticate

        public void authenticate​(org.ietf.jgss.GSSCredential credential,
                                 java.lang.String username)
                          throws java.io.IOException,
                                 ServerException
        Performs authentication with specified user credentials and a specific username (assuming the user dn maps to the passed username).
        Parameters:
        credential - user credentials to use.
        username - specific username to authenticate as.
        Throws:
        java.io.IOException - on i/o error
        ServerException - on server refusal or faulty server behavior
      • list

        public java.util.Vector list​(java.lang.String filter,
                                     java.lang.String modifier)
                              throws ServerException,
                                     ClientException,
                                     java.io.IOException
        Performs remote directory listing like FTPClient.list(). Note: This method cannot be used in conjunction with parallelism or striping; set parallelism to 1 before calling it. Otherwise, use FTPClient.list(). Unlike in vanilla FTP, here IMAGE mode is allowed. For more documentation, look at FTPClient.
        Overrides:
        list in class FTPClient
        Parameters:
        filter - "*" for example, can be null.
        modifier - "-d" for example, can be null.
        Returns:
        Vector list of FileInfo objects, representing remote files
        Throws:
        ServerException
        ClientException
        java.io.IOException
        See Also:
        FTPClient.mlsd(String)
      • nlist

        public java.util.Vector nlist​(java.lang.String path)
                               throws ServerException,
                                      ClientException,
                                      java.io.IOException
        Performs remote directory listing like FTPClient.nlist(). Note: This method cannot be used in conjunction with parallelism or striping; set parallelism to 1 before calling it. Otherwise, use FTPClient.nlist(). Unlike in vanilla FTP, here IMAGE mode is allowed. For more documentation, look at FTPClient.
        Overrides:
        nlist in class FTPClient
        Parameters:
        path - directory to perform listing of. If null, listing of current directory will be performed.
        Returns:
        Vector list of FileInfo objects, representing remote files
        Throws:
        ServerException
        ClientException
        java.io.IOException
      • mlsd

        public java.util.Vector mlsd​(java.lang.String filter)
                              throws ServerException,
                                     ClientException,
                                     java.io.IOException
        Performs remote directory listing like FTPClient.mlsd(). Note: This method cannot be used in conjunction with parallelism or striping; set parallelism to 1 before calling it. Otherwise, use FTPClient.mlsd(). Unlike in vanilla FTP, here IMAGE mode is allowed. For more documentation, look at FTPClient.
        Overrides:
        mlsd in class FTPClient
        Parameters:
        filter - directory to perform listing of. If null, listing of current directory will be performed.
        Returns:
        Vector list of MlsxEntry objects, representing remote files
        Throws:
        ServerException
        ClientException
        java.io.IOException
      • getModeStr

        protected java.lang.String getModeStr​(int mode)
        Overrides:
        getModeStr in class FTPClient
      • setTCPBufferSize

        public void setTCPBufferSize​(int size)
                              throws java.io.IOException,
                                     ServerException
        Sets remote server TCP buffer size, in the following way: First see if server supports "SBUF" and if so, use it. If not, try the following commands until success: "SITE RETRBUFSIZE", "SITE RBUFSZ", "SITE RBUFSIZ", "SITE STORBUFSIZE", "SITE SBUFSZ", "SITE SBUFSIZ", "SITE BUFSIZE". Returns normally if the server confirms successfull setting of the remote buffer size, both for sending and for receiving data. Otherwise, throws ServerException.
        Throws:
        java.io.IOException
        ServerException
      • setLocalTCPBufferSize

        public void setLocalTCPBufferSize​(int size)
                                   throws ClientException
        Sets local TCP buffer size (for both receiving and sending).
        Throws:
        ClientException
      • setStripedActive

        public void setStripedActive​(HostPortList hpl)
                              throws java.io.IOException,
                                     ServerException
        Sets remote server to striped active server mode (SPOR).
        Throws:
        java.io.IOException
        ServerException
      • setLocalStripedPassive

        public HostPortList setLocalStripedPassive​(int port,
                                                   int queue)
                                            throws java.io.IOException
        Starts local server in striped passive mode. Since the local server is not distributed, it will only listen on one socket.
        Parameters:
        port - required server port; can be set to FTPServerFacade.ANY_PORT
        queue - max size of queue of awaiting new data channel connection requests
        Returns:
        the HostPortList of 1 element representing the socket where the local server is listening
        Throws:
        java.io.IOException
      • setLocalStripedPassive

        public HostPortList setLocalStripedPassive()
                                            throws java.io.IOException
        Behaves like setLocalStripedPassive(FTPServerFacade.ANY_PORT, FTPServerFacade.DEFAULT_QUEUE)
        Throws:
        java.io.IOException
      • setLocalStripedActive

        public void setLocalStripedActive()
                                   throws ClientException,
                                          java.io.IOException
        Starts local server in striped active mode. setStripedPassive() must be called before that. This method takes no parameters. HostPortList of the remote server, known from the last call of setStripedPassive(), is stored internally and the local server will connect to this address.
        Throws:
        ClientException
        java.io.IOException
      • extendedGet

        public void extendedGet​(java.lang.String remoteFileName,
                                long size,
                                DataSink sink,
                                MarkerListener mListener)
                         throws java.io.IOException,
                                ClientException,
                                ServerException
        Performs extended retrieve (partial retrieve mode starting at offset 0).
        Parameters:
        remoteFileName - file to retrieve
        size - number of bytes of remote file to transmit
        sink - data sink to store the file
        mListener - marker listener
        Throws:
        java.io.IOException
        ClientException
        ServerException
      • extendedGet

        public void extendedGet​(java.lang.String remoteFileName,
                                long offset,
                                long size,
                                DataSink sink,
                                MarkerListener mListener)
                         throws java.io.IOException,
                                ClientException,
                                ServerException
        Performs extended retrieve (partial retrieve mode).
        Parameters:
        remoteFileName - file to retrieve
        offset - the staring offset in the remote file
        size - number of bytes of remote file to transmit
        sink - data sink to store the file
        mListener - marker listener
        Throws:
        java.io.IOException
        ClientException
        ServerException
      • extendedPut

        public void extendedPut​(java.lang.String remoteFileName,
                                DataSource source,
                                MarkerListener mListener)
                         throws java.io.IOException,
                                ServerException,
                                ClientException
        Performs extended store (adujsted store mode with offset 0).
        Parameters:
        remoteFileName - file name to store
        source - source for the data to transfer
        mListener - marker listener
        Throws:
        java.io.IOException
        ServerException
        ClientException
      • extendedPut

        public void extendedPut​(java.lang.String remoteFileName,
                                long offset,
                                DataSource source,
                                MarkerListener mListener)
                         throws java.io.IOException,
                                ServerException,
                                ClientException
        Performs extended store (adujsted store mode).
        Parameters:
        remoteFileName - file name to store
        offset - the offset added to the file pointer before storing the blocks of the file.
        source - source for the data to transfer
        mListener - marker listener
        Throws:
        java.io.IOException
        ServerException
        ClientException
      • extendedTransfer

        public void extendedTransfer​(java.lang.String remoteSrcFile,
                                     GridFTPClient destination,
                                     java.lang.String remoteDstFile,
                                     MarkerListener mListener)
                              throws java.io.IOException,
                                     ServerException,
                                     ClientException
        Performs a third-party transfer between two servers using extended block mode. If server modes are unset, source will be set to active and destination to passive.
        Parameters:
        remoteSrcFile - source filename
        destination - destination server
        remoteDstFile - destination filename
        mListener - transer progress listener. Can be set to null.
        Throws:
        java.io.IOException
        ServerException
        ClientException
      • extendedTransfer

        public void extendedTransfer​(java.lang.String remoteSrcFile,
                                     long remoteSrcFileOffset,
                                     long remoteSrcFileLength,
                                     GridFTPClient destination,
                                     java.lang.String remoteDstFile,
                                     long remoteDstFileOffset,
                                     MarkerListener mListener)
                              throws java.io.IOException,
                                     ServerException,
                                     ClientException
        Performs a third-party transfer between two servers using extended block mode. If server modes are unset, source will be set to active and destination to passive.
        Parameters:
        remoteSrcFile - source filename
        remoteSrcFileOffset - source filename offset
        remoteSrcFileLength - source filename length to transfer
        destination - destination server
        remoteDstFile - destination filename
        remoteDstFileOffset - destination filename offset
        mListener - transer progress listener. Can be set to null.
        Throws:
        java.io.IOException
        ServerException
        ClientException
      • checkGridFTPSupport

        protected void checkGridFTPSupport()
                                    throws java.io.IOException,
                                           ServerException
        assure that the server supports extended transfer features; throw exception if not
        Throws:
        java.io.IOException
        ServerException
      • setDataChannelAuthentication

        public void setDataChannelAuthentication​(DataChannelAuthentication type)
                                          throws java.io.IOException,
                                                 ServerException
        Sets data channel authentication mode (DCAU)
        Parameters:
        type - for 2-party transfer must be DataChannelAuthentication.SELF or DataChannelAuthentication.NONE
        Throws:
        java.io.IOException
        ServerException
      • setLocalNoDataChannelAuthentication

        public void setLocalNoDataChannelAuthentication()
        Sets compatibility mode with old GSIFTP server. Locally sets data channel authentication to NONE but does not send the command to the remote server (the server wouldn't understand it)
      • getDataChannelAuthentication

        public DataChannelAuthentication getDataChannelAuthentication()
        Returns data channel authentication mode (DCAU).
        Returns:
        data channel authentication mode
      • setDataChannelProtection

        public void setDataChannelProtection​(int protection)
                                      throws java.io.IOException,
                                             ServerException
        Sets data channel protection level (PROT).
        Parameters:
        protection - should be CLEAR, SAFE, or PRIVATE, or CONFIDENTIAL.
        Throws:
        java.io.IOException
        ServerException
      • getDataChannelProtection

        public int getDataChannelProtection()
        Returns data channel protection level.
        Returns:
        data channel protection level: CLEAR, SAFE, or PRIVATE, or CONFIDENTIAL.
      • setAuthorization

        public void setAuthorization​(Authorization authorization)
        Sets authorization method for the control channel.
        Parameters:
        authorization - authorization method.
      • getAuthorization

        public Authorization getAuthorization()
        Returns authorization method for the control channel.
        Returns:
        authorization method performed on the control channel.
      • setControlChannelProtection

        public void setControlChannelProtection​(int protection)
        Sets control channel protection level.
        Parameters:
        protection - should be CLEAR, SAFE, or PRIVATE, or CONFIDENTIAL.
      • getControlChannelProtection

        public int getControlChannelProtection()
        Returns control channel protection level.
        Returns:
        control channel protection level: CLEAR, SAFE, or PRIVATE, or CONFIDENTIAL.
      • setChecksum

        public void setChecksum​(ChecksumAlgorithm algorithm,
                                java.lang.String value)
                         throws java.io.IOException,
                                ServerException
        Sets the checksum values ahead of the transfer
        Parameters:
        algorithm - the checksume algorithm
        value - the checksum value as hexadecimal number
        Throws:
        ServerException - if an error occured.
        java.io.IOException
      • checksum

        public java.lang.String checksum​(ChecksumAlgorithm algorithm,
                                         long offset,
                                         long length,
                                         java.lang.String file)
                                  throws java.io.IOException,
                                         ServerException
        Computes and returns a checksum of a file. transferred.
        Parameters:
        algorithm - the checksume algorithm
        offset - the offset
        length - the length
        file - file to compute checksum of
        Returns:
        the computed checksum
        Throws:
        ServerException - if an error occured.
        java.io.IOException
      • mlsr

        public void mlsr​(java.lang.String path,
                         MlsxEntryWriter writer)
                  throws ServerException,
                         ClientException,
                         java.io.IOException
        Performs a recursive directory listing starting at the given path (or, if path is null, at the current directory of the FTP server). MlsxEntry instances for all of the files in the subtree will be written through the passed MlsxEntryWriter.
        Parameters:
        path - path to begin recursive directory listing
        writer - sink for created MlsxEntry instances
        Throws:
        ServerException
        ClientException
        java.io.IOException
      • changeGroup

        public void changeGroup​(java.lang.String group,
                                java.lang.String file)
                         throws java.io.IOException,
                                ServerException
        Change the Unix group membership of a file.
        Parameters:
        group - the name or ID of the group
        file - the file whose group membership should be changed
        Throws:
        ServerException - if an error occurred.
        java.io.IOException
      • changeModificationTime

        public void changeModificationTime​(int year,
                                           int month,
                                           int day,
                                           int hour,
                                           int min,
                                           int sec,
                                           java.lang.String file)
                                    throws java.io.IOException,
                                           ServerException
        Change the modification time of a file.
        Parameters:
        year - Modifcation year
        month - Modification month (1-12)
        day - Modification day (1-31)
        hour - Modification hour (0-23)
        min - Modification minutes (0-59)
        sec - Modification seconds (0-59)
        file - file whose modification time should be changed
        Throws:
        java.io.IOException
        ServerException - if an error occurred.
      • createSymbolicLink

        public void createSymbolicLink​(java.lang.String link_target,
                                       java.lang.String link_name)
                                throws java.io.IOException,
                                       ServerException
        Create a symbolic link on the FTP server.
        Parameters:
        link_target - the path to which the symbolic link should point
        link_name - the path of the symbolic link to create
        Throws:
        java.io.IOException
        ServerException - if an error occurred.