1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
<title>Get Task</title>
</head>
<body>
<h2><a name="get">Get</a></h2>
<h3>Description</h3>
<p>Gets files from URLs. When the verbose option is "on", this task
displays a '.' for every 100 Kb retrieved. Any URL schema supported by
the runtime is valid here, including http:, ftp: and jar:;
</p>
The <i>usetimestamp</i> option enables you to control downloads so that the remote file is
only fetched if newer than the local copy. If there is no local copy, the download always takes
place. When a file is downloaded, the timestamp of the downloaded file is set to the remote timestamp.
NB: This timestamp facility only works on downloads using the HTTP protocol.
<p>
A username and password can be specified, in which case basic 'slightly encoded
plain text' authentication is used. This is only secure over an HTTPS link.
</p>
<p><b>Proxies</b>. Since Apache Ant 1.7.0, Ant running on Java1.5 or later can
<a href="../proxy.html">use the proxy settings of the operating
system</a> if enabled with the
<code>-autoproxy</code> option. There is also the
<a href="../Tasks/setproxy.html"><setproxy></a> task
for earlier Java versions. With proxies turned
on, <code><get></code> requests against localhost may not work
as expected, if the request is relayed to the proxy.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">src</td>
<td valign="top">the URL from which to retrieve a file.</td>
<td align="center" valign="top">Yes or a nested resource collection</td>
</tr>
<tr>
<td valign="top">dest</td>
<td valign="top">the file or directory where to store the
retrieved file(s).</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">verbose</td>
<td valign="top">show verbose progress information ("on"/"off").</td>
<td align="center" valign="top">No; default "false"</td>
</tr>
<tr>
<td valign="top">quiet</td>
<td valign="top">Log errors only.("true"/"false").</td>
<td align="center" valign="top">No; default "false"</td>
</tr>
<tr>
<td valign="top">ignoreerrors</td>
<td valign="top">Log errors but don't treat as fatal.</td>
<td align="center" valign="top">No; default "false"</td>
</tr>
<tr>
<td valign="top">usetimestamp</td>
<td valign="top">conditionally download a file based on the timestamp of the
local copy. HTTP only</td>
<td align="center" valign="top">No; default "false"</td>
</tr>
<tr>
<td valign="top">username</td>
<td valign="top">username for 'BASIC' http authentication</td>
<td align="center" valign="top">if password is set</td>
</tr>
<tr>
<td valign="top">password</td>
<td valign="top">password: required </td>
<td align="center" valign="top">if username is set</td>
</tr>
<tr>
<td valign="top">maxtime</td>
<td valign="top">Maximum time in seconds a single download may take,
otherwise it will be interrupted and treated like a download
error. <em>Since Ant 1.8.0</em></td>
<td align="center" valign="top">No: default 0 which means no
maximum time</td>
</tr>
<tr>
<td valign="top">retries</td>
<td valign="top">the per download number of retries on error<br/>
<em>since Ant 1.8.0</em></td>
<td align="center" valign="top">No; default "3"</td>
</tr>
<tr>
<td valign="top">skipexisting</td>
<td valign="top">skip files that already exist on the local filesystem<br/>
<em>since Ant 1.8.0</em></td>
<td align="center" valign="top">No; default "false"</td>
</tr>
<tr>
<td valign="top">httpusecaches</td>
<td valign="top">HTTP only - if true, allow caching at the
HttpUrlConnection level. if false, turn caching off.<br/>
<b>Note</b> this is only a hint to the underlying UrlConnection
class, implementations and proxies are free to ignore the
setting.</td>
<td align="center" valign="top">No; default "true"</td>
</tr>
<tr>
<td valign="top">useragent</td>
<td valign="top">User-Agent HTTP header to send, starting with Ant
1.9.3 Ant will specify a User-Agent header of "Apache Ant VERSION"
unless overridden by this attribute<br/>
<em>since Ant 1.9.3</em></td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">tryGzipEncoding</td>
<td valign="top">When set to true Ant will tell the server it is
willing to accept gzip encoding to reduce the amount of data to
transfer and uncompress the content transparently.<br/>
Setting this to true also means Ant will uncompress
<code>.tar.gz</code> and similar files automatically.<br/>
<em>since Ant 1.9.5</em></td>
<td align="center" valign="top">No; default "false"</td>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>any resource collection</h4>
<p><a href="../Types/resources.html#collection">Resource
Collection</a>s are used to select groups of URLs to download. If
the collection contains more than one resource, the dest attribute
must point to a directory if it exists or a directory will be
created if it doesn't exist. The destination file name use the
last part of the path of the source URL unless you also specify a
mapper.</p>
<h4>mapper</h4>
<p>You can define name transformations by using a
nested <a href="../Types/mapper.html">mapper</a> element. You
can also use any filenamemapper type in place of the mapper
element.</p>
<p>The mapper will receive the resource's name as argument. Any
resource for which the mapper returns no or more than one mapped
name will be skipped. If the returned name is a relative path, it
will be considered relative to the <em>dest</em> attribute.</p>
<h3>Examples</h3>
<pre> <get src="http://ant.apache.org/" dest="help/index.html"/></pre>
<p>Gets the index page of http://ant.apache.org/, and stores it in the file <code>help/index.html</code>.</p>
<pre> <get src="http://www.apache.org/dist/ant/KEYS"
dest="KEYS"
verbose="true"
usetimestamp="true"/></pre>
<p>
Gets the PGP keys of Ant's (current and past) release managers, if the local copy
is missing or out of date. Uses the verbose option
for progress information.
</p>
<pre> <get src="https://insecure-bank.org/statement/user=1214"
dest="statement.html"
username="1214";
password="secret"/></pre>
<p>
Fetches some file from a server with access control. Because https is being used the
fact that basic auth sends passwords in plaintext is moot if you
ignore the fact that it is part of your build file which may be
readable by third parties. If you need more security, consider using
the <a href="input.html">input task</a> to query for a password.</p>
<p>Using a macro like the following</p>
<pre>
<macrodef name="get-and-checksum">
<attribute name="url"/>
<attribute name="dest"/>
<sequential>
<local name="destdir"/>
<dirname property="destdir" file="@{dest}"/>
<get dest="${destdir}">
<url url="@{url}"/>
<url url="@{url}.sha1"/>
<firstmatchmapper>
<globmapper from="@{url}.sha1" to="@{dest}.sha"/>
<globmapper from="@{url}" to="@{dest}"/>
</firstmatchmapper>
</get>
<local name="checksum.matches"/>
<local name="checksum.matches.fail"/>
<checksum file="@{dest}" algorithm="sha" fileext=".sha"
verifyproperty="checksum.matches"/>
<condition property="checksum.matches.fail">
<equals arg1="${checksum.matches}" arg2="false"/>
</condition>
<fail if="checksum.matches.fail">Checksum error</fail>
</sequential>
</macrodef>
</pre>
<p>it is possible to download an artifacts together with its SHA1
checksum (assuming a certain naming convention for the checksum
file, of course) and validate the checksum on the fly.</p>
<pre>
<get dest="downloads">
<url url="http://ant.apache.org/index.html"/>
<url url="http://ant.apache.org/faq.html"/>
</get>
</pre>
<p>Gets the index and FAQ pages of http://ant.apache.org/, and stores
them in the directory <code>downloads</code> which will be created if
necessary.</p>
</body>
</html>
|
