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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private class	GridFTPClient.MlsxParserDataSink

Field Summary

Fields

Modifier and Type	Field	Description
protected GridFTPServerFacade	gLocalServer
protected GridFTPSession	gSession
private static org.apache.commons.logging.Log	logger
protected String	usageString

Fields inherited from class 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)
private boolean	tryExecutingCommand(Command cmd)
private boolean	tryExecutingTwoCommands(Command cmd1, Command cmd2)

Methods inherited from class 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 Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

logger

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

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

tryExecutingTwoCommands

private boolean tryExecutingTwoCommands(Command cmd1,
 Command cmd2)
                                 throws IOException,
FTPReplyParseException,
ServerException

Throws:

IOException

FTPReplyParseException

ServerException

tryExecutingCommand

private boolean tryExecutingCommand(Command cmd)
                             throws IOException,
FTPReplyParseException,
ServerException

Throws:

IOException

FTPReplyParseException

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.