Method Detail
_parsePassiveModeReply
protected void _parsePassiveModeReply(String reply)
throws MalformedServerReplyException
Parameters:reply - the reply to parse
Throws:
Since:
3.1
_parseExtendedPassiveModeReply
protected void _parseExtendedPassiveModeReply(String reply)
throws MalformedServerReplyException
_storeFile
protected boolean _storeFile(String command,
String remote,
InputStream local)
throws IOException
Parameters:command - the command to sendremote - the remote file namelocal - the local file name
Returns:true if successful
Throws:
Since:
3.1
_storeFileStream
protected OutputStream _storeFileStream(String command,
String remote)
throws IOException
Parameters:command - the command to sendremote - the remote file name
Returns:the output stream to write to
Throws:
Since:
3.1
_openDataConnection_
@Deprecated
protected Socket _openDataConnection_(int command,
String arg)
throws IOException
Establishes a data connection with the FTP server, returning
a Socket for the connection if successful. If a restart
offset has been set with setRestartOffset(long),
a REST command is issued to the server with the offset as
an argument before establishing the data connection. Active
mode connections also cause a local PORT command to be issued.
Parameters:command - The int representation of the FTP command to send.arg - The arguments to the FTP command. If this parameter is
set to null, then the command is sent with no argument.
Returns:A Socket corresponding to the established data connection.
Null is returned if an FTP protocol error is reported at
any point during the establishment and initialization of
the connection.
Throws:
_openDataConnection_
protected Socket _openDataConnection_(FTPCmd command,
String arg)
throws IOException
Establishes a data connection with the FTP server, returning
a Socket for the connection if successful. If a restart
offset has been set with setRestartOffset(long),
a REST command is issued to the server with the offset as
an argument before establishing the data connection. Active
mode connections also cause a local PORT command to be issued.
Parameters:command - The int representation of the FTP command to send.arg - The arguments to the FTP command. If this parameter is
set to null, then the command is sent with no argument.
Returns:A Socket corresponding to the established data connection.
Null is returned if an FTP protocol error is reported at
any point during the establishment and initialization of
the connection.
Throws:
Since:
3.3
_openDataConnection_
protected Socket _openDataConnection_(String command,
String arg)
throws IOException
Establishes a data connection with the FTP server, returning
a Socket for the connection if successful. If a restart
offset has been set with setRestartOffset(long),
a REST command is issued to the server with the offset as
an argument before establishing the data connection. Active
mode connections also cause a local PORT command to be issued.
Parameters:command - The text representation of the FTP command to send.arg - The arguments to the FTP command. If this parameter is
set to null, then the command is sent with no argument.
Returns:A Socket corresponding to the established data connection.
Null is returned if an FTP protocol error is reported at
any point during the establishment and initialization of
the connection.
Throws:
Since:
3.1
_connectAction_
protected void _connectAction_()
throws IOException
Description copied from class:
Initiates control connections and gets initial reply.
Initializes FTP._controlInput_ and FTP._controlOutput_.
Overrides:
Throws:
_connectAction_
protected void _connectAction_(Reader socketIsReader)
throws IOException
Description copied from class:
Initiates control connections and gets initial reply.
Initializes FTP._controlInput_ and FTP._controlOutput_.
Overrides:
Parameters:socketIsReader - the reader to reuse (if non-null)
Throws:
Since:
3.4
setDataTimeout
public void setDataTimeout(int timeout)
Sets the timeout in milliseconds to use when reading from the
data connection. This timeout will be set immediately after
opening the data connection, provided that the value is ≥ 0.
Note: the timeout will also be applied when calling accept()
whilst establishing an active local data connection.
Parameters:timeout - The default timeout in milliseconds that is used when
opening a data connection socket. The value 0 means an infinite timeout.
setParserFactory
set the factory used for parser creation to the supplied factory object.
Parameters:parserFactory - factory object used to create FTPFileEntryParsersSee Also:
disconnect
public void disconnect()
throws IOException
Closes the connection to the FTP server and restores
connection parameters to the default values.
Overrides:
Throws:
setRemoteVerificationEnabled
Enable or disable verification that the remote host taking part
of a data connection is the same as the host to which the control
connection is attached. The default is for verification to be
enabled. You may set this value at any time, whether the
FTPClient is currently connected or not.
Parameters:enable - True to enable verification, false to disable verification.
isRemoteVerificationEnabled
Return whether or not verification of the remote host participating
in data connections is enabled. The default behavior is for
verification to be enabled.
Returns:True if verification is enabled, false if not.
login
public boolean login(String username,
String password)
throws IOException
Login to the FTP server using the provided username and password.
Parameters:username - The username to login under.password - The password to use.
Returns:True if successfully completed, false if not.
Throws:
login
public boolean login(String username,
String password,
String account)
throws IOException
Login to the FTP server using the provided username, password,
and account. If no account is required by the server, only
the username and password, the account information is not used.
Parameters:username - The username to login under.password - The password to use.account - The account to use.
Returns:True if successfully completed, false if not.
Throws:
logout
public boolean logout()
throws IOException
Logout of the FTP server by sending the QUIT command.
Returns:True if successfully completed, false if not.
Throws:
changeWorkingDirectory
public boolean changeWorkingDirectory(String pathname)
throws IOException
Change the current working directory of the FTP session.
Parameters:pathname - The new current working directory.
Returns:True if successfully completed, false if not.
Throws:
changeToParentDirectory
public boolean changeToParentDirectory()
throws IOException
Change to the parent directory of the current working directory.
Returns:True if successfully completed, false if not.
Throws:
structureMount
public boolean structureMount(String pathname)
throws IOException
Issue the FTP SMNT command.
Parameters:pathname - The pathname to mount.
Returns:True if successfully completed, false if not.
Throws:
reinitialize
public boolean reinitialize()
throws IOException
Reinitialize the FTP session. Not all FTP servers support this
command, which issues the FTP REIN command.
Returns:True if successfully completed, false if not.
Throws:
Since:
3.4 (made public)
enterLocalActiveMode
Set the current data connection mode to
ACTIVE_LOCAL_DATA_CONNECTION_MODE. No communication
with the FTP server is conducted, but this causes all future data
transfers to require the FTP server to connect to the client's
data port. Additionally, to accommodate differences between socket
implementations on different platforms, this method causes the
client to issue a PORT command before every data transfer.
enterLocalPassiveMode
Set the current data connection mode to
PASSIVE_LOCAL_DATA_CONNECTION_MODE. Use this
method only for data transfers between the client and server.
This method causes a PASV (or EPSV) command to be issued to the server
before the opening of every data connection, telling the server to
open a data port to which the client will connect to conduct
data transfers. The FTPClient will stay in
PASSIVE_LOCAL_DATA_CONNECTION_MODE until the
mode is changed by calling some other method such as
enterLocalActiveMode()
N.B. currently calling any connect method will reset the mode to
ACTIVE_LOCAL_DATA_CONNECTION_MODE.
enterRemoteActiveMode
public boolean enterRemoteActiveMode(InetAddress host,
int port)
throws IOException
Set the current data connection mode to
ACTIVE_REMOTE_DATA_CONNECTION. Use this method only
for server to server data transfers. This method issues a PORT
command to the server, indicating the other server and port to which
it should connect for data transfers. You must call this method
before EVERY server to server transfer attempt. The FTPClient will
NOT automatically continue to issue PORT commands. You also
must remember to call
enterLocalActiveMode() if you
wish to return to the normal data connection mode.
Parameters:host - The passive mode server accepting connections for data
transfers.port - The passive mode server's data port.
Returns:True if successfully completed, false if not.
Throws:
enterRemotePassiveMode
public boolean enterRemotePassiveMode()
throws IOException
Set the current data connection mode to
PASSIVE_REMOTE_DATA_CONNECTION_MODE. Use this
method only for server to server data transfers.
This method issues a PASV command to the server, telling it to
open a data port to which the active server will connect to conduct
data transfers. You must call this method
before EVERY server to server transfer attempt. The FTPClient will
NOT automatically continue to issue PASV commands. You also
must remember to call
enterLocalActiveMode() if you
wish to return to the normal data connection mode.
Returns:True if successfully completed, false if not.
Throws:
getPassiveHost
Returns the hostname or IP address (in the form of a string) returned
by the server when entering passive mode. If not in passive mode,
returns null. This method only returns a valid value AFTER a
data connection has been opened after a call to
enterLocalPassiveMode().
This is because FTPClient sends a PASV command to the server only
just before opening a data connection, and not when you call
enterLocalPassiveMode().
Returns:The passive host name if in passive mode, otherwise null.
getPassivePort
If in passive mode, returns the data port of the passive host.
This method only returns a valid value AFTER a
data connection has been opened after a call to
enterLocalPassiveMode().
This is because FTPClient sends a PASV command to the server only
just before opening a data connection, and not when you call
enterLocalPassiveMode().
Returns:The data port of the passive server. If not in passive
mode, undefined.
getDataConnectionMode
Returns the current data connection mode (one of the
_DATA_CONNECTION_MODE constants.
Returns:The current data connection mode (one of the
_DATA_CONNECTION_MODE constants.
setActivePortRange
public void setActivePortRange(int minPort,
int maxPort)
Set the client side port range in active mode.
Parameters:minPort - The lowest available port (inclusive).maxPort - The highest available port (inclusive).Since:
2.2
setActiveExternalIPAddress
public void setActiveExternalIPAddress(String ipAddress)
throws UnknownHostException
Set the external IP address in active mode.
Useful when there are multiple network cards.
Parameters:ipAddress - The external IP address of this machine.
Throws:
Since:
2.2
setPassiveLocalIPAddress
public void setPassiveLocalIPAddress(String ipAddress)
throws UnknownHostException
Set the local IP address to use in passive mode.
Useful when there are multiple network cards.
Parameters:ipAddress - The local IP address of this machine.
Throws:
setPassiveLocalIPAddress
Set the local IP address to use in passive mode.
Useful when there are multiple network cards.
Parameters:inetAddress - The local IP address of this machine.
getPassiveLocalIPAddress
Set the local IP address in passive mode.
Useful when there are multiple network cards.
Returns:The local IP address in passive mode.
setReportActiveExternalIPAddress
public void setReportActiveExternalIPAddress(String ipAddress)
throws UnknownHostException
Set the external IP address to report in EPRT/PORT commands in active mode.
Useful when there are multiple network cards.
Parameters:ipAddress - The external IP address of this machine.
Throws:
Since:
3.1
See Also:
setFileType
public boolean setFileType(int fileType)
throws IOException
Sets the file type to be transferred. This should be one of
FTP.ASCII_FILE_TYPE, FTP.BINARY_FILE_TYPE,
etc. The file type only needs to be set when you want to change the
type. After changing it, the new type stays in effect until you change
it again. The default file type is FTP.ASCII_FILE_TYPE
if this method is never called.
The server default is supposed to be ASCII (see RFC 959), however many
ftp servers default to BINARY. To ensure correct operation with all servers,
always specify the appropriate file type after connecting to the server.
N.B. currently calling any connect method will reset the type to
FTP.ASCII_FILE_TYPE.
Parameters:fileType - The _FILE_TYPE constant indcating the
type of file.
Returns:True if successfully completed, false if not.
Throws:
setFileType
public boolean setFileType(int fileType,
int formatOrByteSize)
throws IOException
Sets the file type to be transferred and the format. The type should be
one of FTP.ASCII_FILE_TYPE,
FTP.BINARY_FILE_TYPE, etc. The file type only needs to
be set when you want to change the type. After changing it, the new
type stays in effect until you change it again. The default file type
is FTP.ASCII_FILE_TYPE if this method is never called.
The server default is supposed to be ASCII (see RFC 959), however many
ftp servers default to BINARY. To ensure correct operation with all servers,
always specify the appropriate file type after connecting to the server.
The format should be one of the FTP class TEXT_FORMAT
constants, or if the type is FTP.LOCAL_FILE_TYPE, the
format should be the byte size for that type. The default format
is FTP.NON_PRINT_TEXT_FORMAT if this method is never
called.
N.B. currently calling any connect method will reset the type to
FTP.ASCII_FILE_TYPE and the formatOrByteSize to FTP.NON_PRINT_TEXT_FORMAT.
Parameters:fileType - The _FILE_TYPE constant indcating the
type of file.formatOrByteSize - The format of the file (one of the
_FORMAT constants. In the case of
LOCAL_FILE_TYPE, the byte size.
Returns:True if successfully completed, false if not.
Throws:
setFileStructure
public boolean setFileStructure(int structure)
throws IOException
Sets the file structure. The default structure is
FTP.FILE_STRUCTURE if this method is never called
or if a connect method is called.
Parameters:structure - The structure of the file (one of the FTP class
_STRUCTURE constants).
Returns:True if successfully completed, false if not.
Throws:
setFileTransferMode
public boolean setFileTransferMode(int mode)
throws IOException
Sets the transfer mode. The default transfer mode
FTP.STREAM_TRANSFER_MODE if this method is never called
or if a connect method is called.
Parameters:mode - The new transfer mode to use (one of the FTP class
_TRANSFER_MODE constants).
Returns:True if successfully completed, false if not.
Throws:
remoteRetrieve
public boolean remoteRetrieve(String filename)
throws IOException
Initiate a server to server file transfer. This method tells the
server to which the client is connected to retrieve a given file from
the other server.
Parameters:filename - The name of the file to retrieve.
Returns:True if successfully completed, false if not.
Throws:
remoteStore
public boolean remoteStore(String filename)
throws IOException
Initiate a server to server file transfer. This method tells the
server to which the client is connected to store a file on
the other server using the given filename. The other server must
have had a remoteRetrieve issued to it by another
FTPClient.
Parameters:filename - The name to call the file that is to be stored.
Returns:True if successfully completed, false if not.
Throws:
remoteStoreUnique
public boolean remoteStoreUnique(String filename)
throws IOException
Initiate a server to server file transfer. This method tells the
server to which the client is connected to store a file on
the other server using a unique filename based on the given filename.
The other server must have had a remoteRetrieve issued
to it by another FTPClient.
Parameters:filename - The name on which to base the filename of the file
that is to be stored.
Returns:True if successfully completed, false if not.
Throws:
remoteStoreUnique
public boolean remoteStoreUnique()
throws IOException
Initiate a server to server file transfer. This method tells the
server to which the client is connected to store a file on
the other server using a unique filename.
The other server must have had a remoteRetrieve issued
to it by another FTPClient. Many FTP servers require that a base
filename be given from which the unique filename can be derived. For
those servers use the other version of remoteStoreUnique
Returns:True if successfully completed, false if not.
Throws:
remoteAppend
public boolean remoteAppend(String filename)
throws IOException
Initiate a server to server file transfer. This method tells the
server to which the client is connected to append to a given file on
the other server. The other server must have had a
remoteRetrieve issued to it by another FTPClient.
Parameters:filename - The name of the file to be appended to, or if the
file does not exist, the name to call the file being stored.
Returns:True if successfully completed, false if not.
Throws:
completePendingCommand
public boolean completePendingCommand()
throws IOException
There are a few FTPClient methods that do not complete the
entire sequence of FTP commands to complete a transaction. These
commands require some action by the programmer after the reception
of a positive intermediate command. After the programmer's code
completes its actions, it must call this method to receive
the completion reply from the server and verify the success of the
entire transaction.
For example,InputStream input;
OutputStream output;
input = new FileInputStream("foobaz.txt");
output = ftp.storeFileStream("foobar.txt")
if(!FTPReply.isPositiveIntermediate(ftp.getReplyCode())) {
input.close();
output.close();
ftp.logout();
ftp.disconnect();
System.err.println("File transfer failed.");
System.exit(1);
}
Util.copyStream(input, output);
input.close();
output.close();
// Must call completePendingCommand() to finish command.
if(!ftp.completePendingCommand()) {
ftp.logout();
ftp.disconnect();
System.err.println("File transfer failed.");
System.exit(1);
}
Returns:True if successfully completed, false if not.
Throws:
retrieveFile
public boolean retrieveFile(String remote,
OutputStream local)
throws IOException
Retrieves a named file from the server and writes it to the given
OutputStream. This method does NOT close the given OutputStream.
If the current file type is ASCII, line separators in the file are
converted to the local representation.
Note: if you have used setRestartOffset(long),
the file data will start from the selected offset.
Parameters:remote - The name of the remote file.local - The local OutputStream to which to write the file.
Returns:True if successfully completed, false if not.
Throws:
_retrieveFile
protected boolean _retrieveFile(String command,
String remote,
OutputStream local)
throws IOException
Parameters:command - the command to getremote - the remote file namelocal - the local file name
Returns:true if successful
Throws:
Since:
3.1
retrieveFileStream
public InputStream retrieveFileStream(String remote)
throws IOException
Returns an InputStream from which a named file from the server
can be read. If the current file type is ASCII, the returned
InputStream will convert line separators in the file to
the local representation. You must close the InputStream when you
finish reading from it. The InputStream itself will take care of
closing the parent data connection socket upon being closed.
To finalize the file transfer you must call
completePendingCommand and
check its return value to verify success.
If this is not done, subsequent commands may behave unexpectedly.
Note: if you have used setRestartOffset(long),
the file data will start from the selected offset.
Parameters:remote - The name of the remote file.
Returns:An InputStream from which the remote file can be read. If
the data connection cannot be opened (e.g., the file does not
exist), null is returned (in which case you may check the reply
code to determine the exact reason for failure).
Throws:
_retrieveFileStream
protected InputStream _retrieveFileStream(String command,
String remote)
throws IOException
Parameters:command - the command to sendremote - the remote file name
Returns:the stream from which to read the file
Throws:
Since:
3.1
storeFile
public boolean storeFile(String remote,
InputStream local)
throws IOException
Stores a file on the server using the given name and taking input
from the given InputStream. This method does NOT close the given
InputStream. If the current file type is ASCII, line separators in
the file are transparently converted to the NETASCII format (i.e.,
you should not attempt to create a special InputStream to do this).
Parameters:remote - The name to give the remote file.local - The local InputStream from which to read the file.
Returns:True if successfully completed, false if not.
Throws:
storeFileStream
public OutputStream storeFileStream(String remote)
throws IOException
Returns an OutputStream through which data can be written to store
a file on the server using the given name. If the current file type
is ASCII, the returned OutputStream will convert line separators in
the file to the NETASCII format (i.e., you should not attempt to
create a special OutputStream to do this). You must close the
OutputStream when you finish writing to it. The OutputStream itself
will take care of closing the parent data connection socket upon being
closed.
To finalize the file transfer you must call
completePendingCommand and
check its return value to verify success.
If this is not done, subsequent commands may behave unexpectedly.
Parameters:remote - The name to give the remote file.
Returns:An OutputStream through which the remote file can be written. If
the data connection cannot be opened (e.g., the file does not
exist), null is returned (in which case you may check the reply
code to determine the exact reason for failure).
Throws:
appendFile
public boolean appendFile(String remote,
InputStream local)
throws IOException
Appends to a file on the server with the given name, taking input
from the given InputStream. This method does NOT close the given
InputStream. If the current file type is ASCII, line separators in
the file are transparently converted to the NETASCII format (i.e.,
you should not attempt to create a special InputStream to do this).
Parameters:remote - The name of the remote file.local - The local InputStream from which to read the data to
be appended to the remote file.
Returns:True if successfully completed, false if not.
Throws:
appendFileStream
public OutputStream appendFileStream(String remote)
throws IOException
Returns an OutputStream through which data can be written to append
to a file on the server with the given name. If the current file type
is ASCII, the returned OutputStream will convert line separators in
the file to the NETASCII format (i.e., you should not attempt to
create a special OutputStream to do this). You must close the
OutputStream when you finish writing to it. The OutputStream itself
will take care of closing the parent data connection socket upon being
closed.
To finalize the file transfer you must call
completePendingCommand and
check its return value to verify success.
If this is not done, subsequent commands may behave unexpectedly.
Parameters:remote - The name of the remote file.
Returns:An OutputStream through which the remote file can be appended.
If the data connection cannot be opened (e.g., the file does not
exist), null is returned (in which case you may check the reply
code to determine the exact reason for failure).
Throws:
storeUniqueFile
public boolean storeUniqueFile(String remote,
InputStream local)
throws IOException
Stores a file on the server using a unique name derived from the
given name and taking input
from the given InputStream. This method does NOT close the given
InputStream. If the current file type is ASCII, line separators in
the file are transparently converted to the NETASCII format (i.e.,
you should not attempt to create a special InputStream to do this).
Parameters:remote - The name on which to base the unique name given to
the remote file.local - The local InputStream from which to read the file.
Returns:True if successfully completed, false if not.
Throws:
storeUniqueFileStream
public OutputStream storeUniqueFileStream(String remote)
throws IOException
Returns an OutputStream through which data can be written to store
a file on the server using a unique name derived from the given name.
If the current file type
is ASCII, the returned OutputStream will convert line separators in
the file to the NETASCII format (i.e., you should not attempt to
create a special OutputStream to do this). You must close the
OutputStream when you finish writing to it. The OutputStream itself
will take care of closing the parent data connection socket upon being
closed.
To finalize the file transfer you must call
completePendingCommand and
check its return value to verify success.
If this is not done, subsequent commands may behave unexpectedly.
Parameters:remote - The name on which to base the unique name given to
the remote file.
Returns:An OutputStream through which the remote file can be written. If
the data connection cannot be opened (e.g., the file does not
exist), null is returned (in which case you may check the reply
code to determine the exact reason for failure).
Throws:
storeUniqueFile
public boolean storeUniqueFile(InputStream local)
throws IOException
Stores a file on the server using a unique name assigned by the
server and taking input from the given InputStream. This method does
NOT close the given
InputStream. If the current file type is ASCII, line separators in
the file are transparently converted to the NETASCII format (i.e.,
you should not attempt to create a special InputStream to do this).
Parameters:local - The local InputStream from which to read the file.
Returns:True if successfully completed, false if not.
Throws:
storeUniqueFileStream
public OutputStream storeUniqueFileStream()
throws IOException
Returns an OutputStream through which data can be written to store
a file on the server using a unique name assigned by the server.
If the current file type
is ASCII, the returned OutputStream will convert line separators in
the file to the NETASCII format (i.e., you should not attempt to
create a special OutputStream to do this). You must close the
OutputStream when you finish writing to it. The OutputStream itself
will take care of closing the parent data connection socket upon being
closed.
To finalize the file transfer you must call
completePendingCommand and
check its return value to verify success.
If this is not done, subsequent commands may behave unexpectedly.
Returns:An OutputStream through which the remote file can be written. If
the data connection cannot be opened (e.g., the file does not
exist), null is returned (in which case you may check the reply
code to determine the exact reason for failure).
Throws:
allocate
public boolean allocate(int bytes)
throws IOException
Reserve a number of bytes on the server for the next file transfer.
Parameters:bytes - The number of bytes which the server should allocate.
Returns:True if successfully completed, false if not.
Throws:
features
public boolean features()
throws IOException
Query the server for supported features. The server may reply with a list of server-supported exensions.
For example, a typical client-server interaction might be (from RFC 2389):
C> feat
S> 211-Extensions supported:
S> MLST size*;create;modify*;perm;media-type
S> SIZE
S> COMPRESSION
S> MDTM
S> 211 END
Returns:True if successfully completed, false if not.
Throws:
Since:
2.2
See Also:
featureValues
public String[] featureValues(String feature)
throws IOException
Query the server for a supported feature, and returns its values (if any).
Caches the parsed response to avoid resending the command repeatedly.
Parameters:feature - the feature to check
Returns:if the feature is present, returns the feature values (empty array if none)
Returns null if the feature is not found or the command failed.
Check FTP.getReplyCode() or FTP.getReplyString() if so.
Throws:
Since:
3.0
featureValue
public String featureValue(String feature)
throws IOException
Query the server for a supported feature, and returns the its value (if any).
Caches the parsed response to avoid resending the command repeatedly.
Parameters:feature - the feature to check
Returns:if the feature is present, returns the feature value or the empty string
if the feature exists but has no value.
Returns null if the feature is not found or the command failed.
Check FTP.getReplyCode() or FTP.getReplyString() if so.
Throws:
Since:
3.0
hasFeature
public boolean hasFeature(String feature)
throws IOException
Query the server for a supported feature.
Caches the parsed response to avoid resending the command repeatedly.
Parameters:feature - the name of the feature; it is converted to upper case.
Returns:true if the feature is present, false if the feature is not present
or the FTP.feat() command failed. Check FTP.getReplyCode() or FTP.getReplyString()
if it is necessary to distinguish these cases.
Throws:
Since:
3.0
hasFeature
public boolean hasFeature(String feature,
String value)
throws IOException
Query the server for a supported feature with particular value,
for example "AUTH SSL" or "AUTH TLS".
Caches the parsed response to avoid resending the command repeatedly.
Parameters:feature - the name of the feature; it is converted to upper case.value - the value to find.
Returns:true if the feature is present, false if the feature is not present
or the FTP.feat() command failed. Check FTP.getReplyCode() or FTP.getReplyString()
if it is necessary to distinguish these cases.
Throws:
Since:
3.0
allocate
public boolean allocate(int bytes,
int recordSize)
throws IOException
Reserve space on the server for the next file transfer.
Parameters:bytes - The number of bytes which the server should allocate.recordSize - The size of a file record.
Returns:True if successfully completed, false if not.
Throws:
doCommand
public boolean doCommand(String command,
String params)
throws IOException
Issue a command and wait for the reply.
Should only be used with commands that return replies on the
command channel - do not use for LIST, NLST, MLSD etc.
Parameters:command - The command to invokeparams - The parameters string, may be null
Returns:True if successfully completed, false if not, in which case
call FTP.getReplyCode() or FTP.getReplyString()
to get the reason.
Throws:
Since:
3.0
doCommandAsStrings
public String[] doCommandAsStrings(String command,
String params)
throws IOException
Issue a command and wait for the reply, returning it as an array of strings.
Should only be used with commands that return replies on the
command channel - do not use for LIST, NLST, MLSD etc.
Parameters:command - The command to invokeparams - The parameters string, may be null
Returns:The array of replies, or null if the command failed, in which case
call FTP.getReplyCode() or FTP.getReplyString()
to get the reason.
Throws:
Since:
3.0
mlistFile
public FTPFile mlistFile(String pathname)
throws IOException
Get file details using the MLST command
Parameters:pathname - the file or directory to list, may be null
Returns:the file details, may be null
Throws:
Since:
3.0
mlistDir
public FTPFile[] mlistDir()
throws IOException
Generate a directory listing for the current directory using the MLSD command.
Returns:the array of file entries
Throws:
Since:
3.0
mlistDir
public FTPFile[] mlistDir(String pathname)
throws IOException
Generate a directory listing using the MLSD command.
Parameters:pathname - the directory name, may be null
Returns:the array of file entries
Throws:
Since:
3.0
mlistDir
public FTPFile[] mlistDir(String pathname,
FTPFileFilter filter)
throws IOException
Generate a directory listing using the MLSD command.
Parameters:pathname - the directory name, may be nullfilter - the filter to apply to the responses
Returns:the array of file entries
Throws:
Since:
3.0
restart
protected boolean restart(long offset)
throws IOException
Restart a STREAM_TRANSFER_MODE file transfer starting
from the given offset. This will only work on FTP servers supporting
the REST comand for the stream transfer mode. However, most FTP
servers support this. Any subsequent file transfer will start
reading or writing the remote file from the indicated offset.
Parameters:offset - The offset into the remote file at which to start the
next file transfer.
Returns:True if successfully completed, false if not.
Throws:
Since:
3.1 (changed from private to protected)
setRestartOffset
public void setRestartOffset(long offset)
Sets the restart offset for file transfers.
The restart command is not sent to the server immediately.
It is sent when a data connection is created as part of a
subsequent command.
The restart marker is reset to zero after use.
Note: This method should only be invoked immediately prior to
the transfer to which it applies.
Parameters:offset - The offset into the remote file at which to start the
next file transfer. This must be a value greater than or
equal to zero.
getRestartOffset
Fetches the restart offset.
Returns:offset The offset into the remote file at which to start the
next file transfer.
rename
public boolean rename(String from,
String to)
throws IOException
Renames a remote file.
Parameters:from - The name of the remote file to rename.to - The new name of the remote file.
Returns:True if successfully completed, false if not.
Throws:
abort
public boolean abort()
throws IOException
Abort a transfer in progress.
Returns:True if successfully completed, false if not.
Throws:
deleteFile
public boolean deleteFile(String pathname)
throws IOException
Deletes a file on the FTP server.
Parameters:pathname - The pathname of the file to be deleted.
Returns:True if successfully completed, false if not.
Throws:
removeDirectory
public boolean removeDirectory(String pathname)
throws IOException
Removes a directory on the FTP server (if empty).
Parameters:pathname - The pathname of the directory to remove.
Returns:True if successfully completed, false if not.
Throws:
makeDirectory
public boolean makeDirectory(String pathname)
throws IOException
Creates a new subdirectory on the FTP server in the current directory
(if a relative pathname is given) or where specified (if an absolute
pathname is given).
Parameters:pathname - The pathname of the directory to create.
Returns:True if successfully completed, false if not.
Throws:
printWorkingDirectory
public String printWorkingDirectory()
throws IOException
Returns the pathname of the current working directory.
Returns:The pathname of the current working directory. If it cannot
be obtained, returns null.
Throws:
sendSiteCommand
public boolean sendSiteCommand(String arguments)
throws IOException
Send a site specific command.
Parameters:arguments - The site specific command and arguments.
Returns:True if successfully completed, false if not.
Throws:
getSystemType
public String getSystemType()
throws IOException
Fetches the system type from the server and returns the string.
This value is cached for the duration of the connection after the
first call to this method. In other words, only the first time
that you invoke this method will it issue a SYST command to the
FTP server. FTPClient will remember the value and return the
cached value until a call to disconnect.
If the SYST command fails, and the system property
FTP_SYSTEM_TYPE_DEFAULT is defined, then this is used instead.
Returns:The system type obtained from the server. Never null.
Throws:
Since:
2.2
listHelp
public String listHelp()
throws IOException
Fetches the system help information from the server and returns the
full string.
Returns:The system help string obtained from the server. null if the
information could not be obtained.
Throws:
listHelp
public String listHelp(String command)
throws IOException
Fetches the help information for a given command from the server and
returns the full string.
Parameters:command - The command on which to ask for help.
Returns:The command help string obtained from the server. null if the
information could not be obtained.
Throws:
sendNoOp
public boolean sendNoOp()
throws IOException
Sends a NOOP command to the FTP server. This is useful for preventing
server timeouts.
Returns:True if successfully completed, false if not.
Throws:
listNames
public String[] listNames(String pathname)
throws IOException
Obtain a list of filenames in a directory (or just the name of a given
file, which is not particularly useful). This information is obtained
through the NLST command. If the given pathname is a directory and
contains no files, a zero length array is returned only
if the FTP server returned a positive completion code, otherwise
null is returned (the FTP server returned a 550 error No files found.).
If the directory is not empty, an array of filenames in the directory is
returned. If the pathname corresponds
to a file, only that file will be listed. The server may or may not
expand glob expressions.
Parameters:pathname - The file or directory to list.
Warning: the server may treat a leading '-' as an
option introducer. If so, try using an absolute path,
or prefix the path with ./ (unix style servers).
Some servers may support "--" as meaning end of options,
in which case "-- -xyz" should work.
Returns:The list of filenames contained in the given path. null if
the list could not be obtained. If there are no filenames in
the directory, a zero-length array is returned.
Throws:
listNames
public String[] listNames()
throws IOException
Obtain a list of filenames in the current working directory
This information is obtained through the NLST command. If the current
directory contains no files, a zero length array is returned only
if the FTP server returned a positive completion code, otherwise,
null is returned (the FTP server returned a 550 error No files found.).
If the directory is not empty, an array of filenames in the directory is
returned.
Returns:The list of filenames contained in the current working
directory. null if the list could not be obtained.
If there are no filenames in the directory, a zero-length array
is returned.
Throws:
listFiles
public FTPFile[] listFiles(String pathname)
throws IOException
Using the default system autodetect mechanism, obtain a
list of file information for the current working directory
or for just a single file.
This information is obtained through the LIST command. The contents of
the returned array is determined by theFTPFileEntryParser
used.
N.B. the LIST command does not generally return very precise timestamps.
For recent files, the response usually contains hours and minutes (not seconds).
For older files, the output may only contain a date.
If the server supports it, the MLSD command returns timestamps with a precision
of seconds, and may include milliseconds. See mlistDir()
Parameters:pathname - The file or directory to list. Since the server may
or may not expand glob expressions, using them here
is not recommended and may well cause this method to
fail.
Also, some servers treat a leading '-' as being an option.
To avoid this interpretation, use an absolute pathname
or prefix the pathname with ./ (unix style servers).
Some servers may support "--" as meaning end of options,
in which case "-- -xyz" should work.
Returns:The list of file information contained in the given path in
the format determined by the autodetection mechanism
Throws:
See Also:
listFiles
public FTPFile[] listFiles()
throws IOException
Using the default system autodetect mechanism, obtain a
list of file information for the current working directory.
This information is obtained through the LIST command. The contents of
the returned array is determined by theFTPFileEntryParser
used.
N.B. the LIST command does not generally return very precise timestamps.
For recent files, the response usually contains hours and minutes (not seconds).
For older files, the output may only contain a date.
If the server supports it, the MLSD command returns timestamps with a precision
of seconds, and may include milliseconds. See mlistDir()
Returns:The list of file information contained in the current directory
in the format determined by the autodetection mechanism.
NOTE: This array may contain null members if any of the
individual file listings failed to parse. The caller should
check each entry for null before referencing it.
Throws:
See Also:
listFiles
public FTPFile[] listFiles(String pathname,
FTPFileFilter filter)
throws IOException
Version of listFiles(String) which allows a filter to be provided.
For example: listFiles("site", FTPFileFilters.DIRECTORY);
Parameters:pathname - the initial path, may be nullfilter - the filter, non-null
Returns:the list of FTPFile entries.
Throws:
Since:
2.2
listDirectories
public FTPFile[] listDirectories()
throws IOException
Using the default system autodetect mechanism, obtain a
list of directories contained in the current working directory.
This information is obtained through the LIST command. The contents of
the returned array is determined by theFTPFileEntryParser
used.
N.B. the LIST command does not generally return very precise timestamps.
For recent files, the response usually contains hours and minutes (not seconds).
For older files, the output may only contain a date.
If the server supports it, the MLSD command returns timestamps with a precision
of seconds, and may include milliseconds. See mlistDir()
Returns:The list of directories contained in the current directory
in the format determined by the autodetection mechanism.
Throws:
Since:
3.0
See Also:
listDirectories
public FTPFile[] listDirectories(String parent)
throws IOException
Using the default system autodetect mechanism, obtain a
list of directories contained in the specified directory.
This information is obtained through the LIST command. The contents of
the returned array is determined by theFTPFileEntryParser
used.
N.B. the LIST command does not generally return very precise timestamps.
For recent files, the response usually contains hours and minutes (not seconds).
For older files, the output may only contain a date.
If the server supports it, the MLSD command returns timestamps with a precision
of seconds, and may include milliseconds. See mlistDir()
Parameters:parent - the starting directory
Returns:The list of directories contained in the specified directory
in the format determined by the autodetection mechanism.
Throws:
Since:
3.0
See Also:
initiateListParsing
public FTPListParseEngine initiateListParsing()
throws IOException
Using the default autodetect mechanism, initialize an FTPListParseEngine
object containing a raw file information for the current working
directory on the server
This information is obtained through the LIST command. This object
is then capable of being iterated to return a sequence of FTPFile
objects with information filled in by the
FTPFileEntryParser used.
This method differs from using the listFiles() methods in that
expensive FTPFile objects are not created until needed which may be
an advantage on large lists.
Returns:A FTPListParseEngine object that holds the raw information and
is capable of providing parsed FTPFile objects, one for each file
containing information contained in the given path in the format
determined by the parser parameter. Null will be
returned if a data connection cannot be opened. If the current working
directory contains no files, an empty array will be the return.
Throws:
See Also:
initiateListParsing
public FTPListParseEngine initiateListParsing(String pathname)
throws IOException
Using the default autodetect mechanism, initialize an FTPListParseEngine
object containing a raw file information for the supplied directory.
This information is obtained through the LIST command. This object
is then capable of being iterated to return a sequence of FTPFile
objects with information filled in by the
FTPFileEntryParser used.
The server may or may not expand glob expressions. You should avoid
using glob expressions because the return format for glob listings
differs from server to server and will likely cause this method to fail.
This method differs from using the listFiles() methods in that
expensive FTPFile objects are not created until needed which may be
an advantage on large lists.FTPClient f=FTPClient();
f.connect(server);
f.login(username, password);
FTPListParseEngine engine = f.initiateListParsing(directory);
while (engine.hasNext()) {
FTPFile[] files = engine.getNext(25); // "page size" you want
//do whatever you want with these files, display them, etc.
//expensive FTPFile objects not created until needed.
}
Parameters:pathname - the starting directory
Returns:A FTPListParseEngine object that holds the raw information and
is capable of providing parsed FTPFile objects, one for each file
containing information contained in the given path in the format
determined by the parser parameter. Null will be
returned if a data connection cannot be opened. If the current working
directory contains no files, an empty array will be the return.
Throws:
See Also:
initiateListParsing
public FTPListParseEngine initiateListParsing(String parserKey,
String pathname)
throws IOException
Using the supplied parser key, initialize an FTPListParseEngine
object containing a raw file information for the supplied directory.
This information is obtained through the LIST command. This object
is then capable of being iterated to return a sequence of FTPFile
objects with information filled in by the
FTPFileEntryParser used.
The server may or may not expand glob expressions. You should avoid
using glob expressions because the return format for glob listings
differs from server to server and will likely cause this method to fail.
This method differs from using the listFiles() methods in that
expensive FTPFile objects are not created until needed which may be
an advantage on large lists.
Parameters:parserKey - A string representing a designated code or fully-qualified
class name of an FTPFileEntryParser that should be
used to parse each server file listing.
May be null, in which case the code checks first
the system property FTP_SYSTEM_TYPE, and if that is
not defined the SYST command is used to provide the value.
To allow for arbitrary system types, the return from the
SYST command is used to look up an alias for the type in the
SYSTEM_TYPE_PROPERTIES properties file if it is available.pathname - the starting directory
Returns:A FTPListParseEngine object that holds the raw information and
is capable of providing parsed FTPFile objects, one for each file
containing information contained in the given path in the format
determined by the parser parameter. Null will be
returned if a data connection cannot be opened. If the current working
directory contains no files, an empty array will be the return.
Throws:
See Also:
getListArguments
Parameters:pathname - the initial pathname
Returns:the adjusted string with "-a" added if necessarySince:
2.0
getStatus
public String getStatus()
throws IOException
Issue the FTP STAT command to the server.
Returns:The status information returned by the server.
Throws:
getStatus
public String getStatus(String pathname)
throws IOException
Issue the FTP STAT command to the server for a given pathname. This
should produce a listing of the file or directory.
Parameters:pathname - the filename
Returns:The status information returned by the server.
Throws:
getModificationTime
public String getModificationTime(String pathname)
throws IOException
Issue the FTP MDTM command (not supported by all servers) to retrieve the last
modification time of a file. The modification string should be in the
ISO 3077 form "YYYYMMDDhhmmss(.xxx)?". The timestamp represented should also be in
GMT, but not all FTP servers honour this.
Parameters:pathname - The file path to query.
Returns:A string representing the last file modification time in YYYYMMDDhhmmss format.
Throws:
Since:
2.0
mdtmFile
public FTPFile mdtmFile(String pathname)
throws IOException
Issue the FTP MDTM command (not supported by all servers) to retrieve the last
modification time of a file. The modification string should be in the
ISO 3077 form "YYYYMMDDhhmmss(.xxx)?". The timestamp represented should also be in
GMT, but not all FTP servers honour this.
Parameters:pathname - The file path to query.
Returns:A FTPFile representing the last file modification time, may be null.
The FTPFile timestamp will be null if a parse error occurs.
Throws:
Since:
3.4
setModificationTime
public boolean setModificationTime(String pathname,
String timeval)
throws IOException
Issue the FTP MFMT command (not supported by all servers) which sets the last
modified time of a file.
The timestamp should be in the form YYYYMMDDhhmmss. It should also
be in GMT, but not all servers honour this.
An FTP server would indicate its support of this feature by including "MFMT"
in its response to the FEAT command, which may be retrieved by FTPClient.features()
Parameters:pathname - The file path for which last modified time is to be changed.timeval - The timestamp to set to, in YYYYMMDDhhmmss format.
Returns:true if successfully set, false if not
Throws:
Since:
2.2
See Also:
setBufferSize
public void setBufferSize(int bufSize)
Set the internal buffer size for buffered data streams.
Parameters:bufSize - The size of the buffer. Use a non-positive value to use the default.
getBufferSize
Retrieve the current internal buffer size for buffered data streams.
Returns:The current buffer size.
setSendDataSocketBufferSize
Sets the value to be used for the data socket SO_SNDBUF option.
If the value is positive, the option will be set when the data socket has been created.
Parameters:bufSize - The size of the buffer, zero or negative means the value is ignored.Since:
3.3
getSendDataSocketBufferSize
Retrieve the value to be used for the data socket SO_SNDBUF option.
Returns:The current buffer size.Since:
3.3
setReceieveDataSocketBufferSize
Sets the value to be used for the data socket SO_RCVBUF option.
If the value is positive, the option will be set when the data socket has been created.
Parameters:bufSize - The size of the buffer, zero or negative means the value is ignored.Since:
3.3
getReceiveDataSocketBufferSize
Retrieve the value to be used for the data socket SO_RCVBUF option.
Returns:The current buffer size.Since:
3.3
configure
Implementation of the Configurable interface.
In the case of this class, configuring merely makes the config object available for the
factory methods that construct parsers.
Specified by:
Parameters:config - FTPClientConfig object used to
provide non-standard configurations to the parser.Since:
1.4
setListHiddenFiles
public void setListHiddenFiles(boolean listHiddenFiles)
You can set this to true if you would like to get hidden files when listFiles(java.lang.String) too.
A LIST -a will be issued to the ftp server.
It depends on your ftp server if you need to call this method, also dont expect to get rid
of hidden files if you call this method with "false".
Parameters:listHiddenFiles - true if hidden files should be listedSince:
2.0
getListHiddenFiles
Returns:the current stateSince:
2.0
See Also:
isUseEPSVwithIPv4
Whether should attempt to use EPSV with IPv4.
Default (if not set) is false
Returns:true if should attempt EPSVSince:
2.2
setUseEPSVwithIPv4
public void setUseEPSVwithIPv4(boolean selected)
Set whether to use EPSV with IPv4.
Might be worth enabling in some circumstances.
For example, when using IPv4 with NAT it
may work with some rare configurations.
E.g. if FTP server has a static PASV address (external network)
and the client is coming from another internal network.
In that case the data connection after PASV command would fail,
while EPSV would make the client succeed by taking just the port.
Parameters:selected - value to set.Since:
2.2
setCopyStreamListener
Set the listener to be used when performing store/retrieve operations.
The default value (if not set) is null.
Parameters:listener - to be used, may be null to disableSince:
3.0
getCopyStreamListener
Obtain the currently active listener.
Returns:the listener, may be nullSince:
3.0
setControlKeepAliveTimeout
public void setControlKeepAliveTimeout(long controlIdle)
Set the time to wait between sending control connection keepalive messages
when processing file upload or download.
Parameters:controlIdle - the wait (in secs) between keepalive messages. Zero (or less) disables.Since:
3.0
See Also:
getControlKeepAliveTimeout
Get the time to wait between sending control connection keepalive messages.
Returns:the number of seconds between keepalive messages.Since:
3.0
setControlKeepAliveReplyTimeout
Set how long to wait for control keep-alive message replies.
Parameters:timeout - number of milliseconds to wait (defaults to 1000)Since:
3.0
See Also:
getControlKeepAliveReplyTimeout
Get how long to wait for control keep-alive message replies.
Returns:wait time in msecSince:
3.0
setPassiveNatWorkaround
Enable or disable passive mode NAT workaround.
If enabled, a site-local PASV mode reply address will be replaced with the
remote host address to which the PASV mode request was sent
(unless that is also a site local address).
This gets around the problem that some NAT boxes may change the
reply.
The default is true, i.e. site-local replies are replaced.
Parameters:enabled - true to enable replacing internal IP's in passive
mode.
setPassiveNatWorkaroundStrategy
Set the workaround strategy to replace the PASV mode reply addresses.
This gets around the problem that some NAT boxes may change the reply.
The default implementation is NatServerResolverImpl, i.e. site-local
replies are replaced.
Parameters:resolver - strategy to replace internal IP's in passive mode
or null to disable the workaround (i.e. use PASV mode reply address.)Since:
3.6
setAutodetectUTF8
public void setAutodetectUTF8(boolean autodetect)
Enables or disables automatic server encoding detection (only UTF-8 supported).
Does not affect existing connections; must be invoked before a connection is established.
Parameters:autodetect - If true, automatic server encoding detection will be enabled.
getAutodetectUTF8
Tells if automatic server encoding detection is enabled or disabled.
Returns:true, if automatic server encoding detection is enabled.
getSystemName
Deprecated.
Returns:the name
Throws: