Http Antlib

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

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.

header

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

Quirky Limitations of java.net classes

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.

   <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)