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

Google's JSON-C as specified in YouTube Developer's Guide: JSON-C / JavaScript (see detailed package specification).

See:
Description

Class Summary

AbstractJsonFeedParser<T>	Abstract base class for a Google JSON-C feed parser when the feed class is known in advance.
DiscoveryDocument	Manages a Google API discovery document based on the JSON format.
DiscoveryDocument.ServiceDefinition	Defines a specific version of an API.
DiscoveryDocument.ServiceMethod	Defines a method of a service resource.
DiscoveryDocument.ServiceParameter	Defines a parameter to a service method.
DiscoveryDocument.ServiceResource	Defines a resource in a service definition.
JsonCContent	Serializes JSON-C content based on the data key/value mapping object for an item, wrapped in a "data" envelope.
JsonContent	Deprecated. (scheduled to be removed in version 1.1) Use JsonCContent
JsonCParser	Parses HTTP JSON-C response content into an data class of key/value pairs, assuming the data is wrapped in a "data" envelope.
JsonFeedParser<T,I>	Google JSON-C feed parser when the item class is known in advance.
JsonHttp	Deprecated. (scheduled to be removed in version 1.1)
JsonMultiKindFeedParser<T>	Google JSON-C feed parser when the item class can be computed from the kind.
JsonParser	Deprecated. (scheduled to be removed in version 1.1) Use JsonCParser

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

Google's JSON-C as specified in YouTube Developer's Guide: JSON-C / JavaScript (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 YouYube Data API:

 "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\u003dhYB0mn5zh2c"
         },
...
        }
    ]
 }

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 GoogleTransport. For example:

  private static GoogleTransport setUpGoogleTransport() throws IOException {
    GoogleTransport transport = new GoogleTransport();
    transport.applicationName = "google-youtubejsoncsample-1.0";
    transport.setVersionHeader(YouTube.VERSION);
    transport.addParser(new JsonParser());
    // insert authentication code...
    return transport;
  }

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

  public static VideoFeed list(GoogleTransport 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 HttpRequest.execute() method will throw an HttpResponseException, which has an HttpResponse field which can be parsed the same way as a success response inside of a catch block. For example:

    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 HttpRequest.execute() and parse the returned byte stream.

This package depends on the com.google.api.client.http, com.google.api.client.json, com.google.api.client.util, and org.codehaus.jackson packages.

Warning: this package is experimental, and its content may be changed in incompatible ways or possibly entirely removed in a future version of the library

Since:

1.0