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 . In short, it 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 farther 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
  • Fully Extensible

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.

See the JavaDoc for full documentation.