HTTPBuilder is basically a wrapper for Apache's HttpClient , with some Groovy syntactical sugar thrown on top. The request/response model is also inspired partially by Prototype.js' Ajax.Request .
Note that at the current point in time, HTTPBuilder should be considered beta quality. There are significant pieces of code that remain largely untested, so please use at your own risk. That being said, please report any problems or errors to the mailing list (or JIRA ) and it should be resolved quickly.
In short, HTTPBuilder allows you to make HTTP requests like this:
def http = new HTTPBuilder( 'http://ajax.googleapis.com' ) // perform a GET request, expecting JSON response data http.request( GET, JSON ) { url.path = '/ajax/services/search/web' url.query = [ v:'1.0', q: 'Calvin and Hobbes' ] headers.'User-Agent' = 'Mozilla/5.0 Ubuntu/8.10 Firefox/3.0.4' // response handler for a success response code: response.success = { resp, json -> println resp.statusLine // parse the JSON response object: json.responseData.results.each { println " ${it.titleNoFormatting} : ${it.visibleUrl}" } } // handler for any failure status code: response.failure = { resp -> println "Unexpected error: ${resp.statusLine.statusCode} : ${resp.statusLine.reasonPhrase}" } }
But it actually goes much further to handle common tasks such as building and parsing common content-types, handling common content-encodings, and built-in support for common authentication mechanisms. It works equally as well for simple REST-based requests, or ad-hoc HTTP queries.
HTTPBuilder is the main API class which is used to make requests and parse responses. URIBuilder is also a convenient class for manipulating complex URLs. It is also used internally by HTTPBuilder to handle path and query string modification. AsyncHTTPBuilder is a subclass of the base HTTPBuilder which transparently delegates all requests to a thread pool for execution.
See the JavaDoc for full documentation.