docs: migrate docs into source control from the wiki

googleapis · chingor13 · Aug 30, 2019 · Aug 30, 2019 · Aug 30, 2019 · Aug 30, 2019
commit f31046efb6e0d376d356edcff8353b9c992cef42
diff --git a/.gitignore b/.gitignore
@@ -27,8 +27,5 @@ nosetests.xml
 **/.classpath
 **/.checkstyle
 
-# 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,17 @@
+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: JSON
+    url: json.html
+  - page: Exponential Backoff
+    url: exponential-backoff.html
+  - page: Unit Testing
+    url: unit-testing.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,61 @@
+---
+title: Using the Google HTTP Client Library for Java on Android
+---
+
+# Using the Google HTTP Client Library for Java on Android
+
+If you are developing for Android and the Google API you want to use is included in the [Google Play Services library](https://developer.android.com/google/play-services/index.html), use that library for the best performance and experience. If the Google API you want to use with Android is not part of the Google Play Services library, you can use the Google HTTP Client Library for Java, which supports Android 1.5 (or higher), and which is described here.
+
+## Beta
+
+Android support for the Google HTTP Client Library for Java is `@Beta`.
+
+## Installation
+
+Follow the download instructions on the [setup](https://developers.google.com/api-client-library/java/google-http-java-client/setup) page, and pay special attention to the Android instructions for [ProGuard](https://developers.google.com/api-client-library/java/google-http-java-client/setup#proguard). Using ProGuard or a similar tool to remove unused code and compress it is critical for minimizing application size. For example, for the [tasks-android-sample](https://github.com/google/google-api-java-client-samples/tree/master/tasks-android-sample), ProGuard reduces the application size ~88%, from 777KB to 93KB.
+
+Note that ProGuard only runs when preparing your application for release; it does not run when preparing it for debugging, to make it easier to develop. However, be sure to test your application in release mode, because if ProGuard is misconfigured it can cause problems that are sometimes a challenge to debug.
+
+**Warning:** For Android, you MUST place the jar files in a directory named "libs" so that the APK packager can find them. Otherwise, you will get a `NoClassDefFoundError` error at runtime.
+
+## Data models
+
+### JSON
+
+You have a choice of three [pluggable streaming JSON libraries](https://github.com/googleapis/google-http-java-client/wiki/JSON). Options include [`JacksonFactory`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/jackson2/JacksonFactory.html) for maximum efficiency, or [`AndroidJsonFactory`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/extensions/android/json/AndroidJsonFactory.html) for the smallest application size on Honeycomb (SDK 3.0) or higher.
+
+### XML (`@Beta`)
+
+The [XML data model](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/xml/package-summary.html) (`@Beta`) is optimized for efficient memory usage that minimizes parsing and serialization time. Only the fields you need are actually parsed when processing an XML response.
+
+Android already has an efficient, native, built-in XML full parser implementation, so no separate library is needed or advised.
+
+## Authentication
+
+The best practice on Android (since the 2.1 SDK) is to use the [`AccountManager`](http://developer.android.com/reference/android/accounts/AccountManager.html) class (@Beta) for centralized identity management and credential token storage. We recommend against using your own solution for storing user identities and credentials.
+
+For details about using the AccountManager with the HTTP service that you need, read the documentation for that service.
+
+## HTTP transport
+
+If your application is targeted at Android 2.3 (Gingerbread) or higher, use the [`NetHttpTransport`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/javanet/NetHttpTransport.html) class. This class isbased on `HttpURLConnection`, which is built into the Android SDK and is found in all Java SDKs.
+
+In prior Android SDKs, however, the implementation of `HttpURLConnection` was buggy, and the Apache HTTP client was preferred. For those SDKs, use the [`ApacheHttpTransport`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/apache/ApacheHttpTransport.html) class.
+
+If your Android application needs to work with all Android SDKs, call [`AndroidHttp.newCompatibleTransport()`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/extensions/android/http/AndroidHttp.html#newCompatibleTransport--) (@Beta), and it will decide which of the two HTTP transport classes to use, based on the Android SDK level.
+
+## Logging
+
+To enable logging of HTTP requests and responses, including URL, headers, and content:
+
+```java
+Logger.getLogger(HttpTransport.class.getName()).setLevel(Level.CONFIG);
+```
+
+When you use `Level.CONFIG`, the value of the Authorization header is not shown. To show the Authorization header, use `Level.ALL`.
+
+Furthermore, you must enable logging on your device as follows:
+
+```java
+adb shell setprop log.tag.HttpTransport DEBUG
+```
diff --git a/docs/component-modules.md b/docs/component-modules.md
@@ -0,0 +1,40 @@
+---
+title: Component Modules
+---
+
+# Component Modules
+
+This libraries is composed of several modules:
+
+## google-http-client
+
+Google HTTP Client Library for Java (google-http-client) is designed to be compatible with all supported Java platforms, including Android.
+
+## google-http-client-android
+
+Android extensions to the Google HTTP Client Library for Java (`google-http-client-android`) support Java Google Android (only for SDK >= 2.1) applications. This module depends on `google-http-client`.
+
+## google-http-client-apache-v2
+
+Apache extension to the Google HTTP Client Library for Java (`google-http-client-apache-v2`) that contains an
+implementation of `HttpTransport` based on the Apache HTTP Client. This module depends on `google-http-client`.
+
+## google-http-client-appengine
+
+Google App Engine extensions to the Google HTTP Client Library for Java (`google-http-client-appengine`) support Java Google App Engine applications. This module depends on `google-http-client`.
+
+## google-http-client-gson
+
+GSON extension to the Google HTTP Client Library for Java (`google-http-client-gson`) that contains an implementation of `JsonFactory` based on the GSON API. This module depends on google-http-client.
+
+## google-http-client-jackson2
+
+Jackson2 extension to the Google HTTP Client Library for Java (`google-http-client-jackson2`) that contains an implementation of `JsonFactory` based on the Jackson2 API. This module depends on `google-http-client`.
+
+## google-http-client-protobuf
+
+[Protocol buffer](https://developers.google.com/protocol-buffers/docs/overview) extensions to the Google HTTP Client Library for Java (`google-http-client-protobuf`) support protobuf data format. This module depends on `google-http-client`.
+
+## google-http-client-xml
+
+XML extensions to the Google HTTP Client Library for Java (`google-http-client-xml`) support the XML data format. This module depends on `google-http-client`.
diff --git a/docs/exponential-backoff.md b/docs/exponential-backoff.md
@@ -0,0 +1,61 @@
+---
+title: Exponential Backoff
+---
+
+# Exponential Backoff
+
+Exponential backoff is an algorithm that retries requests to the server based on certain status codes in the server response. The retries exponentially increase the waiting time up to a certain threshold. The idea is that if the server is down temporarily, it is not overwhelmed with requests hitting at the same time when it comes back up.
+
+The exponential backoff feature of the Google HTTP Client Library for Java provides an easy way to retry on transient failures:
+
+* Provide an instance of [`HttpUnsuccessfulResponseHandler`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpUnsuccessfulResponseHandler.html) to the HTTP request in question.
+* Use the library's [`HttpBackOffUnsuccessfulResponseHandler`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpBackOffUnsuccessfulResponseHandler.html) implementation to handle abnormal HTTP responses with some kind of [`BackOff`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/BackOff.html) policy.
+* Use [`ExponentialBackOff`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/ExponentialBackOff.html) for this backoff policy.
+
+Backoff is turned off by default in [`HttpRequest`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpRequest.html). The examples below demonstrate how to turn it on.
+
+## Examples
+
+To set [`HttpRequest`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpRequest.html) to use [`HttpBackOffUnsuccessfulResponseHandler`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpBackOffUnsuccessfulResponseHandler.html) with default values:
+
+```java
+HttpRequest request = ...
+request.setUnsuccessfulResponseHandler(new HttpBackOffUnsuccessfulResponseHandler(new ExponentialBackOff()));
+// HttpBackOffUnsuccessfulResponseHandler is designed to work with only one HttpRequest at a time.
+// As a result, you MUST create a new instance of HttpBackOffUnsuccessfulResponseHandler with a new
+// instance of BackOff for each instance of HttpRequest.
+HttpResponse = request.execute();
+```
+
+To alter the detailed parameters of [`ExponentialBackOff`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/ExponentialBackOff.html), use its [`Builder`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/ExponentialBackOff.Builder.html) methods:
+
+```java
+ExponentialBackOff backoff = new ExponentialBackOff.Builder()
+    .setInitialIntervalMillis(500)
+    .setMaxElapsedTimeMillis(900000)
+    .setMaxIntervalMillis(6000)
+    .setMultiplier(1.5)
+    .setRandomizationFactor(0.5)
+    .build();
+request.setUnsuccessfulResponseHandler(new HttpBackOffUnsuccessfulResponseHandler(backoff));
+```
+
+To create your own implementation of [`BackOff`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/BackOff.html):
+
+```java
+class CustomBackOff implements BackOff {
+
+  @Override
+  public long nextBackOffMillis() throws IOException {
+    ...
+  }
+
+  @Override
+  public void reset() throws IOException {
+    ...
+  }
+}
+
+request.setUnsuccessfulResponseHandler(
+    new HttpBackOffUnsuccessfulResponseHandler(new CustomBackOff()));
+```
diff --git a/docs/google-app-engine.md b/docs/google-app-engine.md
@@ -0,0 +1,25 @@
+---
+title: Using the Google HTTP Client Library for Java on Google App Engine
+---
+
+# Using the Google HTTP Client Library for Java on Google App Engine
+
+Google App Engine is one of the supported Java environments for the Google HTTP Client Library for Java.
+
+## Data models
+
+### JSON
+
+The [JSON data model](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/package-summary.html) is optimized for efficient memory usage that minimizes parsing and serialization time. Only the fields you need are actually parsed when processing a JSON response.
+
+For your JSON parser, we recommend [`JacksonFactory`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/jackson2/JacksonFactory.html), which is based on the popular Jackson library. It is considered the fastest in terms of parsing/serialization. You can also use [`GsonFactory'](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/gson/GsonFactory.html), which is based on the [Google GSON](https://github.com/google/gson) library. It is a lighter-weight option (smaller size) that is fairly fast, but it is not quite as fast as Jackson.
+
+### XML (@Beta)
+
+The [XML datamodel](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/xml/package-summary.html) (`@Beta`) is optimized for efficient memory usage that minimizes parsing and serialization time. Only the fields you need are actually parsed when processing an XML response.
+
+## HTTP transport
+
+If you have configured Google App Engine to use [`urlfetch` as the stream handler](https://cloud.google.com/appengine/docs/standard/java/issue-requests#using_urlfetch_in_a_java_8_app), then you will use the [`UrlFetchTransport`](https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/extensions/appengine/http/UrlFetchTransport.html) provided by `google-http-client-appengine`.
+
+If you are not using `urlfetch`, then you can use any of the provided [HttpTransport](https://github.com/googleapis/google-http-java-client/wiki/HTTP-Transport) adapters.