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