Get Task

Get

Description

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:, https:, ftp: and jar:.

The usetimestamp 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. Note: This timestamp facility only works on downloads using the HTTP protocol.

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.

Proxies. Since Apache Ant 1.7.0, Ant running on Java 5 or later can use the proxy settings of the operating system if enabled with the -autoproxy command line option. There is also the <setproxy> task for earlier Java versions. With proxies turned on, <get> requests against localhost may not work as expected, if the request is relayed to the proxy.

Parameters

Attribute	Description	Required
src	the URL from which to retrieve a file.	Yes, or a nested resource collection
dest	the file or directory where to store the retrieved file(s).	Yes
verbose	show verbose progress information (on\|off).	No; default is off
quiet	Log errors only.(true\|false).	No; default is false
ignoreerrors	Log errors but don't treat as fatal.	No; default is false
usetimestamp	conditionally download a file based on the timestamp of the local copy. HTTP only	No; default is false
username	username for basic HTTP authentication	Yes, if `password` is set
password	password for basic HTTP authentication	Yes if `username` is set
authenticateOnRedirect	Whether the credentials should also be sent to the new location when a redirect is followed. since Ant 1.10.13	No; default is false
maxtime	Maximum time in seconds a single download may take, otherwise it will be interrupted and treated like a download error. Since Ant 1.8.0	No; default is 0 which means unlimited
retries	The number of attempts to make for opening the URI. 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. since Ant 1.8.0	No; default is 3
skipexisting	skip files that already exist on the local filesystem since Ant 1.8.0	No; default is false
httpusecaches	HTTP only—if true, allow caching at the `HttpUrlConnection` level, if false, turn caching off. Note this is only a hint to the underlying `UrlConnection` class, implementations and proxies are free to ignore the setting.	No; default is true
useragent	`User-Agent` HTTP header to send. since Ant 1.9.3	No; defaults to Apache Ant VERSION
tryGzipEncoding	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. Setting this to true also means Ant will uncompress `.tar.gz` and similar files automatically. since Ant 1.9.5	No; default is false

Parameters specified as nested elements

any resource collection

resource collections 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.

mapper

You can define name transformations by using a nested mapper element. You can also use any filenamemapper type in place of the mapper element.

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 dest attribute.

header

Any arbitrary number of HTTP headers can be added to a request.
The attributes of a nested <header/> node are as follows:

Attribute	Description	Required
name	The name or key of this header. Cannot be null or empty. Leading and trailing spaces are removed	Yes
value	The value to assign to the header. Cannot be null or empty. Leading and trailing spaces are removed	Yes

Examples

Get the index page of https://ant.apache.org/, and store it in the file help/index.html.

<get src="https://ant.apache.org/" dest="help/index.html"/>

Get the PGP keys of Ant's (current and past) release managers, if the local copy is missing or out of date. Use the verbose option for progress information.

<get src="https://www.apache.org/dist/ant/KEYS"
     dest="KEYS"
     verbose="true"
     usetimestamp="true"/>

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 input task to query for a password.

<get src="https://insecure-bank.org/statement/user=1214"
     dest="statement.html"
     username="1214"
     password="secret"/>

Using a macro like the following

<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>

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.

<get dest="downloads">
  <url url="https://ant.apache.org/index.html"/>
  <url url="https://ant.apache.org/faq.html"/>
</get>

Using custom HTTP headers

<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>

get the index and FAQ pages of https://ant.apache.org/, and store them in the directory downloads which will be created if necessary.