Skip to content
Permalink
Browse files
docs: migrate docs from wiki (#1399)
* docs: migrate docs from wiki

* docs: update README links to gh-pages
  • Loading branch information
chingor13 committed Oct 22, 2019
1 parent d3dcfe9 commit 173adcaed0d96b3771486ee59d0b4a4cf87df895
Showing with 1,371 additions and 2 deletions.
  1. +0 −2 .gitignore
  2. +2 −0 docs/_config.yml
  3. +23 −0 docs/_data/navigation.yml
  4. +54 −0 docs/_layouts/default.html
  5. +69 −0 docs/android.md
  6. +43 −0 docs/batching.md
  7. +64 −0 docs/component-modules.md
  8. +52 −0 docs/errors.md
  9. +59 −0 docs/google-app-engine.md
  10. +77 −0 docs/index.md
  11. +88 −0 docs/media-download.md
  12. +112 −0 docs/media-upload.md
  13. +582 −0 docs/oauth-2.0.md
  14. +79 −0 docs/setup.md
  15. +67 −0 docs/support.md
@@ -25,8 +25,6 @@ nosetests.xml
.DS_Store
.classpath

# Built documentation
docs/

# Python utilities
*.pyc
@@ -0,0 +1,2 @@
theme: jekyll-theme-dinky
title: Google HTTP Client for Java
@@ -0,0 +1,23 @@
toc:
- page: Overview
url: index.html
- page: Setup Instructions
url: setup.html
- page: Component Modules
url: component-modules.html
- page: Android
url: android.html
- page: Google App Engine
url: google-app-engine.html
- page: Batching
url: batching.html
- page: Media Download
url: media-download.html
- page: Media Upload
url: media-upload.html
- page: OAuth 2.0
url: oauth-2.0.html
- page: Timeouts and Errors
url: errors.html
- page: Support
url: support.html
@@ -0,0 +1,54 @@
<!doctype html>
<html lang="{{ site.lang | default: "en-US" }}">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">

{% seo %}
<link rel="stylesheet" href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}">
<script src="{{ '/assets/js/scale.fix.js' | relative_url }}"></script>
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body>
<div class="wrapper">
<header>
<h1 class="header">{{ site.title | default: site.github.repository_name }}</h1>

{% for entry in site.data.navigation.toc %}
<a href="{{ entry.url }}">{{ entry.page }}</a><br/>
{% endfor %}
<br/>

<ul>
{% if site.show_downloads %}
<li class="download"><a class="buttons" href="{{ site.github.zip_url }}">Download ZIP</a></li>
<li class="download"><a class="buttons" href="{{ site.github.tar_url }}">Download TAR</a></li>
{% endif %}
<li><a class="buttons github" href="{{ site.github.repository_url }}">View On GitHub</a></li>
</ul>
</header>

<section>
{{ content }}
</section>

<footer>
<p><small>Hosted on <a href="https://pages.github.com">GitHub Pages</a> using the Dinky theme</small></p>
</footer>
</div>
<!--[if !IE]><script>fixScale(document);</script><![endif]-->
{% if site.google_analytics %}
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', '{{ site.google_analytics }}', 'auto');
ga('send', 'pageview');
</script>
{% endif %}
</body>
</html>
@@ -0,0 +1,69 @@
---
title: Android
---

# Running on [Android (@Beta)](#@Beta)

If you are developing for Android and the Google API you want to use is included
in the [Google Play Services library][play-services], use that library for the
best performance and experience.

To access other Google APIs, use the Google Client Library for Java's
Android-specific helper classes, which are well-integrated with
[Android AccountManager][account-manager].

For example:

```java
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Google Accounts
credential =
GoogleAccountCredential.usingOAuth2(this, Collections.singleton(TasksScopes.TASKS));
SharedPreferences settings = getPreferences(Context.MODE_PRIVATE);
credential.setSelectedAccountName(settings.getString(PREF_ACCOUNT_NAME, null));
// Tasks client
service =
new com.google.api.services.tasks.Tasks.Builder(httpTransport, jsonFactory, credential)
.setApplicationName("Google-TasksAndroidSample/1.0").build();
}
```

## Getting started

Begin by reading the [Android development instructions][http-client-android] for
the Google HTTP Client Library for Java.

## Authentication

As described in the [Android development instructions][http-client-android], the
best practice on Android is to use the [`AccountManager`][account-manager] class
(`@Beta`) for centralized identity management and credential token storage.

For information about the OAuth 2.0 flow, see the
[OAuth 2.0 instructions for Android][oauth2-android].

## Partial response and update

Google APIs support a partial-response protocol that allows you to specify which
fields are returned to you in the HTTP response. This can significantly reduce
the size of the response, thereby reducing network usage, parsing response time,
and memory usage. It works with both JSON and XML.

The following snippet of code drawn from the Google+ Sample demonstrates how to
use the partial-response protocol:


```java
Plus.Activities.List listActivities = plus.activities().list("me", "public");
listActivities.setMaxResults(5L);
// Pro tip: Use partial responses to improve response time considerably
listActivities.setFields("nextPageToken,items(id,URL,object/content)");
ActivityFeed feed = listActivities.execute();
```

[play-services]: https://developer.android.com/google/play-services/index.html
[account-manager]: http://developer.android.com/reference/android/accounts/AccountManager.html
[http-client-android]: https://github.com/googleapis/google-http-java-client/wiki/Android
[oauth2-android]: https://github.com/googleapis/google-api-java-client#oauth2-android
@@ -0,0 +1,43 @@
---
title: Batching
---

# Batching

Each HTTP connection that your client makes results in overhead. To reduce
overhead, you can batch multiple API calls together into a single HTTP request.

The main classes of interest are [BatchRequest][batch-request] and
[JsonBatchCallback][json-batch-callback]. The following example shows how to use
these classes with service-specific generated libraries:

```java
JsonBatchCallback<Calendar> callback = new JsonBatchCallback<Calendar>() {
public void onSuccess(Calendar calendar, HttpHeaders responseHeaders) {
printCalendar(calendar);
addedCalendarsUsingBatch.add(calendar);
}
public void onFailure(GoogleJsonError e, HttpHeaders responseHeaders) {
System.out.println("Error Message: " + e.getMessage());
}
};
...
Calendar client = Calendar.builder(transport, jsonFactory, credential)
.setApplicationName("BatchExample/1.0").build();
BatchRequest batch = client.batch();
Calendar entry1 = new Calendar().setSummary("Calendar for Testing 1");
client.calendars().insert(entry1).queue(batch, callback);
Calendar entry2 = new Calendar().setSummary("Calendar for Testing 2");
client.calendars().insert(entry2).queue(batch, callback);
batch.execute();
```

[batch-request]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/batch/BatchRequest.html
[json-batch-callback]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/batch/json/JsonBatchCallback.html
@@ -0,0 +1,64 @@
---
title: Component Modules
---

# Component Modules

This libraries is composed of several modules:

## google-api-client

The Google API Client Library for Java (`google-api-client`) is designed to be
compatible with all supported Java platforms, including Android.

## google-api-client-android

Extensions to the Google API Client Library for Java
(`google-api-client-android`) support Java Google Android (only for SDK >= 2.1)
applications. This module depends on `google-api-client` and
`google-http-client-android`.

## google-api-client-servlet

Servlet and JDO extensions to the Google API Client Library for Java
(`google-api-client-servlet`) support Java servlet web applications. This module
depends on `google-api-client` and `google-oauth-client-servlet`.

## google-api-client-appengine

Google App Engine extensions to the Google API Client Library for Java
(`google-api-client-appengine`) support Java Google App Engine applications.
This module depends on `google-api-client`, `google-api-client-servlet`,
`google-oauth-client-appengine`, and `google-http-client-appengine`.

## google-api-client-gson

GSON extensions to the Google API Client Library for Java
(`google-api-client-gson`). This module depends on `google-api-client` and
`google-http-client-gson`.

## google-api-client-jackson2

Jackson2 extensions to the Google API Client Library for Java
(`google-api-client-jackson2`). This module depends on `google-api-client` and
`google-http-client-jackson2`.

## google-api-client-java6

Java 6 (and higher) extensions to the Google API Client Library for Java
(`google-api-client-java6`). This module depends on `google-api-client` and
`google-oauth-client-java6`.

## google-api-client-protobuf

[Protocol buffer][protobuf] extensions to the Google API Client Library for Java
(`google-api-client-protobuf`). This module depends on
`google-http-client-protobuf` and `google-api-client`.

## google-api-client-xml

XML extensions to the Google API Client Library for Java
(`google-api-client-xml`). This module depends on `google-api-client` and
`google-http-client-xml`.

[protobuf]: https://developers.google.com/protocol-buffers/docs/overview
@@ -0,0 +1,52 @@
---
title: Timeout and Errors
---

# Timeout and Errors

## Setting timeouts

In the following example, which uses the
[Google Analytics API][google-analytics-api], the `setConnectTimeout` and
`setReadTimeout` methods are used to set the connect and read timeouts to three
minutes (in milliseconds) for all requests:

```java
private HttpRequestInitializer setHttpTimeout(final HttpRequestInitializer requestInitializer) {
return new HttpRequestInitializer() {
@Override
public void initialize(HttpRequest httpRequest) throws IOException {
requestInitializer.initialize(httpRequest);
httpRequest.setConnectTimeout(3 * 60000); // 3 minutes connect timeout
httpRequest.setReadTimeout(3 * 60000); // 3 minutes read timeout
}
};
GoogleCredential credential = ....
final Analytics analytics = Analytics.builder(new NetHttpTransport(), jsonFactory, setHttpTimeout(credential)).build();
```
## Handling HTTP error responses from Google APIs
When an error status code is detected in an HTTP response to a Google API that
uses the JSON format, the generated libraries throw a
[`GoogleJsonResponseException`][google-json-response-exception].
The errors use the format specified in [Error responses][error-responses].
The following example shows one way that you can handle these exceptions:
```java
Plus.Activities.List listActivities = plus.activities().list("me", "public");
try {
ActivityFeed feed = listActivities.execute();
...
} catch (GoogleJsonResponseException e) {
System.err.println(e.getDetails());
}
```
[google-analytics-api]: https://developers.google.com/analytics/
[google-json-response-exception]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/json/GoogleJsonResponseException.html
[error-responses]: https://developers.google.com/url-shortener/v1/getting_started?csw=1#errors
@@ -0,0 +1,59 @@
---
title: Running on Google App Engine
---

# Running on Google App Engine

App Engine-specific helpers make quick work of authenticated calls to APIs, and
you do not need to worry about exchanging code for tokens.

For example:

```java
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
AppIdentityCredential credential =
new AppIdentityCredential(Arrays.asList(UrlshortenerScopes.URLSHORTENER));
Urlshortener shortener =
new Urlshortener.Builder(new UrlFetchTransport(), new JacksonFactory(), credential)
.build();
UrlHistory history = shortener.URL().list().execute();
...
}
```

## Auth helpers

If you are building a web app that interacts with a user's data via an OAuth
2.0-enabled API, we've created some helpers to assist you with the process. The
helpers aim to:

* Simplify the process of obtaining access tokens
([`AuthorizationCodeFlow`][authorization-code-flow]).
* Manage tokens, after they are obtained, by marking them as
[`PersistenceCapable`][persistence-capable].
* Simplify the process of making authenticated calls using the access token's
[credential][credential].
* Insulate you from the details of authentication when writing servlets.

## Getting started

1. Install the Google API Client Library for Java:
* Follow the [download instructions][setup] and put the library jar files
into your war/WEB-INF/lib directory.
* Alternatively, you can use [Maven][setup].
1. Learn about using [OAuth 2.0 with the authorization code flow for Google App Engine applications][oauth2].
1. Learn about using [OAuth 2.0 with the Google App Engine Identity API][oauth2-gae].
1. Take a look at the [Calendar App Engine sample][calendar-sample]. This sample
combines our Java library and auth helpers to show you how to access end-user
data from within a Google App Engine web app. The sample also uses [GWT][gwt]
for the user interface.

[authorization-code-flow]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html
[persistence-capable]: https://cloud.google.com/appengine/docs/java/datastore/
[credential]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/Credential.html
[setup]: https://github.com/googleapis/google-api-java-client/wiki/Setup
[oauth2]: https://github.com/googleapis/google-api-java-client/wiki/OAuth2
[oauth2-gae]: https://github.com/googleapis/google-api-java-client/wiki/OAuth2#gae
[calendar-sample]: https://github.com/google/google-api-java-client-samples/tree/master/calendar-appengine-sample
[gwt]: http://www.gwtproject.org/gle-http-java-client/http-transport.html

0 comments on commit 173adca

Please sign in to comment.