docs: migrate docs into source control from the wiki (#807)

* docs: migrate docs into source control from the wiki * docs: update wiki links to the github pages urls * docs: fix links * docs: fix markdown formatting
googleapis · Aug 30, 2019 · 125451d · 125451d
1 parent 0e6d451
commit 125451d
Show file tree

Hide file tree

Showing 14 changed files with 943 additions and 5 deletions.
diff --git a/.gitignore b/.gitignore
@@ -27,8 +27,5 @@ nosetests.xml
 **/.classpath
 **/.checkstyle
 
-# Built documentation
-docs/
-
 # Python utilities
 *.pyc
diff --git a/README.md b/README.md
@@ -40,8 +40,8 @@ might result, and you are not guaranteed a compilation error.
 
 ## Documentation
 
-- [Developer's Guide](https://github.com/googleapis/google-http-java-client/wiki)
-- [Setup Instructions](https://github.com/googleapis/google-http-java-client/wiki/Setup-Instructions)
+- [Developer's Guide](https://googleapis.github.io/google-http-java-client/)
+- [Setup Instructions](https://googleapis.github.io/google-http-java-client/setup.html)
 - [JavaDoc](https://googleapis.dev/java/google-http-client/latest/)
 - [Release Notes](https://github.com/googleapis/google-http-java-client/releases)
 - [Support (Questions, Bugs)](https://developers.google.com/api-client-library/java/google-http-java-client/support)

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,101 @@
+---
+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][setup] page, and pay special attention to the 
+Android instructions for [ProGuard][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][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][json]. Options include 
+[`JacksonFactory`][jackson-factory] for maximum efficiency, or 
+[`AndroidJsonFactory`][android-json-factory] for the smallest application size on Honeycomb 
+(SDK 3.0) or higher.
+
+### XML (`@Beta`)
+
+The [XML data model][xml] (`@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`][account-manager] 
+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`][net-http-transport] 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`][apache-http-transport] 
+class.
+
+If your Android application needs to work with all Android SDKs, call 
+[`AndroidHttp.newCompatibleTransport()`][android-transport] (@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
+```
+
+[setup]: https://googleapis.github.io/google-http-java-client/setup.html
+[proguard]: https://googleapis.github.io/google-http-java-client/setup.html#proguard
+[tasks-android-sample]: https://github.com/google/google-api-java-client-samples/tree/master/tasks-android-sample
+[json]: https://googleapis.github.io/google-http-java-client/json.html
+[jackson-factory]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/jackson2/JacksonFactory.html
+[android-json-factory]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/extensions/android/json/AndroidJsonFactory.html
+[xml]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/xml/package-summary.html
+[account-manager]: http://developer.android.com/reference/android/accounts/AccountManager.html
+[net-http-transport]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/javanet/NetHttpTransport.html
+[apache-http-transport]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/apache/ApacheHttpTransport.html
+[android-transport]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/extensions/android/http/AndroidHttp.html#newCompatibleTransport--
diff --git a/docs/component-modules.md b/docs/component-modules.md
@@ -0,0 +1,52 @@
+---
+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][protobuf] extensions to theGoogle 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`.
+
+[protobuf]: https://developers.google.com/protocol-buffers/docs/overview
diff --git a/docs/exponential-backoff.md b/docs/exponential-backoff.md
@@ -0,0 +1,78 @@
+---
+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`][http-unsuccessful-response-handler] to
+the HTTP request in question.
+* Use the library's [`HttpBackOffUnsuccessfulResponseHandler`][http-backoff-handler] implementation
+to handle abnormal HTTP responses with some kind of [`BackOff`][backoff] policy.
+* Use [`ExponentialBackOff`][exponential-backoff] for this backoff policy.
+
+Backoff is turned off by default in [`HttpRequest`][http-request]. The examples below demonstrate
+how to turn it on.
+
+## Examples
+
+To set [`HttpRequest`][http-request] to use
+[`HttpBackOffUnsuccessfulResponseHandler`][http-backoff-handler] 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`][exponential-backoff], use its
+[`Builder`][exponential-backoff-builder] 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`][backoff]:
+
+```java
+class CustomBackOff implements BackOff {
+
+  @Override
+  public long nextBackOffMillis() throws IOException {
+    ...
+  }
+
+  @Override
+  public void reset() throws IOException {
+    ...
+  }
+}
+
+request.setUnsuccessfulResponseHandler(
+    new HttpBackOffUnsuccessfulResponseHandler(new CustomBackOff()));
+```
+
+
+[http-unsuccessful-response-handler]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpUnsuccessfulResponseHandler.html
+[http-backoff-handler]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpBackOffUnsuccessfulResponseHandler.html
+[backoff]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/BackOff.html
+[exponential-backoff]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/ExponentialBackOff.html
+[http-request]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpRequest.html
+[exponential-backoff-builder]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/ExponentialBackOff.Builder.html
diff --git a/docs/google-app-engine.md b/docs/google-app-engine.md
@@ -0,0 +1,44 @@
+---
+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][json-package] 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`][jackson-factory], which is based on the
+popular Jackson library. It is considered the fastest in terms of parsing/serialization. You can
+also use [`GsonFactory'][gson-factory], which is based on the [Google GSON][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][xml-package] (`@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][url-fetch], then
+you will use the [`UrlFetchTransport`][url-fetch-transport] provided by
+`google-http-client-appengine`.
+
+If you are not using `urlfetch`, then you can use any of the provided
+[HttpTransport][http-transport] adapters.
+
+[json-package]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/package-summary.html
+[jackson-factory]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/jackson2/JacksonFactory.html
+[gson-factory]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/gson/GsonFactory.html
+[gson]: https://github.com/google/gson
+[xml-package]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/xml/package-summary.html
+[url-fetch]: https://cloud.google.com/appengine/docs/standard/java/issue-requests#using_urlfetch_in_a_java_8_app
+[url-fetch-transport]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/extensions/appengine/http/UrlFetchTransport.html
+[http-transport]: https://googleapis.github.io/google-http-java-client/http-transport.html