Package org.globus.ftp

# Class GridFTPClient

java.lang.Object
org.globus.ftp.FTPClient
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

Fields
Modifier and Type
Field
Description
`protected GridFTPServerFacade`
`gLocalServer`
`protected GridFTPSession`
`gSession`
`protected String`
`usageString`

### Fields inherited from class org.globus.ftp.FTPClient

`algorithms, controlChannel, dateFormat, localServer, portPattern, session, useAllo, username`

## Constructor Summary

Constructors
Constructor
Description
`GridFTPClient(String host, int port)`
Constructs client and connects it to the remote server.

## Method Summary

Modifier and Type
Method
Description
`void`
`authenticate(GSSCredential credential)`
Performs authentication with specified user credentials.
`void`
`authenticate(GSSCredential credential, String username)`
Performs authentication with specified user credentials and a specific username (assuming the user dn maps to the passed username).
`void`
`changeGroup(String group, String file)`
Change the Unix group membership of a file.
`void`
`changeModificationTime(int year, int month, int day, int hour, int min, int sec, String file)`
Change the modification time of a file.
`protected void`
`checkGridFTPSupport()`
assure that the server supports extended transfer features; throw exception if not
`String`
`checksum(ChecksumAlgorithm algorithm, long offset, long length, String file)`
Computes and returns a checksum of a file.
`protected void`
`checkTransferParamsGet()`
`void`
`createSymbolicLink(String link_target, String link_name)`
Create a symbolic link on the FTP server.
`void`
`extendedGet(String remoteFileName, long offset, long size, DataSink sink, MarkerListener mListener)`
Performs extended retrieve (partial retrieve mode).
`void`
`extendedGet(String remoteFileName, long size, DataSink sink, MarkerListener mListener)`
Performs extended retrieve (partial retrieve mode starting at offset 0).
`void`
`extendedMultipleTransfer(long[] remoteSrcFileOffset, long[] remoteSrcFileLength, String[] remoteSrcFile, GridFTPClient destination, long[] remoteDstFileOffset, String[] remoteDstFile, MarkerListener mListener, MultipleTransferCompleteListener doneListener)`
`void`
`extendedMultipleTransfer(String[] remoteSrcFile, GridFTPClient destination, String[] remoteDstFile, MarkerListener mListener, MultipleTransferCompleteListener doneListener)`
`void`
`extendedPut(String remoteFileName, long offset, DataSource source, MarkerListener mListener)`
Performs extended store (adujsted store mode).
`void`
`extendedPut(String remoteFileName, DataSource source, MarkerListener mListener)`
Performs extended store (adujsted store mode with offset 0).
`void`
`extendedTransfer(String remoteSrcFile, long remoteSrcFileOffset, long remoteSrcFileLength, GridFTPClient destination, String remoteDstFile, long remoteDstFileOffset, MarkerListener mListener)`
Performs a third-party transfer between two servers using extended block mode.
`void`
`extendedTransfer(String remoteSrcFile, GridFTPClient destination, String remoteDstFile, MarkerListener mListener)`
Performs a third-party transfer between two servers using extended block mode.
`void`
`get(String remoteFileName, 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 String`
`getModeStr(int mode)`
`Vector`
`list(String filter, String modifier)`
Performs remote directory listing like `FTPClient.list()`.
`protected void`
`listCheck()`
check performed at the beginning of list()
`Vector`
`mlsd(String filter)`
Performs remote directory listing like `FTPClient.mlsd()`.
`void`
`mlsr(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).
`Vector`
`nlist(String path)`
Performs remote directory listing like `FTPClient.nlist()`.
`void`
`put(File localFile, String remoteFileName, boolean append)`
`void`
`setAuthorization(Authorization authorization)`
Sets authorization method for the control channel.
`void`
`setChecksum(ChecksumAlgorithm algorithm, 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(String appName, 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 Details

### gSession

protected GridFTPSession gSession

### gLocalServer

protected GridFTPServerFacade gLocalServer

### usageString

protected String usageString

## Constructor Details

### GridFTPClient

public GridFTPClient(String host, int port) throws IOException, ServerException
Constructs client and connects it to the remote server.

Parameters:
  `host` - remote server host
  `port` - remote server port
Throws:
  `IOException`
  `ServerException`

## Method Details

### authenticate

public void authenticate(GSSCredential credential) throws IOException, ServerException
Performs authentication with specified user credentials.

Parameters:
  `credential` - user credentials to use.
Throws:
  `IOException` - on i/o error
  `ServerException` - on server refusal or faulty server behavior

### setUsageInformation

public void setUsageInformation(String appName, String appVer)

### authenticate

public void authenticate(GSSCredential credential, String username) throws 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:
  `IOException` - on i/o error
  `ServerException` - on server refusal or faulty server behavior

### list

public Vector list(String filter, String modifier) throws ServerException, ClientException, 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`
  `IOException`
See Also:
  - `FTPClient.mlsd(String)`

### nlist

public Vector nlist(String path) throws ServerException, ClientException, 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`
  `IOException`

### mlsd

public Vector mlsd(String filter) throws ServerException, ClientException, 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`
  `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, IOException, ClientException

Overrides:
  `checkTransferParamsGet` in class `FTPClient`
Throws:
  `ServerException`
  `IOException`
  `ClientException`

### getModeStr

protected String getModeStr(int mode)

Overrides:
  `getModeStr` in class `FTPClient`

### setTCPBufferSize

public void setTCPBufferSize(int size) throws 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:
  `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 IOException, ServerException
Sets remote server to striped passive server mode (SPAS).

Throws:
  `IOException`
  `ServerException`

### setStripedActive

public void setStripedActive(HostPortList hpl) throws IOException, ServerException
Sets remote server to striped active server mode (SPOR).

Throws:
  `IOException`
  `ServerException`

### setLocalStripedPassive

public HostPortList setLocalStripedPassive(int port, int queue) throws 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:
  `IOException`

### setLocalStripedPassive

public HostPortList setLocalStripedPassive() throws IOException
Behaves like setLocalStripedPassive(FTPServerFacade.ANY_PORT, FTPServerFacade.DEFAULT_QUEUE)

Throws:
  `IOException`

### setLocalStripedActive

public void setLocalStripedActive() throws ClientException, 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`
  `IOException`

### extendedGet

public void extendedGet(String remoteFileName, long size, DataSink sink, MarkerListener mListener) throws 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:
  `IOException`
  `ClientException`
  `ServerException`

### extendedGet

public void extendedGet(String remoteFileName, long offset, long size, DataSink sink, MarkerListener mListener) throws 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:
  `IOException`
  `ClientException`
  `ServerException`

### extendedPut

public void extendedPut(String remoteFileName, DataSource source, MarkerListener mListener) throws 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:
  `IOException`
  `ServerException`
  `ClientException`

### extendedPut

public void extendedPut(String remoteFileName, long offset, DataSource source, MarkerListener mListener) throws 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:
  `IOException`
  `ServerException`
  `ClientException`

### extendedTransfer

public void extendedTransfer(String remoteSrcFile, GridFTPClient destination, String remoteDstFile, MarkerListener mListener) throws 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:
  `IOException`
  `ServerException`
  `ClientException`

### extendedTransfer

public void extendedTransfer(String remoteSrcFile, long remoteSrcFileOffset, long remoteSrcFileLength, GridFTPClient destination, String remoteDstFile, long remoteDstFileOffset, MarkerListener mListener) throws 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:
  `IOException`
  `ServerException`
  `ClientException`

### extendedMultipleTransfer

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

Throws:
  `IOException`
  `ServerException`
  `ClientException`

### extendedMultipleTransfer

public void extendedMultipleTransfer(String[] remoteSrcFile, GridFTPClient destination, String[] remoteDstFile, MarkerListener mListener, MultipleTransferCompleteListener doneListener) throws IOException, ServerException, ClientException

Throws:
  `IOException`
  `ServerException`
  `ClientException`

### checkGridFTPSupport

protected void checkGridFTPSupport() throws IOException, ServerException
assure that the server supports extended transfer features; throw exception if not

Throws:
  `IOException`
  `ServerException`

### setDataChannelAuthentication

public void setDataChannelAuthentication(DataChannelAuthentication type) throws IOException, ServerException
Sets data channel authentication mode (DCAU)

Parameters:
  `type` - for 2-party transfer must be DataChannelAuthentication.SELF or DataChannelAuthentication.NONE
Throws:
  `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 IOException, ServerException
Sets data channel protection level (PROT).

Parameters:
  `protection` - should be `CLEAR`, `SAFE`, or `PRIVATE`, or `CONFIDENTIAL`.
Throws:
  `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(String remoteFileName, File localFile) throws IOException, ClientException, ServerException

Overrides:
  `get` in class `FTPClient`
Throws:
  `IOException`
  `ClientException`
  `ServerException`

### put

public void put(File localFile, String remoteFileName, boolean append) throws IOException, ServerException, ClientException

Overrides:
  `put` in class `FTPClient`
Throws:
  `IOException`
  `ServerException`
  `ClientException`

### setChecksum

public void setChecksum(ChecksumAlgorithm algorithm, String value) throws 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.
  `IOException`

### checksum

public String checksum(ChecksumAlgorithm algorithm, long offset, long length, String file) throws 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.
  `IOException`

### mlsr

public void mlsr(String path, MlsxEntryWriter writer) throws ServerException, ClientException, 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`
  `IOException`

### changeGroup

public void changeGroup(String group, String file) throws 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.
  `IOException`

### changeModificationTime

public void changeModificationTime(int year, int month, int day, int hour, int min, int sec, String file) throws 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:
  `IOException`
  `ServerException` - if an error occurred.

### createSymbolicLink

public void createSymbolicLink(String link_target, String link_name) throws 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:
  `IOException`
  `ServerException` - if an error occurred.