| 1 | <!--
|
|---|
| 2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
|---|
| 3 | contributor license agreements. See the NOTICE file distributed with
|
|---|
| 4 | this work for additional information regarding copyright ownership.
|
|---|
| 5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
|---|
| 6 | (the "License"); you may not use this file except in compliance with
|
|---|
| 7 | the License. You may obtain a copy of the License at
|
|---|
| 8 |
|
|---|
| 9 | http://www.apache.org/licenses/LICENSE-2.0
|
|---|
| 10 |
|
|---|
| 11 | Unless required by applicable law or agreed to in writing, software
|
|---|
| 12 | distributed under the License is distributed on an "AS IS" BASIS,
|
|---|
| 13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|---|
| 14 | See the License for the specific language governing permissions and
|
|---|
| 15 | limitations under the License.
|
|---|
| 16 | -->
|
|---|
| 17 | <html>
|
|---|
| 18 |
|
|---|
| 19 | <head>
|
|---|
| 20 | <meta http-equiv="Content-Language" content="en-us">
|
|---|
| 21 | <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|---|
| 22 | <title>FTP Task</title>
|
|---|
| 23 | </head>
|
|---|
| 24 |
|
|---|
| 25 | <body>
|
|---|
| 26 |
|
|---|
| 27 | <h2><a name="ftp">FTP</a></h2>
|
|---|
| 28 | <h3>Description</h3>
|
|---|
| 29 | <p>The ftp task implements a basic FTP client that can send, receive,
|
|---|
| 30 | list, delete files, and create directories. See below for descriptions and examples of how
|
|---|
| 31 | to perform each task.</p>
|
|---|
| 32 | <p><b>Note:</b> This task depends on external libraries not included in the Ant distribution.
|
|---|
| 33 | See <a href="../install.html#commons-net">Library Dependencies</a> for more information.
|
|---|
| 34 | <i>Get the latest version of this library, for the best support in Ant</i>
|
|---|
| 35 |
|
|---|
| 36 | </p>
|
|---|
| 37 | <p>The ftp task attempts to determine what file system is in place on the FTP server.
|
|---|
| 38 | Supported server types are Unix, NT, OS2, VMS, and OS400. In addition, NT and OS400 servers
|
|---|
| 39 | which have been configured to display the directory in Unix style are also supported correctly.
|
|---|
| 40 | Otherwise, the system will default to Unix standards.
|
|---|
| 41 | <i>remotedir</i> must be specified in the exact syntax required by the ftp
|
|---|
| 42 | server. If the usual Unix conventions are not supported by the server,
|
|---|
| 43 | <i>separator</i> can be used to set the file separator that should be used
|
|---|
| 44 | instead.</p>
|
|---|
| 45 | <p>See the section on <a href="../dirtasks.html#directorybasedtasks">directory based
|
|---|
| 46 | tasks</a>, on how the inclusion/exclusion of files works, and how to
|
|---|
| 47 | write patterns.</p>
|
|---|
| 48 | <p>
|
|---|
| 49 | This task does not currently use the proxy information set by the
|
|---|
| 50 | <a href="setproxy.html"><code><setproxy></code></a> task, and cannot go through
|
|---|
| 51 | a firewall via socks.
|
|---|
| 52 | <p>
|
|---|
| 53 | <b>Warning: </b> there have been problems reported concerning the ftp get with the <code>newer</code> attribute.
|
|---|
| 54 | Problems might be due to format of ls -l differing from what is expected by commons-net,
|
|---|
| 55 | for instance due to specificities of language used by the ftp server in the directory listing.
|
|---|
| 56 | If you encounter such a problem, please send an email including a sample directory listing
|
|---|
| 57 | coming from your ftp server (ls -l on the ftp prompt).
|
|---|
| 58 | </p>
|
|---|
| 59 | <p>
|
|---|
| 60 | If you can connect but not upload or download, try setting the <code>passive</code>
|
|---|
| 61 | attribute to true to use the existing (open) channel, instead of having the server
|
|---|
| 62 | try to set up a new connection.</p>
|
|---|
| 63 |
|
|---|
| 64 | <h3>Parameters</h3>
|
|---|
| 65 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 66 | <tr>
|
|---|
| 67 | <td valign="top" width="15%"><b>Attribute</b></td>
|
|---|
| 68 | <td valign="top" width="65%"><b>Description</b></td>
|
|---|
| 69 | <td align="center" valign="top" width="20%"><b>Required</b></td>
|
|---|
| 70 | </tr>
|
|---|
| 71 | <tr>
|
|---|
| 72 | <td valign="top">server</td>
|
|---|
| 73 | <td valign="top">the address of the remote ftp server.</td>
|
|---|
| 74 | <td valign="top" align="center">Yes</td>
|
|---|
| 75 | </tr>
|
|---|
| 76 | <tr>
|
|---|
| 77 | <td valign="top">port</td>
|
|---|
| 78 | <td valign="top">the port number of the remote ftp server.
|
|---|
| 79 | Defaults to port 21.</td>
|
|---|
| 80 | <td valign="top" align="center">No</td>
|
|---|
| 81 | </tr>
|
|---|
| 82 | <tr>
|
|---|
| 83 | <td valign="top">userid</td>
|
|---|
| 84 | <td valign="top">the login id to use on the ftp server.</td>
|
|---|
| 85 | <td valign="top" align="center">Yes</td>
|
|---|
| 86 | </tr>
|
|---|
| 87 | <tr>
|
|---|
| 88 | <td valign="top">password</td>
|
|---|
| 89 | <td valign="top">the login password to use on the ftp server.</td>
|
|---|
| 90 | <td valign="top" align="center">Yes</td>
|
|---|
| 91 | </tr>
|
|---|
| 92 | <tr>
|
|---|
| 93 | <td valign="top">account</td>
|
|---|
| 94 | <td valign="top">the account to use on the ftp server.
|
|---|
| 95 | <em>since Ant 1.7</em>.
|
|---|
| 96 | </td>
|
|---|
| 97 | <td valign="top" align="center">No</td>
|
|---|
| 98 | </tr>
|
|---|
| 99 | <tr>
|
|---|
| 100 | <td valign="top">remotedir</td>
|
|---|
| 101 | <td valign="top">remote directory on the
|
|---|
| 102 | ftp server
|
|---|
| 103 | see table below for detailed usage
|
|---|
| 104 | </td>
|
|---|
| 105 | <td valign="top" align="center">No</td>
|
|---|
| 106 | </tr>
|
|---|
| 107 | <tr>
|
|---|
| 108 | <td valign="top">action</td>
|
|---|
| 109 | <td valign="top">the ftp action to perform, defaulting to "send".
|
|---|
| 110 | Currently supports "put", "get",
|
|---|
| 111 | "del", "list", "chmod",
|
|---|
| 112 | "mkdir", "rmdir", and "site".</td>
|
|---|
| 113 | <td valign="top" align="center">No</td>
|
|---|
| 114 | </tr>
|
|---|
| 115 | <tr>
|
|---|
| 116 | <td valign="top">binary</td>
|
|---|
| 117 | <td valign="top">selects binary-mode ("yes") or text-mode
|
|---|
| 118 | ("no") transfers.
|
|---|
| 119 | Defaults to "yes"</td>
|
|---|
| 120 | <td valign="top" align="center">No</td>
|
|---|
| 121 | </tr>
|
|---|
| 122 | <tr>
|
|---|
| 123 | <td valign="top">passive</td>
|
|---|
| 124 | <td valign="top">selects passive-mode ("yes") transfers, for
|
|---|
| 125 | better through-firewall connectivity, at the price
|
|---|
| 126 | of performance.
|
|---|
| 127 | Defaults to "no"</td>
|
|---|
| 128 | <td valign="top" align="center">No</td>
|
|---|
| 129 | </tr>
|
|---|
| 130 | <tr>
|
|---|
| 131 | <td valign="top">verbose</td>
|
|---|
| 132 | <td valign="top">displays information on each file transferred if set
|
|---|
| 133 | to "yes". Defaults to "no".</td>
|
|---|
| 134 | <td valign="top" align="center">No</td>
|
|---|
| 135 | </tr>
|
|---|
| 136 | <tr>
|
|---|
| 137 | <td valign="top">depends</td>
|
|---|
| 138 | <td valign="top">transfers only new or changed files if set to
|
|---|
| 139 | "yes". Defaults to "no".</td>
|
|---|
| 140 | <td valign="top" align="center">No</td>
|
|---|
| 141 | </tr>
|
|---|
| 142 | <tr>
|
|---|
| 143 | <td valign="top">newer</td>
|
|---|
| 144 | <td valign="top">a synonym for <i>depends</i>.
|
|---|
| 145 | see timediffauto and timediffmillis</td>
|
|---|
| 146 | <td valign="top" align="center">No</td>
|
|---|
| 147 | </tr>
|
|---|
| 148 | <tr>
|
|---|
| 149 | <td valign="top">timediffauto</td>
|
|---|
| 150 | <td valign="top">set to <code>"true"</code>
|
|---|
| 151 | to make ant calculate the time difference between client and server.<br>
|
|---|
| 152 | <em>requires write access in the remote directory</em><br>
|
|---|
| 153 | Since ant 1.6</td>
|
|---|
| 154 | <td valign="top" align="center">No</td>
|
|---|
| 155 | </tr>
|
|---|
| 156 | <a name="timestampGranularity"/>
|
|---|
| 157 | <tr>
|
|---|
| 158 | <td valign="top">timestampGranularity</td>
|
|---|
| 159 | <td valign="top">Specify either <code>MINUTE</code>, <code>NONE</code>,
|
|---|
| 160 | (or you may specify <code>""</code> which is equivalent to not specifying a value,
|
|---|
| 161 | useful for property-file driven scripts). Allows override of the typical situation
|
|---|
| 162 | in PUT and GET where local filesystem timestamps are <code>HH:mm:ss</code>
|
|---|
| 163 | and the typical FTP server's timestamps are <code>HH:mm</code>. This can throw
|
|---|
| 164 | off uptodate calculations. However, the default values should suffice for most
|
|---|
| 165 | applications.<br>
|
|---|
| 166 | Since ant 1.7
|
|---|
| 167 | </td>
|
|---|
| 168 | <td valign="top" align="center">No. Only applies in "puts" and "gets" where the
|
|---|
| 169 | default values are <code>MINUTE</code> for PUT and <code>NONE</code> for GET.
|
|---|
| 170 | (It is not as necessary in GET because we have the <b>preservelastmodified</b> option.)</td>
|
|---|
| 171 | </tr>
|
|---|
| 172 | <tr>
|
|---|
| 173 | <td valign="top">timediffmillis</td>
|
|---|
| 174 | <td valign="top"><b>Deprecated</b>. Number of milliseconds to add to the time on
|
|---|
| 175 | the remote machine to get the time on the local machine. The <b>timestampGranularity</b>
|
|---|
| 176 | attribute (for which the default values should suffice in most situations), and the
|
|---|
| 177 | <b>serverTimeZoneConfig</b> option, should make this unnecessary.
|
|---|
| 178 | <b>serverTimeZoneConfig</b> does the math for you and also knows about
|
|---|
| 179 | Daylight Savings Time.<br>
|
|---|
| 180 | Since ant 1.6
|
|---|
| 181 | </td>
|
|---|
| 182 | <td valign="top" align="center">No</td>
|
|---|
| 183 | </tr>
|
|---|
| 184 | <tr>
|
|---|
| 185 | <td valign="top">separator</td>
|
|---|
| 186 | <td valign="top">sets the file separator used on the ftp server.
|
|---|
| 187 | Defaults to "/".</td>
|
|---|
| 188 | <td valign="top" align="center">No</td>
|
|---|
| 189 | </tr>
|
|---|
| 190 | <tr>
|
|---|
| 191 | <td valign="top">umask</td>
|
|---|
| 192 | <td valign="top">sets the default file permissions for new files,
|
|---|
| 193 | unix only.</td>
|
|---|
| 194 | <td valign="top" align="center">No</td>
|
|---|
| 195 | </tr>
|
|---|
| 196 | <tr>
|
|---|
| 197 | <td valign="top">chmod</td>
|
|---|
| 198 | <td valign="top">sets or changes file permissions for new or existing files,
|
|---|
| 199 | unix only. If used with a put action, chmod will be issued for each file.</td>
|
|---|
| 200 | <td valign="top" align="center">No</td>
|
|---|
| 201 | </tr>
|
|---|
| 202 | <tr>
|
|---|
| 203 | <td valign="top">listing</td>
|
|---|
| 204 | <td valign="top">the file to write results of the "list" action.
|
|---|
| 205 | Required for the "list" action, ignored otherwise.</td>
|
|---|
| 206 | <td valign="top" align="center">No</td>
|
|---|
| 207 | </tr>
|
|---|
| 208 | <tr>
|
|---|
| 209 | <td valign="top">ignoreNoncriticalErrors</td>
|
|---|
| 210 | <td valign="top">flag which permits the task to ignore some non-fatal error
|
|---|
| 211 | codes sent by some servers during directory creation: wu-ftp in particular.
|
|---|
| 212 | Default: false</td>
|
|---|
| 213 | <td valign="top" align="center">No</td>
|
|---|
| 214 | </tr>
|
|---|
| 215 | <tr>
|
|---|
| 216 | <td valign="top">skipFailedTransfers</td>
|
|---|
| 217 | <td valign="top">flag which enables unsuccessful file put, delete
|
|---|
| 218 | and get operations to be skipped with a warning and the
|
|---|
| 219 | remainder of the files still transferred. Default: false</td>
|
|---|
| 220 | <td valign="top" align="center">No</td>
|
|---|
| 221 | </tr>
|
|---|
| 222 | <tr>
|
|---|
| 223 | <td valign="top">preservelastmodified</td>
|
|---|
| 224 | <td valign="top">Give the copied files the same last modified
|
|---|
| 225 | time as the original source files (applies to getting files only).
|
|---|
| 226 | (<em>Note</em>: Ignored on Java 1.1)</td>
|
|---|
| 227 | <td valign="top" align="center">No; defaults to false.</td>
|
|---|
| 228 | </tr>
|
|---|
| 229 | <tr>
|
|---|
| 230 | <td valign="top">retriesAllowed</td>
|
|---|
| 231 | <td valign="top">Set the number of retries allowed on an file-transfer operation.
|
|---|
| 232 | If a number > 0 specified, each file transfer can fail up to that
|
|---|
| 233 | many times before the operation is failed. If -1 or "forever" specified, the
|
|---|
| 234 | operation will keep trying until it succeeds.</td>
|
|---|
| 235 | <td valign="top" align="center">No; defaults to 0</td>
|
|---|
| 236 | </tr>
|
|---|
| 237 | <tr>
|
|---|
| 238 | <td valign="top">siteCommand</td>
|
|---|
| 239 | <td valign="top">Set the server-specific SITE command to execute if
|
|---|
| 240 | the <code>action</code> attribute has been specified as <code>"site"</code>.
|
|---|
| 241 | <td valign="top" align="center">No</td>
|
|---|
| 242 | </tr>
|
|---|
| 243 | <tr>
|
|---|
| 244 | <td valign="top">initialSiteCommand</td>
|
|---|
| 245 | <td valign="top">Set a server-specific SITE command to execute immediately
|
|---|
| 246 | after login.
|
|---|
| 247 | <td valign="top" align="center">No</td>
|
|---|
| 248 | </tr>
|
|---|
| 249 |
|
|---|
| 250 | <tr>
|
|---|
| 251 | <td colspan="3">
|
|---|
| 252 | <p><b>The following attributes require <a href=
|
|---|
| 253 | "http://jakarta.apache.org/commons/net/download.html">
|
|---|
| 254 | jakarta-commons-net-1.4.0 or greater</a>.</b></p>
|
|---|
| 255 | <p>
|
|---|
| 256 | Use these options when the standard options don't work, because
|
|---|
| 257 | <ul><li>the server is in a different timezone and you need timestamp
|
|---|
| 258 | dependency checking</li>
|
|---|
| 259 | <li>the default timestamp formatting doesn't match the server display and
|
|---|
| 260 | list parsing therefore fails</li></ul>
|
|---|
| 261 | </p><p>
|
|---|
| 262 | If none of these is specified, the default mechanism of letting the system
|
|---|
| 263 | auto-detect the server OS type based on the FTP SYST command and assuming
|
|---|
| 264 | standard formatting for that OS type will be used.
|
|---|
| 265 | </p><p>
|
|---|
| 266 | To aid in property-file-based development where a build script is configured
|
|---|
| 267 | with property files, for any of these attributes, a value of <code>""</code>
|
|---|
| 268 | is equivalent to not specifying it.
|
|---|
| 269 | </p><p>
|
|---|
| 270 | Please understand that these options are incompatible with the autodetection
|
|---|
| 271 | scheme. If any of these options is specified, (other than with a value of
|
|---|
| 272 | <code>""</code> ) a system type must be chosen and if systemTypeKey is not
|
|---|
| 273 | specified, UNIX will be assumed. The philosophy behind this is that these
|
|---|
| 274 | options are for setting non-standard formats, and a build-script author who
|
|---|
| 275 | knows what system he is dealing with will know what options to need to be
|
|---|
| 276 | set. Otherwise, these options should be left alone and the default
|
|---|
| 277 | autodetection scheme can be used and will work in the majority of cases.
|
|---|
| 278 | </p></td>
|
|---|
| 279 | </tr>
|
|---|
| 280 | <tr>
|
|---|
| 281 | <td valign="top">systemTypeKey</td>
|
|---|
| 282 | <td valign="top">Specifies the type of system in use on the server.
|
|---|
| 283 | Supported values are <code>"UNIX", "VMS", "WINDOWS", "OS/2", "OS/400",
|
|---|
| 284 | "MVS".</code> If not specified, (or specified as <code>""</code>) and if
|
|---|
| 285 | no other xxxConfig attributes are specified, the autodectection mechanism
|
|---|
| 286 | based on the FTP SYST command will be used.<br>
|
|---|
| 287 | Since ant 1.7
|
|---|
| 288 | </td>
|
|---|
| 289 | <td valign="top" align="center">No, but if any of the following xxxConfig
|
|---|
| 290 | attributes is specified, UNIX will be assumed, even if <code>""</code>
|
|---|
| 291 | is specified here.
|
|---|
| 292 | </td>
|
|---|
| 293 | </tr>
|
|---|
| 294 | <tr>
|
|---|
| 295 | <td valign="top">serverTimeZoneConfig</td>
|
|---|
| 296 | <td valign="top">Specify as a Java
|
|---|
| 297 | <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/TimeZone.html">
|
|---|
| 298 | TimeZone</a> identifier, (e.g. <code>GMT</code>, <code>America/Chicago</code> or
|
|---|
| 299 | <code>Asia/Jakarta</code>) the timezone used by the server for timestamps. This
|
|---|
| 300 | enables timestamp dependency checking even when the server is in a different
|
|---|
| 301 | time zone from the client. Time Zones know, also, about daylight savings time,
|
|---|
| 302 | and do not require you to calculate milliseconds of difference. If not specified,
|
|---|
| 303 | (or specified as <code>""</code>), the time zone of the client is assumed.<br>
|
|---|
| 304 | Since ant 1.7
|
|---|
| 305 | </td>
|
|---|
| 306 | <td valign="top" align="center">No</td>
|
|---|
| 307 | </tr>
|
|---|
| 308 | <tr>
|
|---|
| 309 |
|
|---|
| 310 | <td valign="top">defaultDateFormatConfig</td>
|
|---|
| 311 | <td valign="top">Specify in Java
|
|---|
| 312 | <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html">
|
|---|
| 313 | SimpleDateFormat</a> notation, (e.g.
|
|---|
| 314 | <code>yyyy-MM-dd</code>), the date format generally used by the FTP server
|
|---|
| 315 | to parse dates. In some cases this will be the only date format used.
|
|---|
| 316 | In others, (unix for example) this will be used for dates
|
|---|
| 317 | older than a year old. (See <b>recentDateFormatConfig</b>). If not specified,
|
|---|
| 318 | (or specified as <code>""</code>), the default date format for the system
|
|---|
| 319 | type indicated by the <b>systemTypeKey</b> attribute will be used.<br>
|
|---|
| 320 | Since ant 1.7
|
|---|
| 321 | </td>
|
|---|
| 322 | <td valign="top" align="center">
|
|---|
| 323 | No.
|
|---|
| 324 | </td>
|
|---|
| 325 | </tr>
|
|---|
| 326 | <tr>
|
|---|
| 327 | <td valign="top">recentDateFormatConfig</td>
|
|---|
| 328 | <td valign="top">Specify in Java
|
|---|
| 329 | <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html">
|
|---|
| 330 | SimpleDateFormat</a> notation,
|
|---|
| 331 | (e.g. <code>MMM dd hh:mm</code>) the date format used by the FTP server
|
|---|
| 332 | to parse dates less than a year old. If not specified (or specified as
|
|---|
| 333 | <code>""</code>), and if the system type indicated by the system key uses
|
|---|
| 334 | a recent date format, its standard format will be used.<br>
|
|---|
| 335 | Since ant 1.7
|
|---|
| 336 | </td>
|
|---|
| 337 | <td valign="top" align="center">No</td>
|
|---|
| 338 | </tr>
|
|---|
| 339 | <tr>
|
|---|
| 340 | <td valign="top">serverLanguageCodeConfig</td>
|
|---|
| 341 | <td valign="top">a <a href="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt">
|
|---|
| 342 | two-letter ISO-639 language code</a> used to specify the
|
|---|
| 343 | language used by the server to format month names. This only needs to be
|
|---|
| 344 | specified when the server uses non-numeric abbreviations for months in its
|
|---|
| 345 | date listings in a language other than English. This appears to be
|
|---|
| 346 | becoming rarer and rarer, as commonly distributed ftp servers seem
|
|---|
| 347 | increasingly to use English or all-numeric formats.
|
|---|
| 348 | Languages supported are:
|
|---|
| 349 | <ul>
|
|---|
| 350 | <li>en - English</li>
|
|---|
| 351 | <li>fr - French</li>
|
|---|
| 352 | <li>de - German</li>
|
|---|
| 353 | <li>it - Italian</li>
|
|---|
| 354 | <li>es - Spanish</li>
|
|---|
| 355 | <li>pt - Portuguese</li>
|
|---|
| 356 | <li>da - Danish</li>
|
|---|
| 357 | <li>sv - Swedish</li>
|
|---|
| 358 | <li>no - Norwegian</li>
|
|---|
| 359 | <li>nl - Dutch</li>
|
|---|
| 360 | <li>ro - Romanian</li>
|
|---|
| 361 | <li>sq - Albanian</li>
|
|---|
| 362 | <li>sh - Serbo-croatian</li>
|
|---|
| 363 | <li>sk - Slovak</li>
|
|---|
| 364 | <li>sl - Slovenian</li>
|
|---|
| 365 | </ul>
|
|---|
| 366 | If you require a language other than the above, see also the
|
|---|
| 367 | <b>shortMonthNamesConfig</b> attribute.<br>
|
|---|
| 368 | Since ant 1.7
|
|---|
| 369 | </td>
|
|---|
| 370 |
|
|---|
| 371 | <td valign="top" align="center">No</td>
|
|---|
| 372 | </tr>
|
|---|
| 373 | <tr>
|
|---|
| 374 | <td valign="top">shortMonthNamesConfig</td>
|
|---|
| 375 | <td valign="top">specify the month abbreviations used on the server in file
|
|---|
| 376 | timestamp dates as a pipe-delimited string for each month. For example,
|
|---|
| 377 | a set of month names used by a hypothetical
|
|---|
| 378 | Icelandic FTP server might conceivably be specified as
|
|---|
| 379 | <code>"jan|feb|mar|apr|maí|jún|júl|ágú|sep|okt|nóv|des"</code>.
|
|---|
| 380 | This attribute exists primarily to support languages not supported by
|
|---|
| 381 | the <b>serverLanguageCode</b> attribute.<br>
|
|---|
| 382 | Since ant 1.7
|
|---|
| 383 | </td>
|
|---|
| 384 | <td valign="top" align="center">No</td>
|
|---|
| 385 | </tr>
|
|---|
| 386 | </table>
|
|---|
| 387 | <h3>Note about remotedir attribute</h3>
|
|---|
| 388 | <table border="1" cellpadding="2" cellspacing="0"
|
|---|
| 389 | >
|
|---|
| 390 | <tbody>
|
|---|
| 391 | <tr>
|
|---|
| 392 | <td style="vertical-align: top;" width="20%">Action<br>
|
|---|
| 393 | </td>
|
|---|
| 394 | <td style="vertical-align: top;" width="40%">meaning of <code>remotedir</code><br>
|
|---|
| 395 | </td>
|
|---|
| 396 | <td style="vertical-align: top;">use of nested <code>fileset</code>
|
|---|
| 397 | (s)<br>
|
|---|
| 398 | </td>
|
|---|
| 399 | </tr>
|
|---|
| 400 | <tr>
|
|---|
| 401 | <td style="vertical-align: top;" width="20%">send/put<br>
|
|---|
| 402 | </td>
|
|---|
| 403 | <td style="vertical-align: top;" width="40%">base directory to
|
|---|
| 404 | which the files are sent<br>
|
|---|
| 405 | </td>
|
|---|
| 406 | <td style="vertical-align: top;">they are used normally and
|
|---|
| 407 | evaluated on the local machine<br>
|
|---|
| 408 | </td>
|
|---|
| 409 | </tr>
|
|---|
| 410 | <tr>
|
|---|
| 411 | <td style="vertical-align: top;" width="20%">recv/get<br>
|
|---|
| 412 | </td>
|
|---|
| 413 | <td style="vertical-align: top;" width="40%">base directory from
|
|---|
| 414 | which the files are retrieved<br>
|
|---|
| 415 | </td>
|
|---|
| 416 | <td style="vertical-align: top;">the remote files located under
|
|---|
| 417 | the <code>remotedir </code>matching the include/exclude patterns of
|
|---|
| 418 | the <code>fileset </code></td>
|
|---|
| 419 | </tr>
|
|---|
| 420 | <tr>
|
|---|
| 421 | <td style="vertical-align: top;" width="20%">del/delete<br>
|
|---|
| 422 | </td>
|
|---|
| 423 | <td style="vertical-align: top;" width="40%">base directory from
|
|---|
| 424 | which files get deleted<br>
|
|---|
| 425 | </td>
|
|---|
| 426 | <td style="vertical-align: top;">the remote files located under
|
|---|
| 427 | the <code>remotedir </code>matching the include/exclude patterns of
|
|---|
| 428 | the <code>fileset <br>
|
|---|
| 429 | </code></td>
|
|---|
| 430 | </tr>
|
|---|
| 431 | <tr>
|
|---|
| 432 | <td style="vertical-align: top;" width="20%">list<br>
|
|---|
| 433 | </td>
|
|---|
| 434 | <td style="vertical-align: top;" width="40%">base directory from
|
|---|
| 435 | which files are listed<br>
|
|---|
| 436 | </td>
|
|---|
| 437 | <td style="vertical-align: top;">the remote files located under
|
|---|
| 438 | the <code>remotedir </code>matching the include/exclude patterns of
|
|---|
| 439 | the <code>fileset <br>
|
|---|
| 440 | </code></td>
|
|---|
| 441 | </tr>
|
|---|
| 442 | <tr>
|
|---|
| 443 | <td style="vertical-align: top;" width="20%">mkdir</td>
|
|---|
| 444 | <td style="vertical-align: top;" width="40%">directory to create<br>
|
|---|
| 445 | </td>
|
|---|
| 446 | <td style="vertical-align: top;">not used<br>
|
|---|
| 447 | </td>
|
|---|
| 448 | </tr>
|
|---|
| 449 | <tr>
|
|---|
| 450 | <td style="vertical-align: top;" width="20%">chmod</td>
|
|---|
| 451 | <td style="vertical-align: top;" width="40%">base directory from
|
|---|
| 452 | which the mode of files get changed<br>
|
|---|
| 453 | </td>
|
|---|
| 454 | <td style="vertical-align: top;">the remote files located under
|
|---|
| 455 | the <code>remotedir </code>matching the include/exclude patterns of
|
|---|
| 456 | the <code>fileset <br>
|
|---|
| 457 | </code></td>
|
|---|
| 458 | </tr>
|
|---|
| 459 | <tr>
|
|---|
| 460 | <td style="vertical-align: top;" width="20%">rmdir<br>
|
|---|
| 461 | </td>
|
|---|
| 462 | <td style="vertical-align: top;" width="40%">base directory from
|
|---|
| 463 | which directories get removed<br>
|
|---|
| 464 | </td>
|
|---|
| 465 | <td style="vertical-align: top;">the remote directories located
|
|---|
| 466 | under the <code>remotedir </code>matching the include/exclude
|
|---|
| 467 | patterns of the <code>fileset <br>
|
|---|
| 468 | </code></td>
|
|---|
| 469 | </tr>
|
|---|
| 470 | </tbody>
|
|---|
| 471 | </table><h3>Parameters specified as nested elements</h3>
|
|---|
| 472 | <h4>fileset</h4>
|
|---|
| 473 | <p>The ftp task supports any number of nested <a
|
|---|
| 474 | href="../CoreTypes/fileset.html"><code><fileset></code></a> elements to specify
|
|---|
| 475 | the files to be retrieved, or deleted, or listed, or whose mode you want to change.</p>
|
|---|
| 476 | <p>
|
|---|
| 477 | The attribute <code>followsymlinks</code> of <code>fileset</code> is supported on
|
|---|
| 478 | local (put) as well as remote (get, chmod, delete) filesets.
|
|---|
| 479 | <em>Before ant 1.6 there was no support of symbolic links in remote filesets.
|
|---|
| 480 | In order to exclude symbolic links (preserve the behavior of ant 1.5.x and older),
|
|---|
| 481 | you need to explicitly set <code>followsymlinks</code> to <code>false</code>.</em>
|
|---|
| 482 | On remote filesets hidden files are not checked for being symbolic links. Hidden
|
|---|
| 483 | files are currently assumed to not be symbolic links.
|
|---|
| 484 | </p>
|
|---|
| 485 | <p>
|
|---|
| 486 | Remote filesets do not support selectors.<br>
|
|---|
| 487 | </p>
|
|---|
| 488 |
|
|---|
| 489 | <h3>Sending Files</h3>
|
|---|
| 490 | <p>The easiest way to describe how to send files is with a couple of examples:</p>
|
|---|
| 491 | <pre>
|
|---|
| 492 | <ftp server="ftp.apache.org"
|
|---|
| 493 | userid="anonymous"
|
|---|
| 494 | password="[email protected]">
|
|---|
| 495 | <fileset dir="htdocs/manual"/>
|
|---|
| 496 | </ftp>
|
|---|
| 497 | </pre>
|
|---|
| 498 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
|---|
| 499 | uploads all files in the <code>htdocs/manual</code> directory
|
|---|
| 500 | to the default directory for that user.</p>
|
|---|
| 501 | <pre> <ftp server="ftp.apache.org"
|
|---|
| 502 | remotedir="incoming"
|
|---|
| 503 | userid="anonymous"
|
|---|
| 504 | password="[email protected]"
|
|---|
| 505 | depends="yes">
|
|---|
| 506 | <fileset dir="htdocs/manual"/>
|
|---|
| 507 | </ftp></pre>
|
|---|
| 508 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
|---|
| 509 | uploads all new or changed files in the <code>htdocs/manual</code> directory
|
|---|
| 510 | to the <code>incoming</code> directory relative to the default directory
|
|---|
| 511 | for <code>anonymous</code>.</p>
|
|---|
| 512 | <pre> <ftp server="ftp.apache.org"
|
|---|
| 513 | port="2121"
|
|---|
| 514 | remotedir="/pub/incoming"
|
|---|
| 515 | userid="coder"
|
|---|
| 516 | password="java1"
|
|---|
| 517 | passive="yes"
|
|---|
| 518 | depends="yes"
|
|---|
| 519 | binary="no">
|
|---|
| 520 | <fileset dir="htdocs/manual">
|
|---|
| 521 | <include name="**/*.html"/>
|
|---|
| 522 | </fileset>
|
|---|
| 523 | </ftp></pre>
|
|---|
| 524 | <p>Logs in to <code>ftp.apache.org</code> at port <code>2121</code> as
|
|---|
| 525 | <code>coder</code> with password <code>java1</code> and uploads all new or
|
|---|
| 526 | changed HTML files in the <code>htdocs/manual</code> directory to the
|
|---|
| 527 | <code>/pub/incoming</code> directory. The files are transferred in text mode.
|
|---|
| 528 | Passive mode has been switched on to send files from behind a firewall.</p>
|
|---|
| 529 | <pre> <ftp server="ftp.hypothetical.india.org"
|
|---|
| 530 | port="2121"
|
|---|
| 531 | remotedir="/pub/incoming"
|
|---|
| 532 | userid="coder"
|
|---|
| 533 | password="java1"
|
|---|
| 534 | depends="yes"
|
|---|
| 535 | binary="no"
|
|---|
| 536 | systemTypeKey="Windows"
|
|---|
| 537 | serverTimeZoneConfig="India/Calcutta">
|
|---|
| 538 | <fileset dir="htdocs/manual">
|
|---|
| 539 | <include name="**/*.html"/>
|
|---|
| 540 | </fileset>
|
|---|
| 541 | </ftp></pre>
|
|---|
| 542 | <p>Logs in to a Windows server at <code>ftp.hypothetical.india.org</code>
|
|---|
| 543 | at port <code>2121</code> as <code>coder</code> with password <code>java1</code>
|
|---|
| 544 | and uploads all new or changed (accounting for timezone differences)
|
|---|
| 545 | HTML files in the <code>htdocs/manual</code>
|
|---|
| 546 | directory to the <code>/pub/incoming</code> directory. The files are transferred
|
|---|
| 547 | in text mode.</p>
|
|---|
| 548 | <pre> <ftp server="ftp.nt.org"
|
|---|
| 549 | remotedir="c:\uploads"
|
|---|
| 550 | userid="coder"
|
|---|
| 551 | password="java1"
|
|---|
| 552 | separator="\"
|
|---|
| 553 | verbose="yes">
|
|---|
| 554 | <fileset dir="htdocs/manual">
|
|---|
| 555 | <include name="**/*.html"/>
|
|---|
| 556 | </fileset>
|
|---|
| 557 | </ftp></pre><p>Logs in to the Windows-based <code>ftp.nt.org</code> as
|
|---|
| 558 | <code>coder</code> with password <code>java1</code> and uploads all
|
|---|
| 559 | HTML files in the <code>htdocs/manual</code> directory to the
|
|---|
| 560 | <code>c:\uploads</code> directory. Progress messages are displayed as each
|
|---|
| 561 | file is uploaded.</p>
|
|---|
| 562 | <h3>Getting Files</h3>
|
|---|
| 563 | <p>Getting files from an FTP server works pretty much the same way as
|
|---|
| 564 | sending them does. The only difference is that the nested filesets
|
|---|
| 565 | use the remotedir attribute as the base directory for the files on the
|
|---|
| 566 | FTP server, and the dir attribute as the local directory to put the files
|
|---|
| 567 | into. The file structure from the FTP site is preserved on the local machine.</p>
|
|---|
| 568 | <pre>
|
|---|
| 569 | <ftp action="get"
|
|---|
| 570 | server="ftp.apache.org"
|
|---|
| 571 | userid="anonymous"
|
|---|
| 572 | password="[email protected]">
|
|---|
| 573 | <fileset dir="htdocs/manual">
|
|---|
| 574 | <include name="**/*.html"/>
|
|---|
| 575 | </fileset>
|
|---|
| 576 | </ftp>
|
|---|
| 577 | </pre>
|
|---|
| 578 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
|---|
| 579 | recursively downloads all .html files from default directory for that user
|
|---|
| 580 | into the <code>htdocs/manual</code> directory on the local machine.</p>
|
|---|
| 581 | <pre>
|
|---|
| 582 | <ftp action="get"
|
|---|
| 583 | server="ftp.apache.org"
|
|---|
| 584 | userid="anonymous"
|
|---|
| 585 | password="[email protected]"
|
|---|
| 586 | systemTypeKey="UNIX"
|
|---|
| 587 | defaultDateFormatConfig="yyyy-MM-dd HH:mm">
|
|---|
| 588 | <fileset dir="htdocs/manual">
|
|---|
| 589 | <include name="**/*.html"/>
|
|---|
| 590 | </fileset>
|
|---|
| 591 | </ftp>
|
|---|
| 592 | </pre>
|
|---|
| 593 | <p>If apache.org ever switches to a unix FTP server that uses the new all-numeric
|
|---|
| 594 | format for timestamps, this version would become necessary. It would accomplish
|
|---|
| 595 | the same functionality as the previous example but would successfully handle the
|
|---|
| 596 | numeric timestamps.
|
|---|
| 597 | The <code>systemTypeKey</code> is not necessary here but helps clarify what is
|
|---|
| 598 | going on.</p>
|
|---|
| 599 | <pre>
|
|---|
| 600 | <ftp action="get"
|
|---|
| 601 | server="ftp.hypthetical.fr"
|
|---|
| 602 | userid="anonymous"
|
|---|
| 603 | password="[email protected]"
|
|---|
| 604 | defaultDateFormatConfig="d MMM yyyy"
|
|---|
| 605 | recentDateFormatConfig="d MMM HH:mm"
|
|---|
| 606 | serverLanguageCodeConfig="fr">
|
|---|
| 607 | <fileset dir="htdocs/manual">
|
|---|
| 608 | <include name="**/*.html"/>
|
|---|
| 609 | </fileset>
|
|---|
| 610 | </ftp>
|
|---|
| 611 | </pre>
|
|---|
| 612 | <p>Logs into a UNIX FTP server at <code>ftp.hypothetical.fr</code> which displays
|
|---|
| 613 | dates with French names in Standard European format, as <code>anonymous</code>, and
|
|---|
| 614 | recursively downloads all .html files from default directory for that user
|
|---|
| 615 | into the <code>htdocs/manual</code> directory on the local machine.</p>
|
|---|
| 616 |
|
|---|
| 617 | <h3>Deleting Files</h3>
|
|---|
| 618 | As you've probably guessed by now, you use nested fileset elements to
|
|---|
| 619 | select the files to delete from the remote FTP server. Again, the
|
|---|
| 620 | filesets are relative to the remote directory, not a local directory. In
|
|---|
| 621 | fact, the dir attribute of the fileset is ignored completely.
|
|---|
| 622 |
|
|---|
| 623 | <pre>
|
|---|
| 624 | <ftp action="del"
|
|---|
| 625 | server="ftp.apache.org"
|
|---|
| 626 | userid="anonymous"
|
|---|
| 627 | password="[email protected]">
|
|---|
| 628 | <fileset>
|
|---|
| 629 | <include name="**/*.tmp"/>
|
|---|
| 630 | </fileset>
|
|---|
| 631 | </ftp>
|
|---|
| 632 | </pre>
|
|---|
| 633 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
|---|
| 634 | tries to delete all *.tmp files from the default directory for that user.
|
|---|
| 635 | If you don't have permission to delete a file, a BuildException is thrown.</p>
|
|---|
| 636 | <h3>Listing Files</h3>
|
|---|
| 637 | <pre>
|
|---|
| 638 | <ftp action="list"
|
|---|
| 639 | server="ftp.apache.org"
|
|---|
| 640 | userid="anonymous"
|
|---|
| 641 | password="[email protected]"
|
|---|
| 642 | listing="data/ftp.listing">
|
|---|
| 643 | <fileset>
|
|---|
| 644 | <include name="**"/>
|
|---|
| 645 | </fileset>
|
|---|
| 646 | </ftp>
|
|---|
| 647 | </pre>
|
|---|
| 648 | <p>This provides a file listing in <code>data/ftp.listing</code> of all the files on
|
|---|
| 649 | the FTP server relative to the default directory of the <code>anonymous</code>
|
|---|
| 650 | user. The listing is in whatever format the FTP server normally lists files.</p>
|
|---|
| 651 |
|
|---|
| 652 | <h3>Creating Directories</h3>
|
|---|
| 653 | <p>Note that with the mkdir action, the directory to create is specified using the
|
|---|
| 654 | remotedir attribute.</p>
|
|---|
| 655 | <pre>
|
|---|
| 656 | <ftp action="mkdir"
|
|---|
| 657 | server="ftp.apache.org"
|
|---|
| 658 | userid="anonymous"
|
|---|
| 659 | password="[email protected]"
|
|---|
| 660 | remotedir="some/remote/dir"/>
|
|---|
| 661 | </pre>
|
|---|
| 662 | <p>This creates the directory <code>some/remote/dir</code> beneath the default root
|
|---|
| 663 | directory. As with all other actions, the directory separator character must be correct
|
|---|
| 664 | according to the desires of the FTP server.</p>
|
|---|
| 665 | <h3>Removing Directories</h3>
|
|---|
| 666 | This action uses nested fileset elements to
|
|---|
| 667 | select the directories to remove from the remote FTP server. The
|
|---|
| 668 | filesets are relative to the remote directory, not a local directory.
|
|---|
| 669 | The dir attribute of the fileset is ignored completely.
|
|---|
| 670 | The directories to be removed must be empty, or contain only
|
|---|
| 671 | other directories that have been also selected to be removed by the filesets
|
|---|
| 672 | patterns, otherwise a BuildException will be thrown.
|
|---|
| 673 | Also, if you don't have permission to remove a directory, a BuildException is
|
|---|
| 674 | thrown.
|
|---|
| 675 |
|
|---|
| 676 | <pre>
|
|---|
| 677 | <ftp action="rmdir"
|
|---|
| 678 | server="ftp.apache.org"
|
|---|
| 679 | userid="anonymous"
|
|---|
| 680 | password="[email protected]"
|
|---|
| 681 | remotedir="/somedir" >
|
|---|
| 682 | <fileset>
|
|---|
| 683 | <include name="dira"/>
|
|---|
| 684 | <include name="dirb/**"/>
|
|---|
| 685 | </fileset>
|
|---|
| 686 | </ftp>
|
|---|
| 687 | </pre>
|
|---|
| 688 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
|---|
| 689 | tries to remove <code>/somedir/dira</code> directory and
|
|---|
| 690 | all the directories tree starting at, and including, <code>/somedir/dirb</code>.
|
|---|
| 691 | When removing the <code>/somedir/dirb</code> tree,
|
|---|
| 692 | it will start at the leaves moving up to the root, so that when
|
|---|
| 693 | it tries to remove a directory it is sure all the directories under it are
|
|---|
| 694 | already removed.
|
|---|
| 695 | Obviously all the files in the tree must have been already deleted.
|
|---|
| 696 | </p>
|
|---|
| 697 | <p>As an example suppose you want to delete everything contained into
|
|---|
| 698 | <code>/somedir</code>, so invoke first the <code><ftp></code> task with
|
|---|
| 699 | <code>action="delete"</code>, then with
|
|---|
| 700 | <code>action="rmdir"</code> specifying in both cases
|
|---|
| 701 | <code>remotedir="/somedir"</code> and
|
|---|
| 702 |
|
|---|
| 703 | <pre>
|
|---|
| 704 | <fileset>
|
|---|
| 705 | <include name="**"/>
|
|---|
| 706 | </fileset>
|
|---|
| 707 | </pre>
|
|---|
| 708 |
|
|---|
| 709 | The directory specified in the <code>remotedir</code> parameter is never
|
|---|
| 710 | selected for remove, so if you need to remove it, specify its parent in
|
|---|
| 711 | <code>remotedir</code> parameter and include it in the
|
|---|
| 712 | <code><fileset></code> pattern, like <code>"somedir/**"</code>.
|
|---|
| 713 | </p>
|
|---|
| 714 |
|
|---|
| 715 |
|
|---|
| 716 | </body>
|
|---|
| 717 | </html>
|
|---|
| 718 |
|
|---|
