HTTPBuilder Overview

HTTPBuilder is the easiest way to manipulate HTTP-based resources from the JVM.

In a nutshell, HTTPBuilder is a wrapper for Apache's HttpClient, with some (actually, a lot of) Groovy syntactical sugar thrown on top. The request/response model is also inspired by Prototype.js' Ajax.Request.

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 ) {
  uri.path = '/ajax/services/search/web'
  uri.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.status

    // 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.status} : ${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 web downloads.

Features

Components

HTTPBuilder is the main API class which is used to make requests and parse responses. AsyncHTTPBuilder is a subclass of the base HTTPBuilder which transparently delegates all requests to a thread pool for execution. RESTClient extends HTTPBuilder to eliminate the closure definition, to make REST operations particularly easy. Finally, HttpURLClient provides most of HTTPBuilder's intelligent handling in a package that can be used from Google App Engine.

URIBuilder provides a fluent interface for manipulating complex URLs. It is also used internally by HTTPBuilder to handle path and query string modification.

See the JavaDoc for full documentation.

Requirements

  • At least Java 1.5. This is because HttpClient 4 requires Java 5.
  • 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.

Support

If you are having trouble, start here.

The best place to ask for help would be the Groovy-User mailing list. If you do not want to subscribe to the mailing list, you can also post questions through Nabble. See the About page for additional contact information.

Please report any problems or errors to the mailing list (or JIRA) and it should be resolved quickly.