You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

get.html 6.9 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180
  1. <!--
  2. Licensed to the Apache Software Foundation (ASF) under one or more
  3. contributor license agreements. See the NOTICE file distributed with
  4. this work for additional information regarding copyright ownership.
  5. The ASF licenses this file to You under the Apache License, Version 2.0
  6. (the "License"); you may not use this file except in compliance with
  7. the License. You may obtain a copy of the License at
  8. http://www.apache.org/licenses/LICENSE-2.0
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. -->
  15. <html>
  16. <head>
  17. <meta http-equiv="Content-Language" content="en-us">
  18. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  19. <title>Get Task</title>
  20. </head>
  21. <body>
  22. <h2><a name="get">Get</a></h2>
  23. <h3>Description</h3>
  24. <p>Gets a file from a URL. When the verbose option is &quot;on&quot;, this task
  25. displays a '.' for every 100 Kb retrieved. Any URL schema supported by
  26. the runtime is valid here, including http:, ftp: and jar:;
  27. https: is only valid if the appropriate support is added to the pre-1.4 Java
  28. runtimes.
  29. </p>
  30. The <i>usetimestamp</i> option enables you to control downloads so that the remote file is
  31. only fetched if newer than the local copy. If there is no local copy, the download always takes
  32. place. When a file is downloaded, the timestamp of the downloaded file is set to the remote timestamp,
  33. if the JVM is Java1.2 or later.
  34. NB: This timestamp facility only works on downloads using the HTTP protocol.
  35. <p>
  36. A username and password can be specified, in which case basic 'slightly encoded
  37. plain text' authentication is used. This is only secure over an HTTPS link.
  38. </p>
  39. <p>
  40. <b>Proxies</b>. Since Ant1.7, Ant running on Java1.5 or later defaults to
  41. <a href="../proxy.html">using
  42. the proxy settings of the operating system</a>. There is also the
  43. <a href="../OptionalTasks/setproxy.html">&lt;setproxy&gt;</a> task for
  44. earlier Java versions. With proxies turned on, <code>&lt;get&gt;</code> requests against
  45. localhost may not work as expected, if the request is relayed to the proxy.
  46. The <code>-noproxy</code> option can be used to turn this feature off.
  47. </p>
  48. <h3>Parameters</h3>
  49. <table border="1" cellpadding="2" cellspacing="0">
  50. <tr>
  51. <td valign="top"><b>Attribute</b></td>
  52. <td valign="top"><b>Description</b></td>
  53. <td align="center" valign="top"><b>Required</b></td>
  54. </tr>
  55. <tr>
  56. <td valign="top">src</td>
  57. <td valign="top">the URL from which to retrieve a file.</td>
  58. <td align="center" valign="top">Yes</td>
  59. </tr>
  60. <tr>
  61. <td valign="top">dest</td>
  62. <td valign="top">the file where to store the retrieved file.</td>
  63. <td align="center" valign="top">Yes</td>
  64. </tr>
  65. <tr>
  66. <td valign="top">verbose</td>
  67. <td valign="top">show verbose progress information (&quot;on&quot;/&quot;off&quot;).</td>
  68. <td align="center" valign="top">No; default "false"</td>
  69. </tr>
  70. <tr>
  71. <td valign="top">ignoreerrors</td>
  72. <td valign="top">Log errors but don't treat as fatal.</td>
  73. <td align="center" valign="top">No; default "false"</td>
  74. </tr>
  75. <tr>
  76. <td valign="top">usetimestamp</td>
  77. <td valign="top">conditionally download a file based on the timestamp of the
  78. local copy. HTTP only</td>
  79. <td align="center" valign="top">No; default "false"</td>
  80. </tr>
  81. <tr>
  82. <td valign="top">username</td>
  83. <td valign="top">username for 'BASIC' http authentication</td>
  84. <td align="center" valign="top">if password is set</td>
  85. </tr>
  86. <tr>
  87. <td valign="top">password</td>
  88. <td valign="top">password: required </td>
  89. <td align="center" valign="top">if username is set</td>
  90. </tr>
  91. <tr>
  92. <td valign="top">maxtime</td>
  93. <td valign="top">Maximum time in seconds the download may take,
  94. otherwise it will be interrupted and treated like a download
  95. error. <em>Since Ant 1.8.0</em></td>
  96. <td align="center" valign="top">No: default 0 which means no
  97. maximum time</td>
  98. </tr>
  99. <tr>
  100. <td valign="top">retries</td>
  101. <td valign="top">the number of retries on error<br/>
  102. <em>since Ant 1.8.0</em></td>
  103. <td align="center" valign="top">No; default "3"</td>
  104. </tr>
  105. <tr>
  106. <td valign="top">skipexisting</td>
  107. <td valign="top">skip files that already exist on the local filesystem<br/>
  108. <em>since Ant 1.8.0</em></td>
  109. <td align="center" valign="top">No; default "false"</td>
  110. </tr>
  111. <tr>
  112. <td valign="top">httpusecaches</td>
  113. <td valign="top">HTTP only - if true, allow caching at the
  114. HttpUrlConnection level. if false, turn caching off.<br/>
  115. <b>Note</b> this is only a hint to the underlying UrlConnection
  116. class, implementations and proxies are free to ignore the
  117. setting.</td>
  118. <td align="center" valign="top">No; default "true"</td>
  119. </tr>
  120. </table>
  121. <h3>Examples</h3>
  122. <pre> &lt;get src=&quot;http://ant.apache.org/&quot; dest=&quot;help/index.html&quot;/&gt;</pre>
  123. <p>Gets the index page of http://ant.apache.org/, and stores it in the file <code>help/index.html</code>.</p>
  124. <pre> &lt;get src=&quot;http://www.apache.org/dist/ant/KEYS&quot;
  125. dest=&quot;KEYS&quot;
  126. verbose=&quot;true&quot;
  127. usetimestamp=&quot;true&quot;/&gt;</pre>
  128. <p>
  129. Gets the PGP keys of Ant's (current and past) release managers, if the local copy
  130. is missing or out of date. Uses the verbose option
  131. for progress information.
  132. </p>
  133. <pre> &lt;get src=&quot;https://insecure-bank.org/statement/user=1214&quot;
  134. dest=&quot;statement.html&quot;
  135. username="1214";
  136. password="secret"/&gt;</pre>
  137. <p>
  138. Fetches some file from a server with access control. Because https is being used the
  139. fact that basic auth sends passwords in plaintext is moot if you
  140. ignore the fact that it is part of your build file which may be
  141. readable by third parties. If you need more security, consider using
  142. the <a href="input.html">input task</a> to query for a password.</p>
  143. <p>Using a macro like the following</p>
  144. <pre>
  145. &lt;macrodef name="get-and-checksum">
  146. &lt;attribute name="url"/>
  147. &lt;attribute name="dest"/>
  148. &lt;sequential>
  149. &lt;get src="@{url}" dest="@{dest}"/>
  150. &lt;get src="@{url}.sha1" dest="@{dest}.sha"/>
  151. &lt;local name="checksum.matches"/>
  152. &lt;local name="checksum.matches.fail"/>
  153. &lt;checksum file="@{dest}" algorithm="sha" fileext=".sha"
  154. verifyproperty="checksum.matches"/>
  155. &lt;condition property="checksum.matches.fail">
  156. &lt;equals arg1="${checksum.matches}" arg2="false"/>
  157. &lt;/condition>
  158. &lt;fail if="checksum.matches.fail">Checksum error&lt;/fail>
  159. &lt;/sequential>
  160. &lt;/macrodef>
  161. </pre>
  162. <p>it is possible to download an artifacts together with its SHA1
  163. checksum (assuming a certain naming convention for the checksum
  164. file, of course) and validate the checksum on the fly.</p>
  165. </body>
  166. </html>