docs: migrate docs from wiki (#1399)

* docs: migrate docs from wiki * docs: update README links to gh-pages
googleapis · Oct 22, 2019 · 173adca · 173adca
1 parent d3dcfe9
commit 173adca
Show file tree

Hide file tree

Showing 15 changed files with 1,371 additions and 2 deletions.
diff --git a/.gitignore b/.gitignore
@@ -25,8 +25,6 @@ nosetests.xml
 .DS_Store
 .classpath
 
-# Built documentation
-docs/
 
 # Python utilities
 *.pyc
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,2 @@
+theme: jekyll-theme-dinky
+title: Google HTTP Client for Java
diff --git a/docs/_data/navigation.yml b/docs/_data/navigation.yml
@@ -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
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.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>
diff --git a/docs/android.md b/docs/android.md
@@ -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
diff --git a/docs/batching.md b/docs/batching.md
@@ -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
diff --git a/docs/component-modules.md b/docs/component-modules.md
@@ -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
diff --git a/docs/errors.md b/docs/errors.md
@@ -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
diff --git a/docs/google-app-engine.md b/docs/google-app-engine.md
@@ -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