## Http Tasks

Tasks do to make the basic HTTP requests: get, post, head, put, with authentication. There is also a task to configure the proxy settings of the http tasks.

These tasks significantly extend the basic get task, but are split off into the optional section so that

1. The core ant file doesn't get so big
2. this implementation can move to using an optional jar (HttpClient) to work around limitations of the HTTP support built in to the Java platform.

### Core Functionality and Parameters

Common functionality to the core tasks tasks is

1. Ability to name the remote url which the target of the request.
2. Ability to name a local file as the local store of any returned content.
3. Ability to name a property as the local store of any returned content.
4. Ability to name a property to be set to "true" when a request succeeds.
5. The option to list a number of parameters, each with a name and a value. Some methods (HttpGet, HttpHead) attach these parameters to the stated url to generate the url to actually fetch. Others (HttpPost) send the parameters up in the standard representation of form data.
6. The option to state the authentication policy and then the username and password. Currently only basic authentication is used, which is utterly insecure except over an https link
7. A 'verbose' option which provides extra information and progess information during a download.
8. Timestamp control, using the usetimestamp flag. When set the timestamp of downloaded content is set to match that of the remote file (Java 1.2 or later only), and the local timestamp of the destination file (if it exists) used to set the if-modified-since header in the request, which will trigger optional download only.

### Parameters

The url parameter specifies the URL to access. The optional dest parameter specifies a destination to which the retrieved page will be written. The optional destinationproperty parameter specifies a name of a property to save the content to, instead of a property. If neither dest nor destinationproperty 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 enabled, the task displays a '.' for every 64 KB retrieved. If the blocksize parameter is adjusted then files are uploaded or downloaded in a different size block from this, and progress markers appear appropriately.

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 authtype, username, and password options enable support for password protected pages. Currently only 'Basic' authentication is used, which is notoriously insecure except over an encrypted https channel.

Attribute | Description | Required
authtype | the HTTP authentication protocol to use, none or basic. | No
blocksize | size (in kilobytes) of the data block used for upload and download. Default: 64. Keep this to a multiple of the hard disk sector size for file IO performance. | No
dest | the file where to store the retrieved file. | No
destinationProperty | the name of a property to fill with the returned content. Ignored if dest is set | No
failonerror | stop the build if the request failed. default: true | No
password | the password for authentication. | No
successProperty | the name of a property to set to "true" if the request succeeds. Set failonerror to false for this to be of use. | No
url | the URL from which to retrieve a file. | Yes
usecaches | boolean to enable 'caching' of content during the fetch process. default:false | No
useresponsecode | boolean to enable success/failure to be determined by result of the received response code. HTTP only. default=true. |
username | the user name for authentication. | No
usetimestamp | boolean flag to conditionally download a file based on the timestamp of the local copy. HTTP only | No
verbose | boolean flag to control progress information display. | No

The successProperty names a property which will be set to "true" if the request was deemed successful. For any non-http protocol, success is defined as the request completing. For http and https, success is defined as the request completing, and the response code from the serving being one of the 'success' values -any number between 200 and 299 inclusive. The usual HTTP_OK (200) is therefore a success, as is HTTP_ACCEPTED (202). But failures such as BAD_REQUEST (400) and the ubiquitous HTTP_NOT_FOUND (404) are most definately errors. So an attempt to access a missing url may result 'failure',even though some content was download (such as, perhaps, the 'file not found' text). If this is not what you desire, then set useresponsecode="false" for the system to interpret any data back as a success.

### Parameters specified as nested elements

param

Specifies an HTTP request parameter to send as part of the request. For get and head 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

Specifies 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

### Quirky Limitations of java.net classes

Multiple HTTP headers can with the same name can not be set, even though the protocol permits it. Java1.1 and Java 1.2 may permit multiple cookies to be set, but this behaviour is explicitly not supported on Java1.3, as someone went and change the code to stop this (Java bug ID #4242254). You need to set multiple cookies in one go and hope the far end can handle it

Bug ID #4160499 covers another issue, to wit: some versions of Java throw exceptions when an error code is greater than 400 and the dest file isn't one of a few simple file types, but Java 1.2 and 1.3 do not. So there is no way to get the error text when a jsp page throws some exception.

Also, although this isnt going to be filed until we have a short test case, but if you recieve a short response with less content than the content-length header promises, the library seems to silently reduce the content length header to match, which seems the wrong action.

## HttpGet

### Description

Accesses a URL to retrieve a file or to cause some action on the server.

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. This task will also retrieve content using other supported protocols, such as ftp: and file:

All the attributes of httptask may be used. Note that a quirk of the implementation of the http client in java makes it impossible to reliably fetch the response details from any unsuccessful request against a URL which doesn't end in '.htm,.html or .txt'. This means that if the task is used to compile jsp pages by issuing request against them, the text details of any errors will not be picked up.

### Examples

      <httpget url="http://jakarta.apache.org/" dest="help/index.html"/>

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

        <httpget src="http://jakarta.apache.org/builds/tomcat/nightly/ant.zip"
            dest="optional.jar"
            verbose="true"
            usetimestamp="true"
    	>
            <header name="Cookie" value="someid=43ff2b"/>
        </httpget>

Retrieves 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. A cookie is supplied for the server's benefit.

        <httpget url="https://www.pizzaservices.com/prices.jsp"
             dest="pizza-prices.xml">
           <param name="zipcode">57340</param>
           <param name="pizza">pepperoni</param>
        </httpget>

Builds a URL by adding parameters ("?zipcode=57340&pizza=pepperoni") to the base URL and then fetches the contents (fictional example)

## HttpHead

The http HEAD request is similar to the normal GET request , except it, by definition, returns no content, just a success code and http headers. Accordingly, the destination properties of the base class -dest and -, destinationpropertyname) are not supported -any attempt to use them will result in a build failure. Note also that the http and https protocols are the only protocols supported.

HttpHead is useful for triggering server side actions, but note that many servers interpret a HEAD very differently from a GET. An HttpGet request with the return data discarded is often a more reliable approach.

Where head can be useful is in testing for the availability and reachability of servers, such as in the following test for apache being reachable, which sets a variable on success:-

        <httphead url="http://www.apache.org/"
        	 failonerror="false"
        	 successproperty="reachable.apache"
        	 />

Note that sometimes a missing file on a mis-configured server still generates a successful '200' response to a GET request -and returns a 'missing' file page, but a HEAD request will reliably pick up the 'missing file' error.

## HttpPost

This implements the POST request. Supplied parameter data is turned into form data and sent as the body of the request, rather than appended to the URL. If a file to upload is specified instead, using uploadFile, the parameter values are ignored. Instead the content type of the file is sent in the header -based on the contentType attribute or what the java runtime thinks the content type is based on the file extension. The file is uploaded.

Like HttpGet, this command can return a content which can downloaded to a file, to a property, or just ignored.

This task adds two new attributes to the base set.

Attribute | Description | Required
uploadFile | a file to upload. when specified, all parameters are ignored. | no
contentType | the type of the content (text/html, text/xml, application/binary, etc). Only of relevance when a file is being uploaded, and still optional in that case. | no

###

       <httppost url="http://www.example.com/servlet/docserver"
               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"/>
       </httppost>

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

        <httppost url="https://www.pizzaservices.com"
             uploadFile="pizza-order.xml"
             contentType="text/xml">

Sends a pre-prepared order for a pizza to a pizza vendor accepting orders using xml-rpc requests. (NB: fictional example)

## SetProxy

This task configures the proxy settings for all http tasks which follow it in the build. That includes the original Get task, but not the telnet and FTP tasks. The proxy settings remain in place until changed or the build finishes, and will also hold for other ant build files invoked and even non-forked java invocations, and even URL resolutions of XML parsers running in the same JVM

Attribute | Description | Required
proxyHost | hostname of a web/ftp proxy server | no
proxyPort | integer; the port of the proxy server | no
socksProxyHost | hostname of a SOCKS4 proxy server | no
socksProxyPort | integer; port number of a SOCKS4 server (default=1080) | no

###

Turn off all proxies

        <setproxy proxyhost="" socksProxyHost="" />

Set web proxy to 'web-proxy:80'; do not make any changes to existing socks settings (if any)

        <setproxy proxyHost="web-proxy" proxyPort="80"/>

Turn on socks

        <setproxy socksProxyHost="socks-server" socksProxyPort="1080"/>

Do nothing

        <setproxy/>

Copyright © 2000,2001 Apache Software Foundation. All rights Reserved.