| <!-- |
| 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>authenticateOnRedirect</td> |
| <td>Whether the credentials should also be sent to the new location when a redirect is followed.<br/> |
| <em>since Ant 1.9.17</em></td> |
| <td>No; default is <q>false</q></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 number of attempts to make for opening the URI.<br/> |
| The name of the attribute is misleading as a value of 1 means |
| "don't retry on error" and a value of 0 meant don't even try to |
| reach the URI at all.<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> |
| |
