Http Antlib

This antlib contains tasks to make the basic HTTP requests: get, post, head, put, with Basicauthentication.

Core Functionality and Parameters

Common functionality to the core tasks tasks is:

  1. Ability to name the remote URL which is 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 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 destFile parameter specifies a destination to which the retrieved page will be written. The optional destProperty parameter specifies a name of a property to save the content to, instead of a property. If neither destFile nor destProperty 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. 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
destfile the file where to store the retrieved file. No
destproperty the name of a property to fill with the returned content. Ignored if destFile is set No
failonerror stop the build if the request failed. default: true No
password the password for authentication. No
status 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 status attribute 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. 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 destFile 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, on Java1.2 and 1.3,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.

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/" destFile="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"
        destFile="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"
         destFile="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 -destFile 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)