diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/get.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/get.html | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/get.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/get.html new file mode 100644 index 00000000..04bc0e4d --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/get.html @@ -0,0 +1,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> + |