Skip to content

Commit 173adca

Browse files
chingor13chingor13
authored
docs: migrate docs from wiki (#1399)
* docs: migrate docs from wiki * docs: update README links to gh-pages
1 parent d3dcfe9 commit 173adca

15 files changed

+1371
-2
lines changed

‎.gitignore

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,6 @@ nosetests.xml
2525
.DS_Store
2626
.classpath
2727

28-
# Built documentation
29-
docs/
3028

3129
# Python utilities
3230
*.pyc

‎docs/_config.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
theme: jekyll-theme-dinky
2+
title: Google HTTP Client for Java

‎docs/_data/navigation.yml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
toc:
2+
- page: Overview
3+
url: index.html
4+
- page: Setup Instructions
5+
url: setup.html
6+
- page: Component Modules
7+
url: component-modules.html
8+
- page: Android
9+
url: android.html
10+
- page: Google App Engine
11+
url: google-app-engine.html
12+
- page: Batching
13+
url: batching.html
14+
- page: Media Download
15+
url: media-download.html
16+
- page: Media Upload
17+
url: media-upload.html
18+
- page: OAuth 2.0
19+
url: oauth-2.0.html
20+
- page: Timeouts and Errors
21+
url: errors.html
22+
- page: Support
23+
url: support.html

‎docs/_layouts/default.html

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
<!doctype html>
2+
<html lang="{{ site.lang | default: "en-US" }}">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta http-equiv="X-UA-Compatible" content="IE=edge">
6+
7+
{% seo %}
8+
<link rel="stylesheet" href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}">
9+
<script src="{{ '/assets/js/scale.fix.js' | relative_url }}"></script>
10+
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
11+
<!--[if lt IE 9]>
12+
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
13+
<![endif]-->
14+
</head>
15+
<body>
16+
<div class="wrapper">
17+
<header>
18+
<h1 class="header">{{ site.title | default: site.github.repository_name }}</h1>
19+
20+
{% for entry in site.data.navigation.toc %}
21+
<a href="{{ entry.url }}">{{ entry.page }}</a><br/>
22+
{% endfor %}
23+
<br/>
24+
25+
<ul>
26+
{% if site.show_downloads %}
27+
<li class="download"><a class="buttons" href="{{ site.github.zip_url }}">Download ZIP</a></li>
28+
<li class="download"><a class="buttons" href="{{ site.github.tar_url }}">Download TAR</a></li>
29+
{% endif %}
30+
<li><a class="buttons github" href="{{ site.github.repository_url }}">View On GitHub</a></li>
31+
</ul>
32+
</header>
33+
34+
<section>
35+
{{ content }}
36+
</section>
37+
38+
<footer>
39+
<p><small>Hosted on <a href="https://pages.github.com">GitHub Pages</a> using the Dinky theme</small></p>
40+
</footer>
41+
</div>
42+
<!--[if !IE]><script>fixScale(document);</script><![endif]-->
43+
{% if site.google_analytics %}
44+
<script>
45+
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
46+
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
47+
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
48+
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
49+
ga('create', '{{ site.google_analytics }}', 'auto');
50+
ga('send', 'pageview');
51+
</script>
52+
{% endif %}
53+
</body>
54+
</html>

‎docs/android.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: Android
3+
---
4+
5+
# Running on [Android (@Beta)](#@Beta)
6+
7+
If you are developing for Android and the Google API you want to use is included
8+
in the [Google Play Services library][play-services], use that library for the
9+
best performance and experience.
10+
11+
To access other Google APIs, use the Google Client Library for Java's
12+
Android-specific helper classes, which are well-integrated with
13+
[Android AccountManager][account-manager].
14+
15+
For example:
16+
17+
```java
18+
@Override
19+
public void onCreate(Bundle savedInstanceState) {
20+
super.onCreate(savedInstanceState);
21+
// Google Accounts
22+
credential =
23+
GoogleAccountCredential.usingOAuth2(this, Collections.singleton(TasksScopes.TASKS));
24+
SharedPreferences settings = getPreferences(Context.MODE_PRIVATE);
25+
credential.setSelectedAccountName(settings.getString(PREF_ACCOUNT_NAME, null));
26+
// Tasks client
27+
service =
28+
new com.google.api.services.tasks.Tasks.Builder(httpTransport, jsonFactory, credential)
29+
.setApplicationName("Google-TasksAndroidSample/1.0").build();
30+
}
31+
```
32+
33+
## Getting started
34+
35+
Begin by reading the [Android development instructions][http-client-android] for
36+
the Google HTTP Client Library for Java.
37+
38+
## Authentication
39+
40+
As described in the [Android development instructions][http-client-android], the
41+
best practice on Android is to use the [`AccountManager`][account-manager] class
42+
(`@Beta`) for centralized identity management and credential token storage.
43+
44+
For information about the OAuth 2.0 flow, see the
45+
[OAuth 2.0 instructions for Android][oauth2-android].
46+
47+
## Partial response and update
48+
49+
Google APIs support a partial-response protocol that allows you to specify which
50+
fields are returned to you in the HTTP response. This can significantly reduce
51+
the size of the response, thereby reducing network usage, parsing response time,
52+
and memory usage. It works with both JSON and XML.
53+
54+
The following snippet of code drawn from the Google+ Sample demonstrates how to
55+
use the partial-response protocol:
56+
57+
58+
```java
59+
Plus.Activities.List listActivities = plus.activities().list("me", "public");
60+
listActivities.setMaxResults(5L);
61+
// Pro tip: Use partial responses to improve response time considerably
62+
listActivities.setFields("nextPageToken,items(id,URL,object/content)");
63+
ActivityFeed feed = listActivities.execute();
64+
```
65+
66+
[play-services]: https://developer.android.com/google/play-services/index.html
67+
[account-manager]: http://developer.android.com/reference/android/accounts/AccountManager.html
68+
[http-client-android]: https://github.com/googleapis/google-http-java-client/wiki/Android
69+
[oauth2-android]: https://github.com/googleapis/google-api-java-client#oauth2-android

‎docs/batching.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Batching
3+
---
4+
5+
# Batching
6+
7+
Each HTTP connection that your client makes results in overhead. To reduce
8+
overhead, you can batch multiple API calls together into a single HTTP request.
9+
10+
The main classes of interest are [BatchRequest][batch-request] and
11+
[JsonBatchCallback][json-batch-callback]. The following example shows how to use
12+
these classes with service-specific generated libraries:
13+
14+
```java
15+
JsonBatchCallback<Calendar> callback = new JsonBatchCallback<Calendar>() {
16+
17+
public void onSuccess(Calendar calendar, HttpHeaders responseHeaders) {
18+
printCalendar(calendar);
19+
addedCalendarsUsingBatch.add(calendar);
20+
}
21+
22+
public void onFailure(GoogleJsonError e, HttpHeaders responseHeaders) {
23+
System.out.println("Error Message: " + e.getMessage());
24+
}
25+
};
26+
27+
...
28+
29+
Calendar client = Calendar.builder(transport, jsonFactory, credential)
30+
.setApplicationName("BatchExample/1.0").build();
31+
BatchRequest batch = client.batch();
32+
33+
Calendar entry1 = new Calendar().setSummary("Calendar for Testing 1");
34+
client.calendars().insert(entry1).queue(batch, callback);
35+
36+
Calendar entry2 = new Calendar().setSummary("Calendar for Testing 2");
37+
client.calendars().insert(entry2).queue(batch, callback);
38+
39+
batch.execute();
40+
```
41+
42+
[batch-request]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/batch/BatchRequest.html
43+
[json-batch-callback]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/batch/json/JsonBatchCallback.html

‎docs/component-modules.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Component Modules
3+
---
4+
5+
# Component Modules
6+
7+
This libraries is composed of several modules:
8+
9+
## google-api-client
10+
11+
The Google API Client Library for Java (`google-api-client`) is designed to be
12+
compatible with all supported Java platforms, including Android.
13+
14+
## google-api-client-android
15+
16+
Extensions to the Google API Client Library for Java
17+
(`google-api-client-android`) support Java Google Android (only for SDK >= 2.1)
18+
applications. This module depends on `google-api-client` and
19+
`google-http-client-android`.
20+
21+
## google-api-client-servlet
22+
23+
Servlet and JDO extensions to the Google API Client Library for Java
24+
(`google-api-client-servlet`) support Java servlet web applications. This module
25+
depends on `google-api-client` and `google-oauth-client-servlet`.
26+
27+
## google-api-client-appengine
28+
29+
Google App Engine extensions to the Google API Client Library for Java
30+
(`google-api-client-appengine`) support Java Google App Engine applications.
31+
This module depends on `google-api-client`, `google-api-client-servlet`,
32+
`google-oauth-client-appengine`, and `google-http-client-appengine`.
33+
34+
## google-api-client-gson
35+
36+
GSON extensions to the Google API Client Library for Java
37+
(`google-api-client-gson`). This module depends on `google-api-client` and
38+
`google-http-client-gson`.
39+
40+
## google-api-client-jackson2
41+
42+
Jackson2 extensions to the Google API Client Library for Java
43+
(`google-api-client-jackson2`). This module depends on `google-api-client` and
44+
`google-http-client-jackson2`.
45+
46+
## google-api-client-java6
47+
48+
Java 6 (and higher) extensions to the Google API Client Library for Java
49+
(`google-api-client-java6`). This module depends on `google-api-client` and
50+
`google-oauth-client-java6`.
51+
52+
## google-api-client-protobuf
53+
54+
[Protocol buffer][protobuf] extensions to the Google API Client Library for Java
55+
(`google-api-client-protobuf`). This module depends on
56+
`google-http-client-protobuf` and `google-api-client`.
57+
58+
## google-api-client-xml
59+
60+
XML extensions to the Google API Client Library for Java
61+
(`google-api-client-xml`). This module depends on `google-api-client` and
62+
`google-http-client-xml`.
63+
64+
[protobuf]: https://developers.google.com/protocol-buffers/docs/overview

‎docs/errors.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Timeout and Errors
3+
---
4+
5+
# Timeout and Errors
6+
7+
## Setting timeouts
8+
9+
In the following example, which uses the
10+
[Google Analytics API][google-analytics-api], the `setConnectTimeout` and
11+
`setReadTimeout` methods are used to set the connect and read timeouts to three
12+
minutes (in milliseconds) for all requests:
13+
14+
```java
15+
private HttpRequestInitializer setHttpTimeout(final HttpRequestInitializer requestInitializer) {
16+
return new HttpRequestInitializer() {
17+
@Override
18+
public void initialize(HttpRequest httpRequest) throws IOException {
19+
requestInitializer.initialize(httpRequest);
20+
httpRequest.setConnectTimeout(3 * 60000); // 3 minutes connect timeout
21+
httpRequest.setReadTimeout(3 * 60000); // 3 minutes read timeout
22+
}
23+
};
24+
25+
GoogleCredential credential = ....
26+
27+
final Analytics analytics = Analytics.builder(new NetHttpTransport(), jsonFactory, setHttpTimeout(credential)).build();
28+
```
29+
30+
## Handling HTTP error responses from Google APIs
31+
32+
When an error status code is detected in an HTTP response to a Google API that
33+
uses the JSON format, the generated libraries throw a
34+
[`GoogleJsonResponseException`][google-json-response-exception].
35+
36+
The errors use the format specified in [Error responses][error-responses].
37+
38+
The following example shows one way that you can handle these exceptions:
39+
40+
```java
41+
Plus.Activities.List listActivities = plus.activities().list("me", "public");
42+
try {
43+
ActivityFeed feed = listActivities.execute();
44+
...
45+
} catch (GoogleJsonResponseException e) {
46+
System.err.println(e.getDetails());
47+
}
48+
```
49+
50+
[google-analytics-api]: https://developers.google.com/analytics/
51+
[google-json-response-exception]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/json/GoogleJsonResponseException.html
52+
[error-responses]: https://developers.google.com/url-shortener/v1/getting_started?csw=1#errors

‎docs/google-app-engine.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Running on Google App Engine
3+
---
4+
5+
# Running on Google App Engine
6+
7+
App Engine-specific helpers make quick work of authenticated calls to APIs, and
8+
you do not need to worry about exchanging code for tokens.
9+
10+
For example:
11+
12+
```java
13+
@Override
14+
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
15+
AppIdentityCredential credential =
16+
new AppIdentityCredential(Arrays.asList(UrlshortenerScopes.URLSHORTENER));
17+
Urlshortener shortener =
18+
new Urlshortener.Builder(new UrlFetchTransport(), new JacksonFactory(), credential)
19+
.build();
20+
UrlHistory history = shortener.URL().list().execute();
21+
...
22+
}
23+
```
24+
25+
## Auth helpers
26+
27+
If you are building a web app that interacts with a user's data via an OAuth
28+
2.0-enabled API, we've created some helpers to assist you with the process. The
29+
helpers aim to:
30+
31+
* Simplify the process of obtaining access tokens
32+
([`AuthorizationCodeFlow`][authorization-code-flow]).
33+
* Manage tokens, after they are obtained, by marking them as
34+
[`PersistenceCapable`][persistence-capable].
35+
* Simplify the process of making authenticated calls using the access token's
36+
[credential][credential].
37+
* Insulate you from the details of authentication when writing servlets.
38+
39+
## Getting started
40+
41+
1. Install the Google API Client Library for Java:
42+
* Follow the [download instructions][setup] and put the library jar files
43+
into your war/WEB-INF/lib directory.
44+
* Alternatively, you can use [Maven][setup].
45+
1. Learn about using [OAuth 2.0 with the authorization code flow for Google App Engine applications][oauth2].
46+
1. Learn about using [OAuth 2.0 with the Google App Engine Identity API][oauth2-gae].
47+
1. Take a look at the [Calendar App Engine sample][calendar-sample]. This sample
48+
combines our Java library and auth helpers to show you how to access end-user
49+
data from within a Google App Engine web app. The sample also uses [GWT][gwt]
50+
for the user interface.
51+
52+
[authorization-code-flow]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html
53+
[persistence-capable]: https://cloud.google.com/appengine/docs/java/datastore/
54+
[credential]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/Credential.html
55+
[setup]: https://github.com/googleapis/google-api-java-client/wiki/Setup
56+
[oauth2]: https://github.com/googleapis/google-api-java-client/wiki/OAuth2
57+
[oauth2-gae]: https://github.com/googleapis/google-api-java-client/wiki/OAuth2#gae
58+
[calendar-sample]: https://github.com/google/google-api-java-client-samples/tree/master/calendar-appengine-sample
59+
[gwt]: http://www.gwtproject.org/gle-http-java-client/http-transport.html

0 commit comments

Comments
 (0)