Package com.google.api.client.googleapis.json (2.6.0)

Google's JSON support (see detailed package specification).

Package Specification

User-defined Partial JSON data models allow you to defined Plain Old Java Objects (POJO's) to define how the library should parse/serialize JSON. Each field that should be included must have an @com.google.api.client.util.Key annotation. The field can be of any visibility (private, package private, protected, or public) and must not be static. By default, the field name is used as the JSON key. To override this behavior, simply specify the JSON key use the optional value parameter of the annotation, for example @Key("name"). Any unrecognized keys from the JSON are normally simply ignored and not stored. If the ability to store unknown keys is important, use com.google.api.client.json.GenericJson.

Let's take a look at a typical partial JSON-C video feed from the YouTube Data API (as specified in YouTube Developer's Guide: JSON-C / JavaScript)

 "data":{
  "updated":"2010-01-07T19:58:42.949Z",
                  "totalItems":800,
                  "startIndex":1,
                  "itemsPerPage":1,
                  "items":[
                          {"id":"hYB0mn5zh2c",
                                  "updated":"2010-01-07T13:26:50.000Z",
                                  "title":"Google Developers Day US - Maps API Introduction",
                                  "description":"Google Maps API Introduction ...",
                                  "tags":[
                                          "GDD07","GDD07US","Maps"],
                              "player":{
                              "default":"http://www.youtube.com/watch?v=hYB0mn5zh2c" },
                              ...
                          }]}
 

Here's one possible way to design the Java data classes for this (each class in its own Java file):

 import com.google.api.client.util.*;
 import java.util.List;

 public class VideoFeed {
   @Key public int itemsPerPage;
   @Key public int startIndex;
   @Key public int totalItems;
   @Key public DateTime updated;
   @Key public List<Video> items;
 }

 public class Video {
   @Key public String id;
   @Key public String title;
   @Key public DateTime updated;
   @Key public String description;
   @Key public List<String> tags;
   @Key public Player player;
 }

 public class Player {
   // "default" is a Java keyword, so need to specify the JSON key manually
   @Key("default")
   public String defaultUrl;
 }
 

You can also use the @com.google.api.client.util.Key annotation to defined query parameters for a URL. For example:

{@code public class YouTubeUrl extends GoogleUrl {

@Key public String author;

@Key("max-results") public Integer maxResults;

public YouTubeUrl(String encodedUrl) { super(encodedUrl); this.alt = "jsonc"; } }

To work with the YouTube API, you first need to set up the com.google.api.client.http.HttpTransport. For example:

{@code private static HttpTransport setUpTransport() throws IOException { HttpTransport result = new NetHttpTransport(); GoogleUtils.useMethodOverride(result); HttpHeaders headers = new HttpHeaders(); headers.setApplicationName("Google-YouTubeSample/1.0"); headers.gdataVersion = "2"; JsonCParser parser = new JsonCParser(); parser.jsonFactory = new GsonFactory(); transport.addParser(parser); // insert authentication code... return transport; } }

Now that we have a transport, we can execute a request to the YouTube API and parse the result:

{@code public static VideoFeed list(HttpTransport transport, YouTubeUrl url) throws IOException { HttpRequest request = transport.buildGetRequest(); request.url = url; return request.execute().parseAs(VideoFeed.class); } }

If the server responds with an error the com.google.api.client.http.HttpRequest#execute method will throw an com.google.api.client.http.HttpResponseException, which has an com.google.api.client.http.HttpResponse field which can be parsed the same way as a success response inside of a catch block. For example:

{@code try { ... } catch (HttpResponseException e) { if (e.response.getParser() != null) { Error error = e.response.parseAs(Error.class); // process error response } else { String errorContentString = e.response.parseAsString(); // process error response as string } throw e; } }

NOTE: As you might guess, the library uses reflection to populate the user-defined data model. It's not quite as fast as writing the wire format parsing code yourself can potentially be, but it's a lot easier.

NOTE: If you prefer to use your favorite JSON parsing library instead (there are many of them listed for example on json.org), that's supported as well. Just call com.google.api.client.http.HttpRequest#execute() and parse the returned byte stream.

@since 1.0

@author Yaniv Inbar