Common functionality to the core tasks tasks is:
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.
|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.
|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
Set failonerror to false for this to be of use.
|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.
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.
|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|
Specifies an arbitrary HTTP request header that will be sent with the request.
|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|
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.
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.
<httpget url="http://jakarta.apache.org/" destFile="help/index.html"/>
Fetches the index page of http://jakarta.apache.org/, and stores it in the
<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)
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.
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.
|uploadFile||a file to upload. when specified, all parameters are ignored.||
|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.||
<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)