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)
*
*
*
"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.http.HttpTransport}. For example:
*
*
*
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 JacksonFactory();
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:
*
*
*
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:
*
*
*
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;