HTTPBuilder Overview

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.

Features

  • Builder and parser support for XML, JSON, and HTML
  • Built-in support for GZIP and Deflate content-encoding
  • Built-in support for HTTP Basic, Digest, and SSL certificate authentication
  • Status code based response handling
  • Convenience methods for GET and POST
  • AsyncHTTPBuilder for asynchronous requests
  • Easily extensible API

Components

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.

Requirements

  • At least Java 1.5. This is because HttpClient 4 requires Java 5. If you need Java 1.4, let me know.
  • Groovy 1.5 or later, although it should work with earlier versions
  • JAR dependencies can be found in the packaged distributions linked from the download page .