[PATCH] Many enhancements to Get task

[Matt Humphrey]

The attached file, get.diff, contains the differences between the latest version of Get.java and the version that I modified to add several features. I've also attached an HTML file which contains a modified version of the docs for Get. I'm posting it this way because that's what Nico Seesle requested. I can also post the full source if anyone wants it.

 

The enhancements are:

 

- Can specify whether to use HTTP's GET or POST methods when retrieving the URL.

- Can specify request parameters (to simulate the posting of a form by a browser).

- Can send arbitrary HTTP request headers.

- Support for basic authentication for use with password protected pages (only basic authentication is supported, but the hooks are in there to support other types).

 

Here's an example of using the task to access a server at www.foo.com, passing a request to some servlet asking it to retrieve several pages from a stored book.

 

<get src="" method="post" authtype="basic" username="joe" password="silly">
    <param name="action" value="getdoc"/>
    <param name="ISBN">038550120X</param>
    <param name="pages">19-20</param>
    <header name="Accept-Language" value="en-us"/>
</get>

 

HTTP POST will be used in the request. "action", "ISBN", and "pages" parameters are sent with the request. An HTTP header specifying acceptable languages for the returned contents is also sent. Basic authentication is used with a user name of "joe" and a password of "silly".

get.diff
Description: Binary data

Title: Ant User Manual

Get

Description

Accesses a URL to retrieve a file or to cause some action on the server.  The src parameter specifies the URL to access. The optional dest parameters specifies a destination to which the retrieved page will be written. If dest is not specified, the contents of the specified URL are discarded (this is useful when accessing the URL for the purpose of causing some action on the remote server).

When the verbose option is "on", this task displays a '.' for every 100 Kb retrieved. This task should be preferred above the CVS task when doing automated builds. CVS is significantly slower than loading a compressed archive with http/ftp.

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, if the JVM is Java1.2 or later. NB: This timestamp facility only works on downloads using the HTTP protocol.

The method option enables you to specify whether to use HTTP GET or HTTP POST methods to access the specified URL. You may specify HTTP request parameters for either of these methods. This is useful to simulate the submission of a form by a browser. Request parameters are specified by using nested param tags (see below). You may also specify arbitrary HTTP headers to be sent in the request.

The authtype, username, and password options enable support for password protected pages using Basic authentication.

Parameters

Attribute	Description	Required
src	the URL from which to retrieve a file.	Yes
dest	the file where to store the retrieved file.	No
verbose	show verbose progress information ("on"/"off").	No
ignoreerrors	Log errors but don't treat as fatal.	No
usetimestamp	conditionally download a file based on the timestamp of the local copy. HTTP only	No
method	the HTTP request method, get or post.	No
authtype	the HTTP authentication protocol to use, none or basic.	No
username	the user name for authentication.	No
password	the password for authentication.	No

Parameters specified as nested elements

param

Specifies an HTTP request parameter to send as part of the request. For get request methods the parameters are encoded as part of the URL. For post request methods, the parameters are sent as the POST request data.

Attribute	Description	Required
name	the name of the request property to set.	Yes
value	the value of the request property. You may alternatively specify the value as text between the beginning and ending param tags.	Yes

header

Species an arbitrary HTTP request header that will be sent with the request.

Attribute	Description	Required
name	the name of the HTTP request header	Yes
value	the value of the HTTP request header. You may alternatively specify the value as text between the beginning and ending header tags.	Yes

Examples

  <get src="" dest="help/index.html"/>

Gets the index page of http://jakarta.apache.org/, and stores it in the file help/index.html.

  <get src="" 
	dest="optional.jar" 
	verbose="true"
	usetimestamp="true"/>

Gets the nightly ant build from the tomcat distribution, if the local copy
is missing or out of date. Uses the verbose option 
for progress information.


  <get src="" method="post" authtype="basic" username="joe" password="silly">
    <param name="action" value="getdoc"/>
    <param name="ISBN">038550120X</param>
    <param name="pages">19-20</param>
    <header name="Accept-Language" value="en-us"/>
  </get>
Accesses a server at www.foo.com, passing a request to some servlet asking it
to retrieve several pages from a stored book. An HTTP header specifying
acceptable languages for the returned contents is also sent. Basic
authentication is used with a user name of "joe" and a password of
"silly".