1 | <html>
|
---|
2 |
|
---|
3 | <head>
|
---|
4 | <meta http-equiv="Content-Language" content="en-us">
|
---|
5 | <title>FTP Task</title>
|
---|
6 | <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
|
---|
7 | </head>
|
---|
8 |
|
---|
9 | <body>
|
---|
10 |
|
---|
11 | <h2><a name="ftp">FTP</a></h2>
|
---|
12 | <h3>Description</h3>
|
---|
13 | <p>The ftp task implements a basic FTP client that can send, receive,
|
---|
14 | list, delete files, and create directories. See below for descriptions and examples of how
|
---|
15 | to perform each task.</p>
|
---|
16 | <p><b>Note:</b> This task depends on external libraries not included in the Ant distribution.
|
---|
17 | See <a href="../install.html#commons-net">Library Dependencies</a> for more information.</p>
|
---|
18 | <p>The ftp task attempts to determine what file system is in place on the FTP server.
|
---|
19 | Supported server types are Unix, NT, OS2, VMS, and OS400. In addition, NT and OS400 servers
|
---|
20 | which have been configured to display the directory in Unix style are also supported correctly.
|
---|
21 | Otherwise, the system will default to Unix standards.
|
---|
22 | <i>remotedir</i> must be specified in the exact syntax required by the ftp
|
---|
23 | server. If the usual Unix conventions are not supported by the server,
|
---|
24 | <i>separator</i> can be used to set the file separator that should be used
|
---|
25 | instead.</p>
|
---|
26 | <p>See the section on <a href="../dirtasks.html#directorybasedtasks">directory based
|
---|
27 | tasks</a>, on how the inclusion/exclusion of files works, and how to
|
---|
28 | write patterns.</p>
|
---|
29 | <p>
|
---|
30 | This task does not currently use the proxy information set by the
|
---|
31 | <a href="setproxy.html"><code><setproxy></code></a> task, and cannot go through
|
---|
32 | a firewall via socks.
|
---|
33 | <p>
|
---|
34 | <b>Warning: </b> there have been problems reported concerning the ftp get with newer attribute.
|
---|
35 | Problems might be due to format of ls -l differing from what is expected by commons-net,
|
---|
36 | for instance due to specificities of language used by the ftp server in the directory listing.
|
---|
37 | If you encounter such a problem, please send an email including a sample directory listing
|
---|
38 | coming from your ftp server (ls -l on the ftp prompt).
|
---|
39 | <h3>Parameters</h3>
|
---|
40 | <table border="1" cellpadding="2" cellspacing="0">
|
---|
41 | <tr>
|
---|
42 | <td valign="top"><b>Attribute</b></td>
|
---|
43 | <td valign="top"><b>Description</b></td>
|
---|
44 | <td align="center" valign="top"><b>Required</b></td>
|
---|
45 | </tr>
|
---|
46 | <tr>
|
---|
47 | <td valign="top">server</td>
|
---|
48 | <td valign="top">the address of the remote ftp server.</td>
|
---|
49 | <td valign="top" align="center">Yes</td>
|
---|
50 | </tr>
|
---|
51 | <tr>
|
---|
52 | <td valign="top">port</td>
|
---|
53 | <td valign="top">the port number of the remote ftp server.
|
---|
54 | Defaults to port 21.</td>
|
---|
55 | <td valign="top" align="center">No</td>
|
---|
56 | </tr>
|
---|
57 | <tr>
|
---|
58 | <td valign="top">userid</td>
|
---|
59 | <td valign="top">the login id to use on the ftp server.</td>
|
---|
60 | <td valign="top" align="center">Yes</td>
|
---|
61 | </tr>
|
---|
62 | <tr>
|
---|
63 | <td valign="top">password</td>
|
---|
64 | <td valign="top">the login password to use on the ftp server.</td>
|
---|
65 | <td valign="top" align="center">Yes</td>
|
---|
66 | </tr>
|
---|
67 | <tr>
|
---|
68 | <td valign="top">remotedir</td>
|
---|
69 | <td valign="top">remote directory on the
|
---|
70 | ftp server
|
---|
71 | see table below for detailed usage
|
---|
72 | </td>
|
---|
73 | <td valign="top" align="center">No</td>
|
---|
74 | </tr>
|
---|
75 | <tr>
|
---|
76 | <td valign="top">action</td>
|
---|
77 | <td valign="top">the ftp action to perform, defaulting to "send".
|
---|
78 | Currently supports "put", "get",
|
---|
79 | "del", "list", "chmod",
|
---|
80 | "mkdir" and "rmdir".</td>
|
---|
81 | <td valign="top" align="center">No</td>
|
---|
82 | </tr>
|
---|
83 | <tr>
|
---|
84 | <td valign="top">binary</td>
|
---|
85 | <td valign="top">selects binary-mode ("yes") or text-mode
|
---|
86 | ("no") transfers.
|
---|
87 | Defaults to "yes"</td>
|
---|
88 | <td valign="top" align="center">No</td>
|
---|
89 | </tr>
|
---|
90 | <tr>
|
---|
91 | <td valign="top">passive</td>
|
---|
92 | <td valign="top">selects passive-mode ("yes") transfers.
|
---|
93 | Defaults to "no"</td>
|
---|
94 | <td valign="top" align="center">No</td>
|
---|
95 | </tr>
|
---|
96 | <tr>
|
---|
97 | <td valign="top">verbose</td>
|
---|
98 | <td valign="top">displays information on each file transferred if set
|
---|
99 | to "yes". Defaults to "no".</td>
|
---|
100 | <td valign="top" align="center">No</td>
|
---|
101 | </tr>
|
---|
102 | <tr>
|
---|
103 | <td valign="top">depends</td>
|
---|
104 | <td valign="top">transfers only new or changed files if set to
|
---|
105 | "yes". Defaults to "no".</td>
|
---|
106 | <td valign="top" align="center">No</td>
|
---|
107 | </tr>
|
---|
108 | <tr>
|
---|
109 | <td valign="top">newer</td>
|
---|
110 | <td valign="top">a synonym for <i>depends</i>.
|
---|
111 | see timediffauto and timediffmillis</td>
|
---|
112 | <td valign="top" align="center">No</td>
|
---|
113 | </tr>
|
---|
114 | <tr>
|
---|
115 | <td valign="top">timediffauto</td>
|
---|
116 | <td valign="top">set to <code>"true"</code>
|
---|
117 | to make ant calculate the time difference between client and server.<br/>
|
---|
118 | <em>requires write access in the remote directory</em><br/>
|
---|
119 | Since ant 1.6</td>
|
---|
120 | <td valign="top" align="center">No</td>
|
---|
121 | </tr>
|
---|
122 | <tr>
|
---|
123 | <td valign="top">timediffmillis</td>
|
---|
124 | <td valign="top">number of milliseconds to add to the time on the remote machine
|
---|
125 | to get the time on the local machine.<br/>
|
---|
126 | Since ant 1.6
|
---|
127 | </td>
|
---|
128 | <td valign="top" align="center">No</td>
|
---|
129 | </tr>
|
---|
130 | <tr>
|
---|
131 | <td valign="top">separator</td>
|
---|
132 | <td valign="top">sets the file separator used on the ftp server.
|
---|
133 | Defaults to "/".</td>
|
---|
134 | <td valign="top" align="center">No</td>
|
---|
135 | </tr>
|
---|
136 | <tr>
|
---|
137 | <td valign="top">umask</td>
|
---|
138 | <td valign="top">sets the default file permissions for new files,
|
---|
139 | unix only.</td>
|
---|
140 | <td valign="top" align="center">No</td>
|
---|
141 | </tr>
|
---|
142 | <tr>
|
---|
143 | <td valign="top">chmod</td>
|
---|
144 | <td valign="top">sets or changes file permissions for new or existing files,
|
---|
145 | unix only. If used with a put action, chmod will be issued for each file.</td>
|
---|
146 | <td valign="top" align="center">No</td>
|
---|
147 | </tr>
|
---|
148 | <tr>
|
---|
149 | <td valign="top">listing</td>
|
---|
150 | <td valign="top">the file to write results of the "list" action.
|
---|
151 | Required for the "list" action, ignored otherwise.</td>
|
---|
152 | <td valign="top" align="center">No</td>
|
---|
153 | </tr>
|
---|
154 | <tr>
|
---|
155 | <td valign="top">ignoreNoncriticalErrors</td>
|
---|
156 | <td valign="top">flag which permits the task to ignore some non-fatal error
|
---|
157 | codes sent by some servers during directory creation: wu-ftp in particular.
|
---|
158 | Default: false</td>
|
---|
159 | <td valign="top" align="center">No</td>
|
---|
160 | </tr>
|
---|
161 | <tr>
|
---|
162 | <td valign="top">skipFailedTransfers</td>
|
---|
163 | <td valign="top">flag which enables unsuccessful file put, delete
|
---|
164 | and get operations to be skipped with a warning and the
|
---|
165 | remainder of the files still transferred. Default: false</td>
|
---|
166 | <td valign="top" align="center">No</td>
|
---|
167 | </tr>
|
---|
168 | <tr>
|
---|
169 | <td valign="top">preservelastmodified</td>
|
---|
170 | <td valign="top">Give the copied files the same last modified
|
---|
171 | time as the original source files (applies to getting files only).
|
---|
172 | (<em>Note</em>: Ignored on Java 1.1)</td>
|
---|
173 | <td valign="top" align="center">No; defaults to false.</td>
|
---|
174 | </tr>
|
---|
175 | </table>
|
---|
176 | <h3>Note about remotedir attribute</h3>
|
---|
177 | <table border="1" cellpadding="2" cellspacing="0"
|
---|
178 | >
|
---|
179 | <tbody>
|
---|
180 | <tr>
|
---|
181 | <td style="vertical-align: top;" width="20%">Action<br>
|
---|
182 | </td>
|
---|
183 | <td style="vertical-align: top;" width="40%">meaning of <code>remotedir</code><br>
|
---|
184 | </td>
|
---|
185 | <td style="vertical-align: top;">use of nested <code>fileset</code>
|
---|
186 | (s)<br>
|
---|
187 | </td>
|
---|
188 | </tr>
|
---|
189 | <tr>
|
---|
190 | <td style="vertical-align: top;" width="20%">send/put<br>
|
---|
191 | </td>
|
---|
192 | <td style="vertical-align: top;" width="40%">base directory to
|
---|
193 | which the files are sent<br>
|
---|
194 | </td>
|
---|
195 | <td style="vertical-align: top;">they are used normally and
|
---|
196 | evaluated on the local machine<br>
|
---|
197 | </td>
|
---|
198 | </tr>
|
---|
199 | <tr>
|
---|
200 | <td style="vertical-align: top;" width="20%">recv/get<br>
|
---|
201 | </td>
|
---|
202 | <td style="vertical-align: top;" width="40%">base directory from
|
---|
203 | which the files are retrieved<br>
|
---|
204 | </td>
|
---|
205 | <td style="vertical-align: top;">the remote files located under
|
---|
206 | the <code>remotedir </code>matching the include/exclude patterns of
|
---|
207 | the <code>fileset </code></td>
|
---|
208 | </tr>
|
---|
209 | <tr>
|
---|
210 | <td style="vertical-align: top;" width="20%">del/delete<br>
|
---|
211 | </td>
|
---|
212 | <td style="vertical-align: top;" width="40%">base directory from
|
---|
213 | which files get deleted<br>
|
---|
214 | </td>
|
---|
215 | <td style="vertical-align: top;">the remote files located under
|
---|
216 | the <code>remotedir </code>matching the include/exclude patterns of
|
---|
217 | the <code>fileset <br>
|
---|
218 | </code></td>
|
---|
219 | </tr>
|
---|
220 | <tr>
|
---|
221 | <td style="vertical-align: top;" width="20%">list<br>
|
---|
222 | </td>
|
---|
223 | <td style="vertical-align: top;" width="40%">base directory from
|
---|
224 | which files are listed<br>
|
---|
225 | </td>
|
---|
226 | <td style="vertical-align: top;">the remote files located under
|
---|
227 | the <code>remotedir </code>matching the include/exclude patterns of
|
---|
228 | the <code>fileset <br>
|
---|
229 | </code></td>
|
---|
230 | </tr>
|
---|
231 | <tr>
|
---|
232 | <td style="vertical-align: top;" width="20%">mkdir</td>
|
---|
233 | <td style="vertical-align: top;" width="40%">directory to create<br>
|
---|
234 | </td>
|
---|
235 | <td style="vertical-align: top;">not used<br>
|
---|
236 | </td>
|
---|
237 | </tr>
|
---|
238 | <tr>
|
---|
239 | <td style="vertical-align: top;" width="20%">chmod</td>
|
---|
240 | <td style="vertical-align: top;" width="40%">base directory from
|
---|
241 | which the mode of files get changed<br>
|
---|
242 | </td>
|
---|
243 | <td style="vertical-align: top;">the remote files located under
|
---|
244 | the <code>remotedir </code>matching the include/exclude patterns of
|
---|
245 | the <code>fileset <br>
|
---|
246 | </code></td>
|
---|
247 | </tr>
|
---|
248 | <tr>
|
---|
249 | <td style="vertical-align: top;" width="20%">rmdir<br>
|
---|
250 | </td>
|
---|
251 | <td style="vertical-align: top;" width="40%">base directory from
|
---|
252 | which directories get removed<br>
|
---|
253 | </td>
|
---|
254 | <td style="vertical-align: top;">the remote directories located
|
---|
255 | under the <code>remotedir </code>matching the include/exclude
|
---|
256 | patterns of the <code>fileset <br>
|
---|
257 | </code></td>
|
---|
258 | </tr>
|
---|
259 | </tbody>
|
---|
260 | </table><h3>Parameters specified as nested elements</h3>
|
---|
261 | <h4>fileset</h4>
|
---|
262 | <p>The ftp task supports any number of nested <a
|
---|
263 | href="../CoreTypes/fileset.html"><code><fileset></code></a> elements to specify
|
---|
264 | the files to be retrieved, or deleted, or listed, or whose mode you want to change.</p>
|
---|
265 | <p>
|
---|
266 | The attribute <code>followsymlinks</code> of <code>fileset</code> is fully supported on
|
---|
267 | local (put) as well as remote (get, chmod, delete) filesets.
|
---|
268 | <em>Before ant 1.6 there was no support of symbolic links in remote filesets.
|
---|
269 | In order to exclude symbolic links (preserve the behavior of ant 1.5.x and older),
|
---|
270 | you need to explicitly set <code>followsymlinks</code> to <code>false</code>.</em>
|
---|
271 | </p>
|
---|
272 | <p>
|
---|
273 | Remote filesets do not support selectors.<br/>
|
---|
274 | </p>
|
---|
275 |
|
---|
276 | <h3>Sending Files</h3>
|
---|
277 | <p>The easiest way to describe how to send files is with a couple of examples:</p>
|
---|
278 | <pre>
|
---|
279 | <ftp server="ftp.apache.org"
|
---|
280 | userid="anonymous"
|
---|
281 | password="[email protected]">
|
---|
282 | <fileset dir="htdocs/manual"/>
|
---|
283 | </ftp>
|
---|
284 | </pre>
|
---|
285 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
---|
286 | uploads all files in the <code>htdocs/manual</code> directory
|
---|
287 | to the default directory for that user.</p>
|
---|
288 | <pre> <ftp server="ftp.apache.org"
|
---|
289 | remotedir="incoming"
|
---|
290 | userid="anonymous"
|
---|
291 | password="[email protected]"
|
---|
292 | depends="yes"
|
---|
293 | >
|
---|
294 | <fileset dir="htdocs/manual"/>
|
---|
295 | </ftp></pre>
|
---|
296 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
---|
297 | uploads all new or changed files in the <code>htdocs/manual</code> directory
|
---|
298 | to the <code>incoming</code> directory relative to the default directory
|
---|
299 | for <code>anonymous</code>.</p>
|
---|
300 | <pre> <ftp server="ftp.apache.org"
|
---|
301 | port="2121"
|
---|
302 | remotedir="/pub/incoming"
|
---|
303 | userid="coder"
|
---|
304 | password="java1"
|
---|
305 | depends="yes"
|
---|
306 | binary="no"
|
---|
307 | >
|
---|
308 | <fileset dir="htdocs/manual">
|
---|
309 | <include name="**/*.html"/>
|
---|
310 | </fileset>
|
---|
311 | </ftp></pre>
|
---|
312 | <p>Logs in to <code>ftp.apache.org</code> at port <code>2121</code> as
|
---|
313 | <code>coder</code> with password <code>java1</code> and uploads all new or
|
---|
314 | changed HTML files in the <code>htdocs/manual</code> directory to the
|
---|
315 | <code>/pub/incoming</code> directory. The files are transferred in text mode. Passive mode has been switched on to send files from behind a firewall.</p>
|
---|
316 | <pre> <ftp server="ftp.nt.org"
|
---|
317 | remotedir="c:\uploads"
|
---|
318 | userid="coder"
|
---|
319 | password="java1"
|
---|
320 | separator="\"
|
---|
321 | verbose="yes"</pre>
|
---|
322 | <PRE>
|
---|
323 | >
|
---|
324 | <fileset dir="htdocs/manual">
|
---|
325 | <include name="**/*.html"/>
|
---|
326 | </fileset>
|
---|
327 | </ftp></PRE><p>Logs in to the Windows-based <code>ftp.nt.org</code> as
|
---|
328 | <code>coder</code> with password <code>java1</code> and uploads all
|
---|
329 | HTML files in the <code>htdocs/manual</code> directory to the
|
---|
330 | <code>c:\uploads</code> directory. Progress messages are displayed as each
|
---|
331 | file is uploaded.</p>
|
---|
332 | <h3>Getting Files</h3>
|
---|
333 | <p>Getting files from an FTP server works pretty much the same way as
|
---|
334 | sending them does. The only difference is that the nested filesets
|
---|
335 | use the remotedir attribute as the base directory for the files on the
|
---|
336 | FTP server, and the dir attribute as the local directory to put the files
|
---|
337 | into. The file structure from the FTP site is preserved on the local machine.</p>
|
---|
338 | <pre>
|
---|
339 | <ftp action="get"
|
---|
340 | server="ftp.apache.org"
|
---|
341 | userid="anonymous"
|
---|
342 | password="[email protected]">
|
---|
343 | <fileset dir="htdocs/manual">
|
---|
344 | <include name="**/*.html"/>
|
---|
345 | </fileset>
|
---|
346 | </ftp>
|
---|
347 | </pre>
|
---|
348 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
---|
349 | recursively downloads all .html files from default directory for that user
|
---|
350 | into the <code>htdocs/manual</code> directory on the local machine.</p>
|
---|
351 | .
|
---|
352 | <h3>Deleting Files</h3>
|
---|
353 | As you've probably guessed by now, you use nested fileset elements to
|
---|
354 | select the files to delete from the remote FTP server. Again, the
|
---|
355 | filesets are relative to the remote directory, not a local directory. In
|
---|
356 | fact, the dir attribute of the fileset is ignored completely.
|
---|
357 |
|
---|
358 | <pre>
|
---|
359 | <ftp action="del"
|
---|
360 | server="ftp.apache.org"
|
---|
361 | userid="anonymous"
|
---|
362 | password="[email protected]">
|
---|
363 | <fileset>
|
---|
364 | <include name="**/*.tmp"/>
|
---|
365 | </fileset>
|
---|
366 | </ftp>
|
---|
367 | </pre>
|
---|
368 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
---|
369 | tries to delete all *.tmp files from the default directory for that user.
|
---|
370 | If you don't have permission to delete a file, a BuildException is thrown.</p>
|
---|
371 | <h3>Listing Files</h3>
|
---|
372 | <pre>
|
---|
373 | <ftp action="list"
|
---|
374 | server="ftp.apache.org"
|
---|
375 | userid="anonymous"
|
---|
376 | password="[email protected]"
|
---|
377 | listing="data/ftp.listing">
|
---|
378 | <fileset>
|
---|
379 | <include name="**"/>
|
---|
380 | </fileset>
|
---|
381 | </ftp>
|
---|
382 | </pre>
|
---|
383 | <p>This provides a file listing in <code>data/ftp.listing</code> of all the files on
|
---|
384 | the FTP server relative to the default directory of the <code>anonymous</code>
|
---|
385 | user. The listing is in whatever format the FTP server normally lists files.</p>
|
---|
386 |
|
---|
387 | <h3>Creating Directories</h3>
|
---|
388 | <p>Note that with the mkdir action, the directory to create is specified using the
|
---|
389 | remotedir attribute.</p>
|
---|
390 | <pre>
|
---|
391 | <ftp action="mkdir"
|
---|
392 | server="ftp.apache.org"
|
---|
393 | userid="anonymous"
|
---|
394 | password="[email protected]"
|
---|
395 | remotedir="some/remote/dir"/>
|
---|
396 | </pre>
|
---|
397 | <p>This creates the directory <code>some/remote/dir</code> beneath the default root
|
---|
398 | directory. As with all other actions, the directory separator character must be correct
|
---|
399 | according to the desires of the FTP server.</p>
|
---|
400 | <h3>Removing Directories</h3>
|
---|
401 | This action uses nested fileset elements to
|
---|
402 | select the directories to remove from the remote FTP server. The
|
---|
403 | filesets are relative to the remote directory, not a local directory.
|
---|
404 | The dir attribute of the fileset is ignored completely.
|
---|
405 | The directories to be removed must be empty, or contain only
|
---|
406 | other directories that have been also selected to be removed by the filesets
|
---|
407 | patterns, otherwise a BuildException will be thrown.
|
---|
408 | Also, if you don't have permission to remove a directory, a BuildException is
|
---|
409 | thrown.
|
---|
410 |
|
---|
411 | <pre>
|
---|
412 | <ftp action="rmdir"
|
---|
413 | server="ftp.apache.org"
|
---|
414 | userid="anonymous"
|
---|
415 | password="[email protected]"
|
---|
416 | remotedir="/somedir" >
|
---|
417 | <fileset>
|
---|
418 | <include name="dira"/>
|
---|
419 | <include name="dirb/**"/>
|
---|
420 | </fileset>
|
---|
421 | </ftp>
|
---|
422 | </pre>
|
---|
423 | <p>Logs in to <code>ftp.apache.org</code> as <code>anonymous</code> and
|
---|
424 | tries to remove <code>/somedir/dira</code> directory and
|
---|
425 | all the directories tree starting at, and including, <code>/somedir/dirb</code>.
|
---|
426 | When removing the <code>/somedir/dirb</code> tree,
|
---|
427 | it will start at the leaves moving up to the root, so that when
|
---|
428 | it tries to remove a directory it is sure all the directories under it are
|
---|
429 | already removed.
|
---|
430 | Obviously all the files in the tree must have been already deleted.
|
---|
431 | </p>
|
---|
432 | <p>As an example suppose you want to delete everything contained into
|
---|
433 | <code>/somedir</code>, so invoke first the <code><ftp></code> task with
|
---|
434 | <code>action="delete"</code>, then with
|
---|
435 | <code>action="rmdir"</code> specifying in both cases
|
---|
436 | <code>remotedir="/somedir"</code> and
|
---|
437 |
|
---|
438 | <pre>
|
---|
439 | <fileset>
|
---|
440 | <include name="**"/>
|
---|
441 | </fileset>
|
---|
442 | </pre>
|
---|
443 |
|
---|
444 | The directory specified in the <code>remotedir</code> parameter is never
|
---|
445 | selected for remove, so if you need to remove it, specify its parent in
|
---|
446 | <code>remotedir</code> parameter and include it in the
|
---|
447 | <code><fileset></code> pattern, like <code>"somedir/**"</code>.
|
---|
448 | </p>
|
---|
449 | <hr>
|
---|
450 | <p align="center">Copyright © 2000-2004 The Apache Software Foundation. All rights
|
---|
451 | Reserved.</p>
|
---|
452 |
|
---|
453 | </body>
|
---|
454 | </html>
|
---|
455 |
|
---|