Package com.google.api.client.googleapis.json

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

See: Description

Class Summary

Class	Description
GoogleJsonError	Data class representing the Google JSON error response content, as documented for example in Error responses.
GoogleJsonError.Details
GoogleJsonError.ErrorInfo	Detailed error information.
GoogleJsonError.ParameterViolations
GoogleJsonErrorContainer	Data class representing a container of GoogleJsonError.

Exception Summary

Exception	Description
GoogleJsonResponseException	Exception thrown when an error status code is detected in an HTTP response to a Google API that uses the JSON format, using the format specified in Error Responses.

Package com.google.api.client.googleapis.json Description

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 @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 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 @Key annotation to defined query parameters for a URL. For example:

 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 {@link 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 {@link com.google.api.client.http.HttpRequest#execute} method will throw an {@link com.google.api.client.http.HttpResponseException}, which has an {@link 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 {@link com.google.api.client.http.HttpRequest#execute()} and parse the returned byte stream.

Since:

1.0

Author:

Yaniv Inbar