Skip to content

Commit 125451d

Browse files
chingor13chingor13
authored
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
1 parent 0e6d451 commit 125451d

14 files changed

+943
-5
lines changed

‎.gitignore

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,5 @@ nosetests.xml
2727
**/.classpath
2828
**/.checkstyle
2929

30-
# Built documentation
31-
docs/
32-
3330
# Python utilities
3431
*.pyc

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ might result, and you are not guaranteed a compilation error.
4040

4141
## Documentation
4242

43-
- [Developer's Guide](https://github.com/googleapis/google-http-java-client/wiki)
44-
- [Setup Instructions](https://github.com/googleapis/google-http-java-client/wiki/Setup-Instructions)
43+
- [Developer's Guide](https://googleapis.github.io/google-http-java-client/)
44+
- [Setup Instructions](https://googleapis.github.io/google-http-java-client/setup.html)
4545
- [JavaDoc](https://googleapis.dev/java/google-http-client/latest/)
4646
- [Release Notes](https://github.com/googleapis/google-http-java-client/releases)
4747
- [Support (Questions, Bugs)](https://developers.google.com/api-client-library/java/google-http-java-client/support)

‎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: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
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: JSON
13+
url: json.html
14+
- page: Exponential Backoff
15+
url: exponential-backoff.html
16+
- page: Unit Testing
17+
url: unit-testing.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: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: Using the Google HTTP Client Library for Java on Android
3+
---
4+
5+
# Using the Google HTTP Client Library for Java on Android
6+
7+
If you are developing for Android and the Google API you want to use is included in the
8+
[Google Play Services library](https://developer.android.com/google/play-services/index.html), use
9+
that library for the best performance and experience. If the Google API you want to use with Android
10+
is not part of the Google Play Services library, you can use the Google HTTP Client Library for
11+
Java, which supports Android 1.5 (or higher), and which is described here.
12+
13+
## Beta
14+
15+
Android support for the Google HTTP Client Library for Java is `@Beta`.
16+
17+
## Installation
18+
19+
Follow the download instructions on the [setup][setup] page, and pay special attention to the
20+
Android instructions for [ProGuard][proguard]. Using ProGuard or a similar tool to remove unused
21+
code and compress it is critical for minimizing application size. For example, for the
22+
[tasks-android-sample][tasks-android-sample], ProGuard reduces the application size ~88%, from
23+
777KB to 93KB.
24+
25+
Note that ProGuard only runs when preparing your application for release; it does not run when
26+
preparing it for debugging, to make it easier to develop. However, be sure to test your application
27+
in release mode, because if ProGuard is misconfigured it can cause problems that are sometimes a
28+
challenge to debug.
29+
30+
**Warning:** For Android, you MUST place the jar files in a directory named "libs" so that the APK
31+
packager can find them. Otherwise, you will get a `NoClassDefFoundError` error at runtime.
32+
33+
## Data models
34+
35+
### JSON
36+
37+
You have a choice of three [pluggable streaming JSON libraries][json]. Options include
38+
[`JacksonFactory`][jackson-factory] for maximum efficiency, or
39+
[`AndroidJsonFactory`][android-json-factory] for the smallest application size on Honeycomb
40+
(SDK 3.0) or higher.
41+
42+
### XML (`@Beta`)
43+
44+
The [XML data model][xml] (`@Beta`) is optimized for efficient memory usage that minimizes parsing
45+
and serialization time. Only the fields you need are actually parsed when processing an XML
46+
response.
47+
48+
Android already has an efficient, native, built-in XML full parser implementation, so no separate
49+
library is needed or advised.
50+
51+
## Authentication
52+
53+
The best practice on Android (since the 2.1 SDK) is to use the [`AccountManager`][account-manager]
54+
class (@Beta) for centralized identity management and credential token storage. We recommend against
55+
using your own solution for storing user identities and credentials.
56+
57+
For details about using the AccountManager with the HTTP service that you need, read the
58+
documentation for that service.
59+
60+
## HTTP transport
61+
62+
If your application is targeted at Android 2.3 (Gingerbread) or higher, use the
63+
[`NetHttpTransport`][net-http-transport] class. This class isbased on `HttpURLConnection`, which is
64+
built into the Android SDK and is found in all Java SDKs.
65+
66+
In prior Android SDKs, however, the implementation of `HttpURLConnection` was buggy, and the Apache
67+
HTTP client was preferred. For those SDKs, use the [`ApacheHttpTransport`][apache-http-transport]
68+
class.
69+
70+
If your Android application needs to work with all Android SDKs, call
71+
[`AndroidHttp.newCompatibleTransport()`][android-transport] (@Beta), and it will decide which of the
72+
two HTTP transport classes to use, based on the Android SDK level.
73+
74+
## Logging
75+
76+
To enable logging of HTTP requests and responses, including URL, headers, and content:
77+
78+
```java
79+
Logger.getLogger(HttpTransport.class.getName()).setLevel(Level.CONFIG);
80+
```
81+
82+
When you use `Level.CONFIG`, the value of the Authorization header is not shown. To show the
83+
Authorization header, use `Level.ALL`.
84+
85+
Furthermore, you must enable logging on your device as follows:
86+
87+
```java
88+
adb shell setprop log.tag.HttpTransport DEBUG
89+
```
90+
91+
[setup]: https://googleapis.github.io/google-http-java-client/setup.html
92+
[proguard]: https://googleapis.github.io/google-http-java-client/setup.html#proguard
93+
[tasks-android-sample]: https://github.com/google/google-api-java-client-samples/tree/master/tasks-android-sample
94+
[json]: https://googleapis.github.io/google-http-java-client/json.html
95+
[jackson-factory]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/jackson2/JacksonFactory.html
96+
[android-json-factory]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/extensions/android/json/AndroidJsonFactory.html
97+
[xml]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/xml/package-summary.html
98+
[account-manager]: http://developer.android.com/reference/android/accounts/AccountManager.html
99+
[net-http-transport]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/javanet/NetHttpTransport.html
100+
[apache-http-transport]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/apache/ApacheHttpTransport.html
101+
[android-transport]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/extensions/android/http/AndroidHttp.html#newCompatibleTransport--

‎docs/component-modules.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Component Modules
3+
---
4+
5+
# Component Modules
6+
7+
This libraries is composed of several modules:
8+
9+
## google-http-client
10+
11+
Google HTTP Client Library for Java (google-http-client) is designed to be compatible with all
12+
supported Java platforms, including Android.
13+
14+
## google-http-client-android
15+
16+
Android extensions to the Google HTTP Client Library for Java (`google-http-client-android`) support
17+
Java Google Android (only for SDK >= 2.1) applications. This module depends on `google-http-client`.
18+
19+
## google-http-client-apache-v2
20+
21+
Apache extension to the Google HTTP Client Library for Java (`google-http-client-apache-v2`) that
22+
contains an implementation of `HttpTransport` based on the Apache HTTP Client. This module depends
23+
on `google-http-client`.
24+
25+
## google-http-client-appengine
26+
27+
Google App Engine extensions to the Google HTTP Client Library for Java
28+
(`google-http-client-appengine`) support Java Google App Engine applications. This module depends on
29+
`google-http-client`.
30+
31+
## google-http-client-gson
32+
33+
GSON extension to the Google HTTP Client Library for Java (`google-http-client-gson`) that contains
34+
an implementation of `JsonFactory` based on the GSON API. This module depends on google-http-client.
35+
36+
## google-http-client-jackson2
37+
38+
Jackson2 extension to the Google HTTP Client Library for Java (`google-http-client-jackson2`) that
39+
contains an implementation of `JsonFactory` based on the Jackson2 API. This module depends on
40+
`google-http-client`.
41+
42+
## google-http-client-protobuf
43+
44+
[Protocol buffer][protobuf] extensions to theGoogle HTTP Client Library for Java
45+
(`google-http-client-protobuf`) support protobuf data format. This module depends on `google-http-client`.
46+
47+
## google-http-client-xml
48+
49+
XML extensions to the Google HTTP Client Library for Java (`google-http-client-xml`) support the XML
50+
data format. This module depends on `google-http-client`.
51+
52+
[protobuf]: https://developers.google.com/protocol-buffers/docs/overview

‎docs/exponential-backoff.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: Exponential Backoff
3+
---
4+
5+
# Exponential Backoff
6+
7+
Exponential backoff is an algorithm that retries requests to the server based on certain status
8+
codes in the server response. The retries exponentially increase the waiting time up to a certain
9+
threshold. The idea is that if the server is down temporarily, it is not overwhelmed with requests
10+
hitting at the same time when it comes back up.
11+
12+
The exponential backoff feature of the Google HTTP Client Library for Java provides an easy way to
13+
retry on transient failures:
14+
15+
* Provide an instance of [`HttpUnsuccessfulResponseHandler`][http-unsuccessful-response-handler] to
16+
the HTTP request in question.
17+
* Use the library's [`HttpBackOffUnsuccessfulResponseHandler`][http-backoff-handler] implementation
18+
to handle abnormal HTTP responses with some kind of [`BackOff`][backoff] policy.
19+
* Use [`ExponentialBackOff`][exponential-backoff] for this backoff policy.
20+
21+
Backoff is turned off by default in [`HttpRequest`][http-request]. The examples below demonstrate
22+
how to turn it on.
23+
24+
## Examples
25+
26+
To set [`HttpRequest`][http-request] to use
27+
[`HttpBackOffUnsuccessfulResponseHandler`][http-backoff-handler] with default values:
28+
29+
```java
30+
HttpRequest request = ...
31+
request.setUnsuccessfulResponseHandler(new HttpBackOffUnsuccessfulResponseHandler(new ExponentialBackOff()));
32+
// HttpBackOffUnsuccessfulResponseHandler is designed to work with only one HttpRequest at a time.
33+
// As a result, you MUST create a new instance of HttpBackOffUnsuccessfulResponseHandler with a new
34+
// instance of BackOff for each instance of HttpRequest.
35+
HttpResponse = request.execute();
36+
```
37+
38+
To alter the detailed parameters of [`ExponentialBackOff`][exponential-backoff], use its
39+
[`Builder`][exponential-backoff-builder] methods:
40+
41+
```java
42+
ExponentialBackOff backoff = new ExponentialBackOff.Builder()
43+
.setInitialIntervalMillis(500)
44+
.setMaxElapsedTimeMillis(900000)
45+
.setMaxIntervalMillis(6000)
46+
.setMultiplier(1.5)
47+
.setRandomizationFactor(0.5)
48+
.build();
49+
request.setUnsuccessfulResponseHandler(new HttpBackOffUnsuccessfulResponseHandler(backoff));
50+
```
51+
52+
To create your own implementation of [`BackOff`][backoff]:
53+
54+
```java
55+
class CustomBackOff implements BackOff {
56+
57+
@Override
58+
public long nextBackOffMillis() throws IOException {
59+
...
60+
}
61+
62+
@Override
63+
public void reset() throws IOException {
64+
...
65+
}
66+
}
67+
68+
request.setUnsuccessfulResponseHandler(
69+
new HttpBackOffUnsuccessfulResponseHandler(new CustomBackOff()));
70+
```
71+
72+
73+
[http-unsuccessful-response-handler]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpUnsuccessfulResponseHandler.html
74+
[http-backoff-handler]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpBackOffUnsuccessfulResponseHandler.html
75+
[backoff]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/BackOff.html
76+
[exponential-backoff]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/ExponentialBackOff.html
77+
[http-request]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/http/HttpRequest.html
78+
[exponential-backoff-builder]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/util/ExponentialBackOff.Builder.html

‎docs/google-app-engine.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Using the Google HTTP Client Library for Java on Google App Engine
3+
---
4+
5+
# Using the Google HTTP Client Library for Java on Google App Engine
6+
7+
Google App Engine is one of the supported Java environments for the Google HTTP Client Library for Java.
8+
9+
## Data models
10+
11+
### JSON
12+
13+
The [JSON data model][json-package] is optimized for efficient memory usage that minimizes parsing
14+
and serialization time. Only the fields you need are actually parsed when processing a JSON
15+
response.
16+
17+
For your JSON parser, we recommend [`JacksonFactory`][jackson-factory], which is based on the
18+
popular Jackson library. It is considered the fastest in terms of parsing/serialization. You can
19+
also use [`GsonFactory'][gson-factory], which is based on the [Google GSON][gson] library. It is a
20+
lighter-weight option (smaller size) that is fairly fast, but it is not quite as fast as Jackson.
21+
22+
### XML (@Beta)
23+
24+
The [XML datamodel][xml-package] (`@Beta`) is optimized for efficient memory usage that minimizes
25+
parsing and serialization time. Only the fields you need are actually parsed when processing an XML
26+
response.
27+
28+
## HTTP transport
29+
30+
If you have configured Google App Engine to use [`urlfetch` as the stream handler][url-fetch], then
31+
you will use the [`UrlFetchTransport`][url-fetch-transport] provided by
32+
`google-http-client-appengine`.
33+
34+
If you are not using `urlfetch`, then you can use any of the provided
35+
[HttpTransport][http-transport] adapters.
36+
37+
[json-package]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/package-summary.html
38+
[jackson-factory]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/jackson2/JacksonFactory.html
39+
[gson-factory]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/json/gson/GsonFactory.html
40+
[gson]: https://github.com/google/gson
41+
[xml-package]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/xml/package-summary.html
42+
[url-fetch]: https://cloud.google.com/appengine/docs/standard/java/issue-requests#using_urlfetch_in_a_java_8_app
43+
[url-fetch-transport]: https://googleapis.dev/java/google-http-client/latest/index.html?com/google/api/client/extensions/appengine/http/UrlFetchTransport.html
44+
[http-transport]: https://googleapis.github.io/google-http-java-client/http-transport.html

0 commit comments

Comments
 (0)