FTP (Apache Ant API)

org.apache.tools.ant.taskdefs.optional.net
Class FTP


java.lang.Object

  |

  +--org.apache.tools.ant.ProjectComponent

        |

        +--org.apache.tools.ant.Task

              |

              +--org.apache.tools.ant.taskdefs.optional.net.FTP


public class FTP
extends Task

Basic FTP client. Performs the following actions:

Note: Some FTP servers - notably the Solaris server - seem to hold data ports open after a "retr" operation, allowing them to timeout instead of shutting them down cleanly. This happens in active or passive mode, and the ports will remain open even after ending the FTP session. FTP "send" operations seem to close ports immediately. This behavior may cause problems on some systems when downloading large sets of files.

Since:
Ant 1.3
Author:
Roger Vaughn rvaughn@seaconinc.com
, Glenn McAllister glennm@ca.ibm.com , Magesh Umasankar

Nested Class Summary
static class FTP.Action
          an action to perform, one of "send", "put", "recv", "get", "del", "delete", "list", "mkdir", "chmod"
protected  class FTP.FTPDirectoryScanner
           
 
Field Summary
protected static java.lang.String[] ACTION_STRS
           
protected static int CHMOD
           
protected static java.lang.String[] COMPLETED_ACTION_STRS
           
protected static int DEL_FILES
           
protected static int GET_FILES
           
protected static int LIST_FILES
           
protected static int MK_DIR
           
protected static int SEND_FILES
           
 
Fields inherited from class org.apache.tools.ant.Task
description, location, target, taskName, taskType, wrapper
 
Fields inherited from class org.apache.tools.ant.ProjectComponent
project
 
Constructor Summary
FTP()
           
 
Method Summary
 void addFileset(FileSet set)
          A set of files to upload or download
protected  void checkConfiguration()
          Checks to see that all required parameters are set.
protected  void createParents(com.oroinc.net.ftp.FTPClient ftp, java.lang.String filename)
          Creates all parent directories specified in a complete relative pathname.
protected  void delFile(com.oroinc.net.ftp.FTPClient ftp, java.lang.String filename)
          Delete a file from the remote host.
protected  void doSiteCommand(com.oroinc.net.ftp.FTPClient ftp, java.lang.String TheCMD)
          Sends a site command to the ftp server
 void execute()
          Runs the task.
protected  void getFile(com.oroinc.net.ftp.FTPClient ftp, java.lang.String dir, java.lang.String filename)
          Retrieve a single file to the remote host.
protected  boolean isUpToDate(com.oroinc.net.ftp.FTPClient ftp, java.io.File localFile, java.lang.String remoteFile)
          Checks to see if the remote file is current as compared with the local file.
protected  void listFile(com.oroinc.net.ftp.FTPClient ftp, java.io.BufferedWriter bw, java.lang.String filename)
          List information about a single file from the remote host.
protected  void makeRemoteDir(com.oroinc.net.ftp.FTPClient ftp, java.lang.String dir)
          Create the specified directory on the remote host.
protected  java.lang.String resolveFile(java.lang.String file)
          Correct a file path to correspond to the remote host requirements.
protected  void sendFile(com.oroinc.net.ftp.FTPClient ftp, java.lang.String dir, java.lang.String filename)
          Sends a single file to the remote host.
 void setAction(FTP.Action action)
          Sets the FTP action to be taken.
 void setAction(java.lang.String action)
          Deprecated. setAction(String) is deprecated and is replaced with setAction(FTP.Action) to make Ant's Introspection mechanism do the work and also to encapsulate operations on the type in its own class.
 void setBinary(boolean binary)
          If true, uses binary mode, otherwise text mode (default is binary).
 void setChmod(java.lang.String theMode)
          Sets the file permission mode (Unix only) for files sent to the server.
 void setDepends(boolean depends)
          Set to true to transmit only files that are new or changed from their remote counterparts.
 void setIgnoreNoncriticalErrors(boolean ignoreNoncriticalErrors)
          set the flag to skip errors on directory creation.
 void setListing(java.io.File listing)
          The output file for the "list" action.
 void setNewer(boolean newer)
          A synonym for depends.
 void setPassive(boolean passive)
          Specifies whether to use passive mode.
 void setPassword(java.lang.String password)
          Sets the login password for the given user id.
 void setPort(int port)
          Sets the FTP port used by the remote server.
 void setRemotedir(java.lang.String dir)
          Sets the remote directory where files will be placed.
 void setSeparator(java.lang.String separator)
          Sets the remote file separator character.
 void setServer(java.lang.String server)
          Sets the FTP server to send files to.
 void setSkipFailedTransfers(boolean skipFailedTransfers)
          If true, enables unsuccessful file put, delete and get operations to be skipped with a warning and the remainder of the files still transferred.
 void setUmask(java.lang.String theUmask)
          Sets the default mask for file creation on a unix server.
 void setUserid(java.lang.String userid)
          Sets the login user id to use on the specified server.
 void setVerbose(boolean verbose)
          Set to true to receive notification about each file as it is transferred.
protected  void transferFiles(com.oroinc.net.ftp.FTPClient ftp)
          Sends all files specified by the configured filesets to the remote server.
protected  int transferFiles(com.oroinc.net.ftp.FTPClient ftp, FileSet fs)
          For each file in the fileset, do the appropriate action: send, get, delete, or list.
 
Methods inherited from class org.apache.tools.ant.Task
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, handleErrorOutput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject, setProject
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SEND_FILES


protected static final int SEND_FILES
See Also:
Constant Field Values

GET_FILES


protected static final int GET_FILES
See Also:
Constant Field Values

DEL_FILES


protected static final int DEL_FILES
See Also:
Constant Field Values

LIST_FILES


protected static final int LIST_FILES
See Also:
Constant Field Values

MK_DIR


protected static final int MK_DIR
See Also:
Constant Field Values

CHMOD


protected static final int CHMOD
See Also:
Constant Field Values

ACTION_STRS


protected static final java.lang.String[] ACTION_STRS

COMPLETED_ACTION_STRS


protected static final java.lang.String[] COMPLETED_ACTION_STRS
Constructor Detail

FTP


public FTP()
Method Detail

setRemotedir


public void setRemotedir(java.lang.String dir)
Sets the remote directory where files will be placed. This may be a relative or absolute path, and must be in the path syntax expected by the remote server. No correction of path syntax will be performed.


setServer


public void setServer(java.lang.String server)
Sets the FTP server to send files to.


setPort


public void setPort(int port)
Sets the FTP port used by the remote server.


setUserid


public void setUserid(java.lang.String userid)
Sets the login user id to use on the specified server.


setPassword


public void setPassword(java.lang.String password)
Sets the login password for the given user id.


setBinary


public void setBinary(boolean binary)
If true, uses binary mode, otherwise text mode (default is binary).


setPassive


public void setPassive(boolean passive)
Specifies whether to use passive mode. Set to true if you are behind a firewall and cannot connect without it. Passive mode is disabled by default.


setVerbose


public void setVerbose(boolean verbose)
Set to true to receive notification about each file as it is transferred.


setNewer


public void setNewer(boolean newer)
A synonym for depends. Set to true to transmit only new or changed files.


setDepends


public void setDepends(boolean depends)
Set to true to transmit only files that are new or changed from their remote counterparts. The default is to transmit all files.


setSeparator


public void setSeparator(java.lang.String separator)
Sets the remote file separator character. This normally defaults to the Unix standard forward slash, but can be manually overridden using this call if the remote server requires some other separator. Only the first character of the string is used.


setChmod


public void setChmod(java.lang.String theMode)
Sets the file permission mode (Unix only) for files sent to the server.


setUmask


public void setUmask(java.lang.String theUmask)
Sets the default mask for file creation on a unix server.


addFileset


public void addFileset(FileSet set)
A set of files to upload or download


setAction


public void setAction(java.lang.String action)
               throws BuildException
Deprecated. setAction(String) is deprecated and is replaced with setAction(FTP.Action) to make Ant's Introspection mechanism do the work and also to encapsulate operations on the type in its own class.

Sets the FTP action to be taken. Currently accepts "put", "get", "del", "mkdir" and "list".

BuildException

setAction


public void setAction(FTP.Action action)
               throws BuildException
Sets the FTP action to be taken. Currently accepts "put", "get", "del", "mkdir", "chmod" and "list".

BuildException

setListing


public void setListing(java.io.File listing)
                throws BuildException
The output file for the "list" action. This attribute is ignored for any other actions.

BuildException

setSkipFailedTransfers


public void setSkipFailedTransfers(boolean skipFailedTransfers)
If true, enables unsuccessful file put, delete and get operations to be skipped with a warning and the remainder of the files still transferred.


setIgnoreNoncriticalErrors


public void setIgnoreNoncriticalErrors(boolean ignoreNoncriticalErrors)
set the flag to skip errors on directory creation. (and maybe later other server specific errors)


checkConfiguration


protected void checkConfiguration()
                           throws BuildException
Checks to see that all required parameters are set.

BuildException

transferFiles


protected int transferFiles(com.oroinc.net.ftp.FTPClient ftp,
                            FileSet fs)
                     throws java.io.IOException,
                            BuildException
For each file in the fileset, do the appropriate action: send, get, delete, or list.

java.io.IOException
BuildException

transferFiles


protected void transferFiles(com.oroinc.net.ftp.FTPClient ftp)
                      throws java.io.IOException,
                             BuildException
Sends all files specified by the configured filesets to the remote server.

java.io.IOException
BuildException

resolveFile


protected java.lang.String resolveFile(java.lang.String file)
Correct a file path to correspond to the remote host requirements. This implementation currently assumes that the remote end can handle Unix-style paths with forward-slash separators. This can be overridden with the separator task parameter. No attempt is made to determine what syntax is appropriate for the remote host.


createParents


protected void createParents(com.oroinc.net.ftp.FTPClient ftp,
                             java.lang.String filename)
                      throws java.io.IOException,
                             BuildException
Creates all parent directories specified in a complete relative pathname. Attempts to create existing directories will not cause errors.

java.io.IOException
BuildException

isUpToDate


protected boolean isUpToDate(com.oroinc.net.ftp.FTPClient ftp,
                             java.io.File localFile,
                             java.lang.String remoteFile)
                      throws java.io.IOException,
                             BuildException
Checks to see if the remote file is current as compared with the local file. Returns true if the remote file is up to date.

java.io.IOException
BuildException

doSiteCommand


protected void doSiteCommand(com.oroinc.net.ftp.FTPClient ftp,
                             java.lang.String TheCMD)
                      throws java.io.IOException,
                             BuildException
Sends a site command to the ftp server

java.io.IOException
BuildException

sendFile


protected void sendFile(com.oroinc.net.ftp.FTPClient ftp,
                        java.lang.String dir,
                        java.lang.String filename)
                 throws java.io.IOException,
                        BuildException
Sends a single file to the remote host. filename may contain a relative path specification. When this is the case, sendFile will attempt to create any necessary parent directories before sending the file. The file will then be sent using the entire relative path spec - no attempt is made to change directories. It is anticipated that this may eventually cause problems with some FTP servers, but it simplifies the coding.

java.io.IOException
BuildException

delFile


protected void delFile(com.oroinc.net.ftp.FTPClient ftp,
                       java.lang.String filename)
                throws java.io.IOException,
                       BuildException
Delete a file from the remote host.

java.io.IOException
BuildException

getFile


protected void getFile(com.oroinc.net.ftp.FTPClient ftp,
                       java.lang.String dir,
                       java.lang.String filename)
                throws java.io.IOException,
                       BuildException
Retrieve a single file to the remote host. filename may contain a relative path specification.

The file will then be retreived using the entire relative path spec - no attempt is made to change directories. It is anticipated that this may eventually cause problems with some FTP servers, but it simplifies the coding.

java.io.IOException
BuildException

listFile


protected void listFile(com.oroinc.net.ftp.FTPClient ftp,
                        java.io.BufferedWriter bw,
                        java.lang.String filename)
                 throws java.io.IOException,
                        BuildException
List information about a single file from the remote host. filename may contain a relative path specification.

The file listing will then be retrieved using the entire relative path spec - no attempt is made to change directories. It is anticipated that this may eventually cause problems with some FTP servers, but it simplifies the coding.

java.io.IOException
BuildException

makeRemoteDir


protected void makeRemoteDir(com.oroinc.net.ftp.FTPClient ftp,
                             java.lang.String dir)
                      throws java.io.IOException,
                             BuildException
Create the specified directory on the remote host.

Parameters:
ftp - The FTP client connection
dir - The directory to create (format must be correct for host type)
java.io.IOException
BuildException

execute


public void execute()
             throws BuildException
Runs the task.

Overrides:
execute in class Task
Throws:
BuildException - if something goes wrong with the build


Copyright 2000-2002 Apache Software Foundation. All Rights Reserved.