HTTPBuilder Overview

HTTP Builder - Home

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

• Builder and parser support for XML, JSON, and HTML
• Easy URI manipulation
• Streamlined client for REST interfaces
• Built-in support for GZIP and Deflate content-encoding
• Built-in support for most common authentication schemes
• Status code based response handling
• Convenience methods for GET and POST
• Compatible with Google App Engine
• AsyncHTTPBuilder for asynchronous requests
• Easily extensible API

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 downlo