| <!DOCTYPE html> |
| <!-- |
| 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 |
| |
| https://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 lang="en"> |
| |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>Get Task</title> |
| </head> |
| |
| <body> |
| |
| <h2 id="get">Get</h2> |
| <h3>Description</h3> |
| <p>Gets files from URLs. When the <var>verbose</var> option is <q>on</q>, this task displays |
| a <q>.</q> for every 100 Kb retrieved. Any URL schema supported by the runtime is valid here, |
| including <q>http:</q>, <q>https:</q>, <q>ftp:</q> and <q>jar:</q>.</p> |
| <p>The <var>usetimestamp</var> 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. <strong>Note</strong>: This timestamp facility only works on downloads using the HTTP |
| protocol.</p> |
| <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><strong>Proxies</strong>. <em>Since Apache Ant 1.7.0</em>, Ant running on Java 5 or later |
| can <a href="../proxy.html">use the proxy settings of the operating system</a> if enabled with |
| the <kbd>-autoproxy</kbd> command line 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 class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>src</td> |
| <td>the URL from which to retrieve a file.</td> |
| <td>Yes, or a nested resource collection</td> |
| </tr> |
| <tr> |
| <td>dest</td> |
| <td>the file or directory where to store the retrieved file(s).</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>verbose</td> |
| <td>show verbose progress information (<q>on|off</q>).</td> |
| <td>No; default is <q>off</q></td> |
| </tr> |
| <tr> |
| <td>quiet</td> |
| <td>Log errors only.(<q>true|false</q>).</td> |
| <td>No; default is <q>false</q></td> |
| </tr> |
| <tr> |
| <td>ignoreerrors</td> |
| <td>Log errors but don't treat as fatal.</td> |
| <td>No; default is <q>false</q></td> |
| </tr> |
| <tr> |
| <td>usetimestamp</td> |
| <td>conditionally download a file based on the timestamp of the local copy. HTTP only</td> |
| <td>No; default is <q>false</q></td> |
| </tr> |
| <tr> |
| <td>username</td> |
| <td>username for basic HTTP authentication</td> |
| <td>Yes, if <var>password</var> is set</td> |
| </tr> |
| <tr> |
| <td>password</td> |
| <td>password for basic HTTP authentication</td> |
| <td>Yes if <var>username</var> is set</td> |
| </tr> |
| <tr> |
| <td>maxtime</td> |
| <td>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>No; default is <q>0</q> which means |
| unlimited</td> |
| </tr> |
| <tr> |
| <td>retries</td> |
| <td>The number of attempts to make for opening the URI.<br/>The name of the attribute is |
| misleading as a value of <q>1</q> means "don't retry on error" and a value of <q>0</q> meant |
| don't even try to reach the URI at all.<br/><em>since Ant 1.8.0</em></td> |
| <td>No; default is <q>3</q></td> |
| </tr> |
| <tr> |
| <td>skipexisting</td> |
| <td>skip files that already exist on the local filesystem<br/><em>since Ant 1.8.0</em></td> |
| <td>No; default is <q>false</q></td> |
| </tr> |
| <tr> |
| <td>httpusecaches</td> |
| <td>HTTP only—if <q>true</q>, allow caching at the <code>HttpUrlConnection</code> level, |
| if <q>false</q>, turn caching off.<br/><strong>Note</strong> this is only a hint to the |
| underlying <code>UrlConnection</code> class, implementations and proxies are free to ignore the |
| setting.</td> |
| <td>No; default is <q>true</q></td> |
| </tr> |
| <tr> |
| <td>useragent</td> |
| <td><code>User-Agent</code> HTTP header to send.<br/><em>since Ant 1.9.3</em></td> |
| <td>No; defaults to <q>Apache Ant VERSION</q></td> |
| </tr> |
| <tr> |
| <td>tryGzipEncoding</td> |
| <td>When set to <q>true</q>, 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 <q>true</q> also means Ant will uncompress <code>.tar.gz</code> and similar files |
| automatically.<br/><em>since Ant 1.9.5</em></td> |
| <td>No; default is <q>false</q></td> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>any resource collection</h4> |
| |
| <p><a href="../Types/resources.html#collection">resource collections</a> are used to select groups |
| of URLs to download. If the collection contains more than one resource, the <var>dest</var> |
| 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 <var>dest</var> attribute.</p> |
| |
| <h4>header</h4> |
| <p>Any arbitrary number of HTTP headers can be added to a request.<br/>The attributes of a |
| nested <code><header/></code> node are as follows:</p> |
| |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>The name or key of this header. Cannot be null or empty. Leading and trailing spaces are |
| removed</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>value</td> |
| <td>The value to assign to the header. Cannot be null or empty. Leading and trailing spaces are |
| removed</td> |
| <td>Yes</td> |
| </tr> |
| </table> |
| |
| <h3>Examples</h3> |
| |
| <p>Get the index page of <samp>https://ant.apache.org/</samp>, and store it in the |
| file <samp>help/index.html</samp>.</p> |
| <pre><get src="https://ant.apache.org/" dest="help/index.html"/></pre> |
| |
| <p>Get the PGP keys of Ant's (current and past) release managers, if the local copy is missing or |
| out of date. Use the <var>verbose</var> option for progress information.</p> |
| <pre> |
| <get src="https://www.apache.org/dist/ant/KEYS" |
| dest="KEYS" |
| verbose="true" |
| usetimestamp="true"/></pre> |
| |
| <p>Fetch 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</a> task to query for a password.</p> |
| <pre> |
| <get src="https://insecure-bank.org/statement/user=1214" |
| dest="statement.html" |
| username="1214" |
| password="secret"/></pre> |
| |
| <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="https://ant.apache.org/index.html"/> |
| <url url="https://ant.apache.org/faq.html"/> |
| </get></pre> |
| |
| <p>Using custom HTTP headers</p> |
| |
| <pre> |
| <get src="https://ant.apache.org/index.html" dest="downloads"> |
| <header name="header1" value="headerValue1"/> |
| <header name="header2" value="headerValue2"/> |
| <header name="header3" value="headerValue3"/> |
| </get></pre> |
| |
| <p>get the index and FAQ pages of <samp>https://ant.apache.org/</samp>, and store them in the |
| directory <samp>downloads</samp> which will be created if necessary.</p> |
| </body> |
| </html> |