Coming from v1.0

FullContact4j 2.0 is a ground-up redesign of the Java interface for FullContact APIs. In terms of practical code, the changes should not be massive -- mostly changing how requests are made. However, the client is now thread-safe and supports asynchronous calls which can allow a large codebase to interact with the client much more elegantly. This page is intended to be a primer- reading the full readme is highly recommended.

Although dependencies have changed dramatically, they have overall been slimmed down. Gson has been replaced with Jackson. See the readme for the full list.

FullContact4j now uses builders for everything. The client and all requests use the builder pattern.

Before, you'd make a FullContact client by invoking it's constructor with an API key. Now, the static factory method withApiKey is used. It has much more options than the old client, including threading specification, base url changing (for use in testing), rate limiting options, and more. Use build() to create the client.

Another large change in the FullContact4j library is it's new thread-safe design. Only one client per api key should be used as the client uses a thread pool to execute requests (even synchronous ones).

The client now reads rate limit headers back from FullContact4j to automatically pace your requests. If the client goes unused for a short period, it will allow bursting behavior, but otherwise it allows you to make requests up to your per-second api key rate limit. This is another reason to use only one client per api key -- otherwise the rate limiting won't do much good as each client will use up to the rate limit.

Making requests has been dramatically simplified. No handlers or individual methods are used to create requests. Call build____Request() from the FullContact client to create a new request builder of that type, allowing you to specify all parameters as you see fit.

client.buildAccountStatsRequest();
client.buildPersonRequest().twitterName("bartlorang").webhookUrl("http://www.mysite.com/api/gotresponse").build();
client.buildNameStatsRequest().givenName("Bart").familyName("Lorang").build();

Once your request has been built, it can be sent with the same method.

client.sendRequest(personRequest);

Asynchronous calls are now supported. Implement the class FCCallback anonymously to do so:

fullContact.sendRequest(locationEnrichmentRequest, new FCCallback() {
  public void success(LocationEnrichmentResponse response) {
    System.out.println("got a response back!");
  }

  public void failure(FullContactException exception) {
    System.out.println("got an error :( ");
  }
});

Error handling is easier as well; any response that isn't 200 or 202 will create a FullContactException. In the case of synchronous requests, these will be thrown; asynchronous requests will pass them to the failure() method.

This should bring you up to speed on the big changes from version 1. Read the readme for the full changes.