[go: nahoru, domu]
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 4 commits into from
Aug 30, 2019
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f31046e
docs: migrate docs into source control from the wiki
chingor13 Aug 30, 2019
f3110f6
docs: update wiki links to the github pages urls
chingor13 Aug 30, 2019
dcba1c2
docs: fix links
chingor13 Aug 30, 2019
cb07daa
docs: fix markdown formatting
chingor13 Aug 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
docs: fix markdown formatting
  • Loading branch information
@chingor13
chingor13 committed Aug 30, 2019
commit cb07daa9463612d73da25c405c2637f8d0dc218e
30 changes: 21 additions & 9 deletions docs/component-modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,33 +8,45 @@ 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 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`.
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`.
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 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.
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`.
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`.
[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`.
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
37 changes: 27 additions & 10 deletions docs/exponential-backoff.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,27 @@ 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.
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:
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.
* 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`](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.
Backoff is turned off by default in [`HttpRequest`][http-request]. 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:
To set [`HttpRequest`][http-request] to use
[`HttpBackOffUnsuccessfulResponseHandler`][http-backoff-handler] with default values:

```java
HttpRequest request = ...
Expand All @@ -27,7 +35,8 @@ request.setUnsuccessfulResponseHandler(new HttpBackOffUnsuccessfulResponseHandle
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:
To alter the detailed parameters of [`ExponentialBackOff`][exponential-backoff], use its
[`Builder`][exponential-backoff-builder] methods:

```java
ExponentialBackOff backoff = new ExponentialBackOff.Builder()
Expand All @@ -40,7 +49,7 @@ ExponentialBackOff backoff = new ExponentialBackOff.Builder()
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):
To create your own implementation of [`BackOff`][backoff]:

```java
class CustomBackOff implements BackOff {
Expand All @@ -58,4 +67,12 @@ class CustomBackOff implements BackOff {

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
31 changes: 25 additions & 6 deletions docs/google-app-engine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,35 @@ Google App Engine is one of the supported Java environments for the Google HTTP

### 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.
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`](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.
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](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.
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](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.
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
Loading