org.globus.ftp
Class GridFTPClient

java.lang.Object
  extended by org.globus.ftp.FTPClient
      extended by org.globus.ftp.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 Summary
protected  GridFTPServerFacade gLocalServer
           
protected  GridFTPSession gSession
           
protected  java.lang.String usageString
           
 
Fields inherited from class org.globus.ftp.FTPClient
algorithms, controlChannel, dateFormat, localServer, portPattern, session, useAllo, username
 
Constructor Summary
GridFTPClient(java.lang.String host, int port)
          Constructs client and connects it to the remote server.
 
Method Summary
 void authenticate(org.ietf.jgss.GSSCredential credential)
          Performs authentication with specified user credentials.
 void authenticate(org.ietf.jgss.GSSCredential credential, java.lang.String username)
          Performs authentication with specified user credentials and a specific username (assuming the user dn maps to the passed username).
 void changeGroup(java.lang.String group, java.lang.String file)
          Change the Unix group membership of a file.
 void changeModificationTime(int year, int month, int day, int hour, int min, int sec, java.lang.String file)
          Change the modification time of a file.
protected  void checkGridFTPSupport()
          assure that the server supports extended transfer features; throw exception if not
 java.lang.String checksum(ChecksumAlgorithm algorithm, long offset, long length, java.lang.String file)
          Computes and returns a checksum of a file.
protected  void checkTransferParamsGet()
           
 void createSymbolicLink(java.lang.String link_target, java.lang.String link_name)
          Create a symbolic link on the FTP server.
 void extendedGet(java.lang.String remoteFileName, long size, DataSink sink, MarkerListener mListener)
          Performs extended retrieve (partial retrieve mode starting at offset 0).
 void extendedGet(java.lang.String remoteFileName, long offset, long size, DataSink sink, MarkerListener mListener)
          Performs extended retrieve (partial retrieve mode).
 void extendedMultipleTransfer(long[] remoteSrcFileOffset, long[] remoteSrcFileLength, java.lang.String[] remoteSrcFile, GridFTPClient destination, long[] remoteDstFileOffset, java.lang.String[] remoteDstFile, MarkerListener mListener, MultipleTransferCompleteListener doneListener)
           
 void extendedMultipleTransfer(java.lang.String[] remoteSrcFile, GridFTPClient destination, java.lang.String[] remoteDstFile, MarkerListener mListener, MultipleTransferCompleteListener doneListener)
           
 void extendedPut(java.lang.String remoteFileName, DataSource source, MarkerListener mListener)
          Performs extended store (adujsted store mode with offset 0).
 void extendedPut(java.lang.String remoteFileName, long offset, DataSource source, MarkerListener mListener)
          Performs extended store (adujsted store mode).
 void extendedTransfer(java.lang.String remoteSrcFile, GridFTPClient destination, java.lang.String remoteDstFile, MarkerListener mListener)
          Performs a third-party transfer between two servers using extended block mode.
 void extendedTransfer(java.lang.String remoteSrcFile, long remoteSrcFileOffset, long remoteSrcFileLength, GridFTPClient destination, java.lang.String remoteDstFile, long remoteDstFileOffset, MarkerListener mListener)
          Performs a third-party transfer between two servers using extended block mode.
 void get(java.lang.String remoteFileName, java.io.File localFile)
           
 Authorization getAuthorization()
          Returns authorization method for the control channel.
 int getControlChannelProtection()
          Returns control channel protection level.
 DataChannelAuthentication getDataChannelAuthentication()
          Returns data channel authentication mode (DCAU).
 int getDataChannelProtection()
          Returns data channel protection level.
protected  java.lang.String getModeStr(int mode)
           
 java.util.Vector list(java.lang.String filter, java.lang.String modifier)
          Performs remote directory listing like FTPClient.list().
protected  void listCheck()
          check performed at the beginning of list()
 java.util.Vector mlsd(java.lang.String filter)
          Performs remote directory listing like FTPClient.mlsd().
 void mlsr(java.lang.String path, MlsxEntryWriter writer)
          Performs a recursive directory listing starting at the given path (or, if path is null, at the current directory of the FTP server).
 java.util.Vector nlist(java.lang.String path)
          Performs remote directory listing like FTPClient.nlist().
 void put(java.io.File localFile, java.lang.String remoteFileName, boolean append)
           
 void setAuthorization(Authorization authorization)
          Sets authorization method for the control channel.
 void setChecksum(ChecksumAlgorithm algorithm, java.lang.String value)
          Sets the checksum values ahead of the transfer
 void setControlChannelProtection(int protection)
          Sets control channel protection level.
 void setDataChannelAuthentication(DataChannelAuthentication type)
          Sets data channel authentication mode (DCAU)
 void setDataChannelProtection(int protection)
          Sets data channel protection level (PROT).
 void setLocalNoDataChannelAuthentication()
          Sets compatibility mode with old GSIFTP server.
 void setLocalStripedActive()
          Starts local server in striped active mode.
 HostPortList setLocalStripedPassive()
          Behaves like setLocalStripedPassive(FTPServerFacade.ANY_PORT, FTPServerFacade.DEFAULT_QUEUE)
 HostPortList setLocalStripedPassive(int port, int queue)
          Starts local server in striped passive mode.
 void setLocalTCPBufferSize(int size)
          Sets local TCP buffer size (for both receiving and sending).
 void setStripedActive(HostPortList hpl)
          Sets remote server to striped active server mode (SPOR).
 HostPortList setStripedPassive()
          Sets remote server to striped passive server mode (SPAS).
 void setTCPBufferSize(int size)
          Sets remote server TCP buffer size, in the following way: First see if server supports "SBUF" and if so, use it.
 void setUsageInformation(java.lang.String appName, java.lang.String appVer)
           
 
Methods inherited from class org.globus.ftp.FTPClient
abort, actualSetMode, allocate, asynchGet, asynchGet2, asynchPut, asynchPut, asynchPut2, authorize, changeDir, checkGETPUTSupport, checkTransferParams, checkTransferParamsPut, close, close, deleteDir, deleteFile, exists, get, get127Reply, get2, getChecksum, getChecksum, getCurrentDir, getFeatureList, getHost, getLastModified, getLastReply, getPort, getSize, getSupportedCksumAlgorithms, getUseAllo, getUserName, goUpDir, isActiveMode, isCksumAlgorithmSupported, isFeatureSupported, isPassiveMode, lastModified, list, list, list, makeDir, mlsd, mlsd, mlst, nlist, nlist, performTransfer, put, put, put2, quote, rename, setActive, setActive, setChecksum, setClientWaitParams, setLocalActive, setLocalPassive, setLocalPassive, setMode, setOptions, setPassive, setPassiveMode, setProtectionBufferSize, setRestartMarker, setType, setUseAllo, site, size, transfer, transfer, transferBegin, transferRun, transferRunSingleThread, transferStart, transferWait
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

gSession

protected GridFTPSession gSession

gLocalServer

protected GridFTPServerFacade gLocalServer

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

listCheck

protected void listCheck()
                  throws ClientException
Description copied from class: FTPClient
check performed at the beginning of list()

Overrides:
listCheck in class FTPClient
Throws:
ClientException

checkTransferParamsGet

protected void checkTransferParamsGet()
                               throws ServerException,
                                      java.io.IOException,
                                      ClientException
Overrides:
checkTransferParamsGet in class FTPClient
Throws:
ServerException
java.io.IOException
ClientException

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

setStripedPassive

public HostPortList setStripedPassive()
                               throws java.io.IOException,
                                      ServerException
Sets remote server to striped passive server mode (SPAS).

Throws:
java.io.IOException
ServerException

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

extendedMultipleTransfer

public void extendedMultipleTransfer(long[] remoteSrcFileOffset,
                                     long[] remoteSrcFileLength,
                                     java.lang.String[] remoteSrcFile,
                                     GridFTPClient destination,
                                     long[] remoteDstFileOffset,
                                     java.lang.String[] remoteDstFile,
                                     MarkerListener mListener,
                                     MultipleTransferCompleteListener doneListener)
                              throws java.io.IOException,
                                     ServerException,
                                     ClientException
Throws:
java.io.IOException
ServerException
ClientException

extendedMultipleTransfer

public void extendedMultipleTransfer(java.lang.String[] remoteSrcFile,
                                     GridFTPClient destination,
                                     java.lang.String[] remoteDstFile,
                                     MarkerListener mListener,
                                     MultipleTransferCompleteListener doneListener)
                              throws java.io.IOException,
                                     ServerException,
                                     ClientException
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.

get

public void get(java.lang.String remoteFileName,
                java.io.File localFile)
         throws java.io.IOException,
                ClientException,
                ServerException
Overrides:
get in class FTPClient
Throws:
java.io.IOException
ClientException
ServerException

put

public void put(java.io.File localFile,
                java.lang.String remoteFileName,
                boolean append)
         throws java.io.IOException,
                ServerException,
                ClientException
Overrides:
put in class FTPClient
Throws:
java.io.IOException
ServerException
ClientException

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.


Copyright © 2013. All Rights Reserved.