com.google.api.client.googleapis.json.package-info Maven / Gradle / Ivy
/*
* Copyright 2010 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
* in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
/**
* 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 @{@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 YouTube
* Data API (as specified in YouTube
* Developer's Guide: JSON-C / JavaScript)
*
*
{@code
* "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):
*
*
{@code
* 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:
*
*
{@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 {@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
*/
package com.google.api.client.googleapis.json;