com.google.api.client.googleapis.json.package.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of google-api-client Show documentation
Google API Client Library for Java. Supports Java 5 (or higher) desktop (SE) and web (EE), Android, and Google App Engine.
There is a newer version: 1.4.1-beta
Show newest version

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 @{@link
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 {@code @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 {@link com.google.api.client.json.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 @{@link com.google.api.client.util.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.googleapis.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 {@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:


    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.

This package depends on theses packages:

  {@link com.google.api.client.escape}
  {@link com.google.api.client.googleapis}
  {@link com.google.api.client.http}
  {@link com.google.api.client.json}
  {@link com.google.api.client.repackaged.com.google.common.base}
  {@link com.google.api.client.util}


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