From becd99bb675a490670946088e73f9299614758aa Mon Sep 17 00:00:00 2001 From: Yoshi Automation Bot Date: Wed, 9 Oct 2019 15:14:42 -0700 Subject: [PATCH 01/10] chore: update release-please config (#1388) --- .github/release-please.yml | 2 +- synth.metadata | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/release-please.yml b/.github/release-please.yml index 8b1378917..827446828 100644 --- a/.github/release-please.yml +++ b/.github/release-please.yml @@ -1 +1 @@ - +releaseType: java-yoshi diff --git a/synth.metadata b/synth.metadata index fa1ac9d36..2ea9dffd5 100644 --- a/synth.metadata +++ b/synth.metadata @@ -1,5 +1,5 @@ { - "updateTime": "2019-09-19T16:22:15.152063Z", + "updateTime": "2019-10-08T08:05:40.643237Z", "sources": [ { "template": { From d5f9f54c34e5df675c59e8997573d470ca4b4706 Mon Sep 17 00:00:00 2001 From: "release-please[bot]" <55107282+release-please[bot]@users.noreply.github.com> Date: Fri, 11 Oct 2019 09:51:48 -0700 Subject: [PATCH 02/10] chore: release 1.30.5-SNAPSHOT (#1389) * updated versions.txt [ci skip] * updated google-api-client-android/pom.xml [ci skip] * updated google-api-client-appengine/pom.xml [ci skip] * updated google-api-client-assembly/pom.xml [ci skip] * updated google-api-client-bom/pom.xml [ci skip] * updated google-api-client-gson/pom.xml [ci skip] * updated google-api-client-jackson2/pom.xml [ci skip] * updated google-api-client-java6/pom.xml [ci skip] * updated google-api-client-protobuf/pom.xml [ci skip] * updated google-api-client-servlet/pom.xml [ci skip] * updated google-api-client-xml/pom.xml [ci skip] * updated google-api-client/pom.xml [ci skip] * updated pom.xml [ci skip] --- google-api-client-android/pom.xml | 2 +- google-api-client-appengine/pom.xml | 2 +- google-api-client-assembly/pom.xml | 2 +- google-api-client-bom/pom.xml | 22 +++++++++++----------- google-api-client-gson/pom.xml | 2 +- google-api-client-jackson2/pom.xml | 2 +- google-api-client-java6/pom.xml | 2 +- google-api-client-protobuf/pom.xml | 2 +- google-api-client-servlet/pom.xml | 2 +- google-api-client-xml/pom.xml | 2 +- google-api-client/pom.xml | 2 +- pom.xml | 2 +- versions.txt | 2 +- 13 files changed, 23 insertions(+), 23 deletions(-) diff --git a/google-api-client-android/pom.xml b/google-api-client-android/pom.xml index b5db44b4d..47606af40 100644 --- a/google-api-client-android/pom.xml +++ b/google-api-client-android/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml google-api-client-android diff --git a/google-api-client-appengine/pom.xml b/google-api-client-appengine/pom.xml index f1cfc8633..1b857ab30 100644 --- a/google-api-client-appengine/pom.xml +++ b/google-api-client-appengine/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml google-api-client-appengine diff --git a/google-api-client-assembly/pom.xml b/google-api-client-assembly/pom.xml index 131fe2a83..f8d85b193 100644 --- a/google-api-client-assembly/pom.xml +++ b/google-api-client-assembly/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml com.google.api-client diff --git a/google-api-client-bom/pom.xml b/google-api-client-bom/pom.xml index 2d5ae08af..829c346eb 100644 --- a/google-api-client-bom/pom.xml +++ b/google-api-client-bom/pom.xml @@ -3,7 +3,7 @@ 4.0.0 com.google.api-client google-api-client-bom - 1.30.4 + 1.30.5-SNAPSHOT pom Google API Client Library for Java BOM @@ -63,52 +63,52 @@ com.google.api-client google-api-client - 1.30.4 + 1.30.5-SNAPSHOT com.google.api-client google-api-client-android - 1.30.4 + 1.30.5-SNAPSHOT com.google.api-client google-api-client-appengine - 1.30.4 + 1.30.5-SNAPSHOT com.google.api-client google-api-client-assembly - 1.30.4 + 1.30.5-SNAPSHOT com.google.api-client google-api-client-gson - 1.30.4 + 1.30.5-SNAPSHOT com.google.api-client google-api-client-jackson2 - 1.30.4 + 1.30.5-SNAPSHOT com.google.api-client google-api-client-java6 - 1.30.4 + 1.30.5-SNAPSHOT com.google.api-client google-api-client-protobuf - 1.30.4 + 1.30.5-SNAPSHOT com.google.api-client google-api-client-servlet - 1.30.4 + 1.30.5-SNAPSHOT com.google.api-client google-api-client-xml - 1.30.4 + 1.30.5-SNAPSHOT diff --git a/google-api-client-gson/pom.xml b/google-api-client-gson/pom.xml index 6860ac536..636c5c597 100644 --- a/google-api-client-gson/pom.xml +++ b/google-api-client-gson/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml google-api-client-gson diff --git a/google-api-client-jackson2/pom.xml b/google-api-client-jackson2/pom.xml index 11bd72369..36279cda9 100644 --- a/google-api-client-jackson2/pom.xml +++ b/google-api-client-jackson2/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml google-api-client-jackson2 diff --git a/google-api-client-java6/pom.xml b/google-api-client-java6/pom.xml index ec0290ca1..6219dc325 100644 --- a/google-api-client-java6/pom.xml +++ b/google-api-client-java6/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml google-api-client-java6 diff --git a/google-api-client-protobuf/pom.xml b/google-api-client-protobuf/pom.xml index bb31509c9..f45a5d198 100644 --- a/google-api-client-protobuf/pom.xml +++ b/google-api-client-protobuf/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml google-api-client-protobuf diff --git a/google-api-client-servlet/pom.xml b/google-api-client-servlet/pom.xml index 84b40b2bc..60059d02a 100644 --- a/google-api-client-servlet/pom.xml +++ b/google-api-client-servlet/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml google-api-client-servlet diff --git a/google-api-client-xml/pom.xml b/google-api-client-xml/pom.xml index 751eccbcb..130e447bc 100644 --- a/google-api-client-xml/pom.xml +++ b/google-api-client-xml/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml google-api-client-xml diff --git a/google-api-client/pom.xml b/google-api-client/pom.xml index 80f082233..dab63ed67 100644 --- a/google-api-client/pom.xml +++ b/google-api-client/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT ../pom.xml google-api-client diff --git a/pom.xml b/pom.xml index 840e33dc7..78adf5371 100644 --- a/pom.xml +++ b/pom.xml @@ -9,7 +9,7 @@ com.google.api-client google-api-client-parent - 1.30.4 + 1.30.5-SNAPSHOT pom Parent for the Google API Client Library for Java diff --git a/versions.txt b/versions.txt index 9fdbcf822..bd82a17a5 100644 --- a/versions.txt +++ b/versions.txt @@ -1,4 +1,4 @@ # Format: # module:released-version:current-version -google-api-client:1.30.4:1.30.4 +google-api-client:1.30.4:1.30.5-SNAPSHOT From 34d64858d46f418ea9d1b01fee1d204e78ce12b2 Mon Sep 17 00:00:00 2001 From: Yoshi Automation Bot Date: Fri, 11 Oct 2019 09:52:21 -0700 Subject: [PATCH 03/10] chore: update issue template (#1390) --- .github/ISSUE_TEMPLATE/bug_report.md | 4 ++-- synth.metadata | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 033a37caa..f69f0c445 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -10,7 +10,7 @@ Thanks for stopping by to let us know something could be better! Please run down the following list and make sure you've tried the usual "quick fixes": - - Search the issues already opened: https://github.com/googleapis/google-api-client/issues + - Search the issues already opened: https://github.com/googleapis/google-api-java-client/issues - Check for answers on StackOverflow: http://stackoverflow.com/questions/tagged/google-cloud-platform If you are still having issues, please include as much information as possible: @@ -48,4 +48,4 @@ Any relevant stacktrace here. Following these steps guarantees the quickest resolution possible. -Thanks! \ No newline at end of file +Thanks! diff --git a/synth.metadata b/synth.metadata index 2ea9dffd5..ff2bfeada 100644 --- a/synth.metadata +++ b/synth.metadata @@ -1,5 +1,5 @@ { - "updateTime": "2019-10-08T08:05:40.643237Z", + "updateTime": "2019-10-10T08:02:02.518193Z", "sources": [ { "template": { From 56b72fadbf5b91725e42936704a4ca64932ad455 Mon Sep 17 00:00:00 2001 From: Yoshi Automation Bot Date: Thu, 17 Oct 2019 16:00:16 -0700 Subject: [PATCH 04/10] chore: update common templates (#1393) --- .kokoro/build.sh | 2 ++ .kokoro/coerce_logs.sh | 38 +++++++++++++++++++++++++++++++++++ .kokoro/continuous/common.cfg | 1 + .kokoro/nightly/common.cfg | 1 + .kokoro/presubmit/common.cfg | 1 + .kokoro/release/snapshot.sh | 5 ++++- .kokoro/release/stage.sh | 1 + synth.metadata | 2 +- 8 files changed, 49 insertions(+), 2 deletions(-) create mode 100755 .kokoro/coerce_logs.sh diff --git a/.kokoro/build.sh b/.kokoro/build.sh index 2ffb5ef7f..bcd1e410c 100755 --- a/.kokoro/build.sh +++ b/.kokoro/build.sh @@ -39,6 +39,7 @@ case ${JOB_TYPE} in test) mvn test -B bash ${KOKORO_GFILE_DIR}/codecov.sh + bash .kokoro/coerce_logs.sh ;; lint) mvn com.coveo:fmt-maven-plugin:check @@ -48,6 +49,7 @@ javadoc) ;; integration) mvn -B ${INTEGRATION_TEST_ARGS} -DtrimStackTrace=false -fae verify + bash .kokoro/coerce_logs.sh ;; *) ;; diff --git a/.kokoro/coerce_logs.sh b/.kokoro/coerce_logs.sh new file mode 100755 index 000000000..5cf7ba49e --- /dev/null +++ b/.kokoro/coerce_logs.sh @@ -0,0 +1,38 @@ +#!/bin/bash +# Copyright 2019 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# This script finds and moves sponge logs so that they can be found by placer +# and are not flagged as flaky by sponge. + +set -eo pipefail + +## Get the directory of the build script +scriptDir=$(realpath $(dirname "${BASH_SOURCE[0]}")) +## cd to the parent directory, i.e. the root of the git repo +cd ${scriptDir}/.. + +job=$(basename ${KOKORO_JOB_NAME}) + +echo "coercing sponge logs..." +for xml in `find . -name *-sponge_log.xml` +do + echo "processing ${xml}" + class=$(basename ${xml} | cut -d- -f2) + dir=$(dirname ${xml})/${job}/${class} + text=$(dirname ${xml})/${class}-sponge_log.txt + mkdir -p ${dir} + mv ${xml} ${dir}/sponge_log.xml + mv ${text} ${dir}/sponge_log.txt +done diff --git a/.kokoro/continuous/common.cfg b/.kokoro/continuous/common.cfg index 7c562d48d..81ac96db0 100644 --- a/.kokoro/continuous/common.cfg +++ b/.kokoro/continuous/common.cfg @@ -4,6 +4,7 @@ action { define_artifacts { regex: "**/*sponge_log.xml" + regex: "**/*sponge_log.txt" } } diff --git a/.kokoro/nightly/common.cfg b/.kokoro/nightly/common.cfg index 7c562d48d..81ac96db0 100644 --- a/.kokoro/nightly/common.cfg +++ b/.kokoro/nightly/common.cfg @@ -4,6 +4,7 @@ action { define_artifacts { regex: "**/*sponge_log.xml" + regex: "**/*sponge_log.txt" } } diff --git a/.kokoro/presubmit/common.cfg b/.kokoro/presubmit/common.cfg index fd684c7e1..4e28721be 100644 --- a/.kokoro/presubmit/common.cfg +++ b/.kokoro/presubmit/common.cfg @@ -4,6 +4,7 @@ action { define_artifacts { regex: "**/*sponge_log.xml" + regex: "**/*sponge_log.txt" } } diff --git a/.kokoro/release/snapshot.sh b/.kokoro/release/snapshot.sh index bf738c56d..098168a73 100755 --- a/.kokoro/release/snapshot.sh +++ b/.kokoro/release/snapshot.sh @@ -19,6 +19,9 @@ source $(dirname "$0")/common.sh MAVEN_SETTINGS_FILE=$(realpath $(dirname "$0")/../../)/settings.xml pushd $(dirname "$0")/../../ +# ensure we're trying to push a snapshot (no-result returns non-zero exit code) +grep SNAPSHOT versions.txt + setup_environment_secrets create_settings_xml_file "settings.xml" @@ -27,4 +30,4 @@ mvn clean install deploy -B \ -DperformRelease=true \ -Dgpg.executable=gpg \ -Dgpg.passphrase=${GPG_PASSPHRASE} \ - -Dgpg.homedir=${GPG_HOMEDIR} \ No newline at end of file + -Dgpg.homedir=${GPG_HOMEDIR} diff --git a/.kokoro/release/stage.sh b/.kokoro/release/stage.sh index b1b1b01c6..3c482cbc5 100755 --- a/.kokoro/release/stage.sh +++ b/.kokoro/release/stage.sh @@ -28,6 +28,7 @@ create_settings_xml_file "settings.xml" mvn clean install deploy -B \ --settings ${MAVEN_SETTINGS_FILE} \ + -DskipTests=true \ -DperformRelease=true \ -Dgpg.executable=gpg \ -Dgpg.passphrase=${GPG_PASSPHRASE} \ diff --git a/synth.metadata b/synth.metadata index ff2bfeada..027418699 100644 --- a/synth.metadata +++ b/synth.metadata @@ -1,5 +1,5 @@ { - "updateTime": "2019-10-10T08:02:02.518193Z", + "updateTime": "2019-10-17T20:26:06.515366Z", "sources": [ { "template": { From 420d9da51d91904b5f4538f358c38e30f49bbb8b Mon Sep 17 00:00:00 2001 From: Yoshi Automation Bot Date: Mon, 21 Oct 2019 08:05:08 -0700 Subject: [PATCH 05/10] build: split clirr into separate check (#1394) --- .kokoro/build.sh | 8 ++++++-- .kokoro/presubmit/clirr.cfg | 13 +++++++++++++ synth.metadata | 4 ++-- 3 files changed, 21 insertions(+), 4 deletions(-) create mode 100644 .kokoro/presubmit/clirr.cfg diff --git a/.kokoro/build.sh b/.kokoro/build.sh index bcd1e410c..fa132f410 100755 --- a/.kokoro/build.sh +++ b/.kokoro/build.sh @@ -26,6 +26,7 @@ echo ${JOB_TYPE} mvn install -B -V \ -DskipTests=true \ + -Dclirr.skip=true \ -Dmaven.javadoc.skip=true \ -Dgcloud.download.skip=true \ -T 1C @@ -37,7 +38,7 @@ fi case ${JOB_TYPE} in test) - mvn test -B + mvn test -B -Dclirr.skip=true bash ${KOKORO_GFILE_DIR}/codecov.sh bash .kokoro/coerce_logs.sh ;; @@ -48,9 +49,12 @@ javadoc) mvn javadoc:javadoc javadoc:test-javadoc ;; integration) - mvn -B ${INTEGRATION_TEST_ARGS} -DtrimStackTrace=false -fae verify + mvn -B ${INTEGRATION_TEST_ARGS} -DtrimStackTrace=false -Dclirr.skip=true -fae verify bash .kokoro/coerce_logs.sh ;; +clirr) + mvn -B clirr:check + ;; *) ;; esac \ No newline at end of file diff --git a/.kokoro/presubmit/clirr.cfg b/.kokoro/presubmit/clirr.cfg new file mode 100644 index 000000000..ec572442e --- /dev/null +++ b/.kokoro/presubmit/clirr.cfg @@ -0,0 +1,13 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +# Configure the docker image for kokoro-trampoline. + +env_vars: { + key: "TRAMPOLINE_IMAGE" + value: "gcr.io/cloud-devrel-kokoro-resources/java8" +} + +env_vars: { + key: "JOB_TYPE" + value: "clirr" +} \ No newline at end of file diff --git a/synth.metadata b/synth.metadata index 027418699..4ce7899c2 100644 --- a/synth.metadata +++ b/synth.metadata @@ -1,11 +1,11 @@ { - "updateTime": "2019-10-17T20:26:06.515366Z", + "updateTime": "2019-10-19T07:50:20.310494Z", "sources": [ { "template": { "name": "java_library", "origin": "synthtool.gcp", - "version": "2019.5.2" + "version": "2019.10.17" } } ] From 1ffdba6071d716d9843fada802c3cb4d2dcaedf7 Mon Sep 17 00:00:00 2001 From: Alex Saveau Date: Mon, 21 Oct 2019 16:26:48 -0700 Subject: [PATCH 06/10] fix: add details to GoogleJsonResponseExceptions created with GoogleJsonResponseExceptionFactoryTesting (#1395) * Add details to GoogleJsonResponseExceptions created with GoogleJsonResponseExceptionFactoryTesting * Add import --- .../json/GoogleJsonResponseExceptionFactoryTesting.java | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/google-api-client/src/main/java/com/google/api/client/googleapis/testing/json/GoogleJsonResponseExceptionFactoryTesting.java b/google-api-client/src/main/java/com/google/api/client/googleapis/testing/json/GoogleJsonResponseExceptionFactoryTesting.java index 5afaaedb1..4ee29091e 100644 --- a/google-api-client/src/main/java/com/google/api/client/googleapis/testing/json/GoogleJsonResponseExceptionFactoryTesting.java +++ b/google-api-client/src/main/java/com/google/api/client/googleapis/testing/json/GoogleJsonResponseExceptionFactoryTesting.java @@ -17,6 +17,7 @@ import com.google.api.client.googleapis.json.GoogleJsonResponseException; import com.google.api.client.http.HttpRequest; import com.google.api.client.http.HttpResponse; +import com.google.api.client.json.Json; import com.google.api.client.json.JsonFactory; import com.google.api.client.testing.http.HttpTesting; import com.google.api.client.testing.http.MockHttpTransport; @@ -59,7 +60,10 @@ public static GoogleJsonResponseException newMock(JsonFactory jsonFactory, MockLowLevelHttpResponse otherServiceUnavaiableLowLevelResponse = new MockLowLevelHttpResponse() .setStatusCode(httpCode) - .setReasonPhrase(reasonPhrase); + .setReasonPhrase(reasonPhrase) + .setContentType(Json.MEDIA_TYPE) + .setContent("{ \"error\": { \"errors\": [ { \"reason\": \"" + reasonPhrase + "\" } ], " + + "\"code\": " + httpCode + " } }"); MockHttpTransport otherTransport = new MockHttpTransport.Builder() .setLowLevelHttpResponse(otherServiceUnavaiableLowLevelResponse) .build(); From d3dcfe9c049f72207b30e75f073b4b8ccc14c46d Mon Sep 17 00:00:00 2001 From: Erik Date: Mon, 21 Oct 2019 19:28:02 -0400 Subject: [PATCH 07/10] fix: specify Metadata-Flavor for metadata requests (#1397) --- .../google/api/client/googleapis/auth/oauth2/OAuth2Utils.java | 1 + 1 file changed, 1 insertion(+) diff --git a/google-api-client/src/main/java/com/google/api/client/googleapis/auth/oauth2/OAuth2Utils.java b/google-api-client/src/main/java/com/google/api/client/googleapis/auth/oauth2/OAuth2Utils.java index ecf9f19ab..8c9c5afac 100644 --- a/google-api-client/src/main/java/com/google/api/client/googleapis/auth/oauth2/OAuth2Utils.java +++ b/google-api-client/src/main/java/com/google/api/client/googleapis/auth/oauth2/OAuth2Utils.java @@ -83,6 +83,7 @@ static boolean runningOnComputeEngine(HttpTransport transport, try { HttpRequest request = transport.createRequestFactory().buildGetRequest(tokenUrl); request.setConnectTimeout(COMPUTE_PING_CONNECTION_TIMEOUT_MS); + request.getHeaders().set("Metadata-Flavor", "Google"); HttpResponse response = request.execute(); try { HttpHeaders headers = response.getHeaders(); From 173adcaed0d96b3771486ee59d0b4a4cf87df895 Mon Sep 17 00:00:00 2001 From: Jeff Ching Date: Tue, 22 Oct 2019 16:35:28 -0700 Subject: [PATCH 08/10] docs: migrate docs from wiki (#1399) * docs: migrate docs from wiki * docs: update README links to gh-pages --- .gitignore | 2 - docs/_config.yml | 2 + docs/_data/navigation.yml | 23 ++ docs/_layouts/default.html | 54 ++++ docs/android.md | 69 +++++ docs/batching.md | 43 +++ docs/component-modules.md | 64 ++++ docs/errors.md | 52 ++++ docs/google-app-engine.md | 59 ++++ docs/index.md | 77 +++++ docs/media-download.md | 88 ++++++ docs/media-upload.md | 112 +++++++ docs/oauth-2.0.md | 582 +++++++++++++++++++++++++++++++++++++ docs/setup.md | 79 +++++ docs/support.md | 67 +++++ 15 files changed, 1371 insertions(+), 2 deletions(-) create mode 100644 docs/_config.yml create mode 100644 docs/_data/navigation.yml create mode 100644 docs/_layouts/default.html create mode 100644 docs/android.md create mode 100644 docs/batching.md create mode 100644 docs/component-modules.md create mode 100644 docs/errors.md create mode 100644 docs/google-app-engine.md create mode 100644 docs/index.md create mode 100644 docs/media-download.md create mode 100644 docs/media-upload.md create mode 100644 docs/oauth-2.0.md create mode 100644 docs/setup.md create mode 100644 docs/support.md diff --git a/.gitignore b/.gitignore index 3ca4b1fa5..2d6752757 100644 --- 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 new file mode 100644 index 000000000..0c830d027 --- /dev/null +++ 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 new file mode 100644 index 000000000..4a92b7885 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html new file mode 100644 index 000000000..b3e7d30e6 --- /dev/null +++ b/docs/_layouts/default.html @@ -0,0 +1,54 @@ + + + + + + +{% seo %} + + + + + + +
+
+

{{ site.title | default: site.github.repository_name }}

+ + {% for entry in site.data.navigation.toc %} + {{ entry.page }}
+ {% endfor %} +
+ + +
+ +
+ {{ content }} +
+ + +
+ + {% if site.google_analytics %} + + {% endif %} + + \ No newline at end of file diff --git a/docs/android.md b/docs/android.md new file mode 100644 index 000000000..f3b5ab5b6 --- /dev/null +++ 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 new file mode 100644 index 000000000..52f943e8c --- /dev/null +++ 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 callback = new JsonBatchCallback() { + + 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 \ No newline at end of file diff --git a/docs/component-modules.md b/docs/component-modules.md new file mode 100644 index 000000000..264788217 --- /dev/null +++ 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 new file mode 100644 index 000000000..3b43e83ab --- /dev/null +++ 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 new file mode 100644 index 000000000..52a0a360d --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..106bc5e4f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,77 @@ +--- +title: Overview +--- + +# Overview + +## Description + +The Google APIs Client Library for Java is a flexible, efficient, and powerful +Java client library for accessing any HTTP-based API on the web, not just Google +APIs. + +The library has the following features: + +- A powerful [OAuth 2.0][oauth2] library with a consistent interface. +- Lightweight, efficient XML and JSON data models that support any data schema. +- Support for [protocol buffers][protobuf]. +- A set of [generated libraries for Google APIs][service-clients]. + +The library supports the following Java environments: + +- Java 7 (or higher) +- Android 1.6 (or higher) +- [Google App Engine][app-engine] + +This library is built on top of two common libraries, also built by Google, and +also designed to work with any HTTP service on the web: + +- [Google HTTP Client Library for Java][http-client] +- [Google OAuth Client Library for Java][oauth-client] + +This is an open-source library, and [contributions][contributions] are welcome. + +## Accessing Google APIs + +To use Google's Java client libraries to call any Google API, you need two +libraries: + +- The core Google APIs Client Library for Java (`google-api-java-client`), which + is the generic runtime library described here. This library provides + functionality common to all APIs, for example HTTP transport, error handling, + authentication, JSON parsing, media download/upload, and batching. +- An auto-generated Java library for the API you are accessing, for example the + [generated Java library for the BigQuery API][bigquery]. These generated + libraries include API-specific information such as the root URL, and classes + that represent entities in the context of the API. These classes are useful + for making conversions between JSON objects and Java objects. + +To find the generated library for a Google API, visit +[Google APIs Client Library for Java][service-list]. +The API-specific Java packages include both the core google-api-java-client and +the client-specific libraries. + +## Beta Features + +Features marked with the `@Beta` annotation at the class or method level are +subject to change. They might be modified in any way, or even removed, in any +major release. You should not use beta features if your code is a library itself +(that is, if your code is used on the `CLASSPATH` of users outside your own +control). + +## Deprecated Features + +Deprecated non-beta features will be removed eighteen months after the release +in which they are first deprecated. You must fix your usages before this time. +If you don't, any type of breakage might result, and you are not guaranteed a +compilation error. + +[oauth2]: https://googleapis.github.io/google-api-java-client/oauth-2.0.html +[protobuf]: https://github.com/google/protobuf/ +[service-clients]: https://github.com/googleapis/google-api-java-client-services/ +[app-engine]: https://googleapis.github.io/google-api-java-client/google-app-engine.html +[http-client]: https://github.com/googleapis/google-http-java-client +[oauth-client]: https://github.com/googleapis/google-oauth-java-client +[contributions]: https://github.com/googleapis/google-api-java-client/wiki/CONTRIBUTING.md +[bigquery]: https://github.com/google/google-api-java-client-samples/tree/master/bigquery-appengine-sample/src/main/java/com/google/api/client/sample/bigquery/appengine/dashboard +[service-list]: https://github.com/googleapis/google-api-java-client-services#supported-google-apis diff --git a/docs/media-download.md b/docs/media-download.md new file mode 100644 index 000000000..088786828 --- /dev/null +++ b/docs/media-download.md @@ -0,0 +1,88 @@ +--- +title: Media Download +--- + +# Media Download + +## Resumable media downloads + +When you download a large media file from a server, use resumable media download +to download the file chunk by chunk. The Google API generated libraries contain +convenience methods for interacting with resumable media download, which was +introduced in the 1.9.0-beta version of the Google API Client Library for Java. + +The resumable media download protocol is similar to the resumable media upload +protocol, which is described in the +[Google Drive API documentation][google-drive-documentation]. + +### Implementation details + +The main classes of interest are [`MediaHttpDownloader`][media-http-downloader] +and [`MediaHttpDownloaderProgressListener`][media-http-downloader-progress-listener]. +Media content is downloaded in chunks, and chunk size is configurable. If a +server error is encountered in a request, then the request is retried. + +If methods in the service-specific generated libraries support download in the +Discovery document, then a convenient download method is created for these +methods that takes in an [`OutputStream`][output-stream]. (For more about using +media download with the Google APIs Discovery Service, see +[Media download][media-download].) + +For example: + +```java +class CustomProgressListener implements MediaHttpDownloaderProgressListener { + public void progressChanged(MediaHttpDownloader downloader) { + switch (downloader.getDownloadState()) { + case MEDIA_IN_PROGRESS: + System.out.println(downloader.getProgress()); + break; + case MEDIA_COMPLETE: + System.out.println("Download is complete!"); + } + } +} + +OutputStream out = new FileOutputStream("/tmp/driveFile.jpg"); + +DriveFiles.Get request = drive.files().get(fileId); +request.getMediaHttpDownloader().setProgressListener(new CustomProgressListener()); +request.executeMediaAndDownloadTo(out); +``` + +You can also use this feature without service-specific generated libraries. +Here is an example: + +```java +OutputStream out = new FileOutputStream("/tmp/Test.jpg"); + +MediaHttpDownloader downloader = new MediaHttpDownloader(transport, httpRequestInitializer); +downloader.setProgressListener(new CustomProgressListener()); +downloader.download(requestUrl, out); +``` + +## Direct media download + +Resumable media download is enabled by default, but you can disable it and use +direct media download instead, for example if you are downloading a small file. +Direct media download was introduced in the 1.9.0-beta version of the Google API +Client Library for Java. + +Direct media download downloads the whole media content in one HTTP request, as +opposed to the resumable media download protocol, which can download in multiple +requests. Doing a direct download reduces the number of HTTP requests but +increases the chance of failures (such as connection failures) that can happen +with large downloads. + +The usage is the same as what is described above, plus the following call that +tells [`MediaHttpDownloader`][media-http-downloader] to do direct downloads: + +```java +mediaHttpDownloader.setDirectDownloadEnabled(true); +``` + +[google-drive-documentation]: https://developers.google.com/drive/web/manage-uploads#resumable +[media-http-downloader]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/media/MediaHttpDownloader.html +[media-http-downloader-progress-listener]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/media/MediaHttpDownloaderProgressListener.html +[output-stream]: https://docs.oracle.com/javase/7/docs/api/java/io/OutputStream.html +[media-download]: https://developers.google.com/discovery/v1/using#discovery-doc-methods-mediadownload \ No newline at end of file diff --git a/docs/media-upload.md b/docs/media-upload.md new file mode 100644 index 000000000..8418ca160 --- /dev/null +++ b/docs/media-upload.md @@ -0,0 +1,112 @@ +--- +title: Media Upload +--- + +# Media Upload + +## Resumable media upload + +When you upload a large media file to a server, use resumable media upload to +send the file chunk by chunk. The Google API generated libraries contain +convenience methods for interacting with resumable media upload, which was +introduced in the 1.7.0-beta version of the Google API Client Library for Java. + +The resumable media upload protocol is similar to the resumable media upload +protocol described in the +[Google Drive API documentation][google-drive-documentation]. + +### Protocol design + +The following sequence diagram shows how the resumable media upload protocol +works: ![Resumable Media Upload Protocol Diagram][resumable-media-upload-protocol-diagram] + +### Implementation details + +The main classes of interest are [MediaHttpUploader][media-http-uploader] and +[MediaHttpProgressListener][media-http-progress-listener]. + +If methods in the service-specific generated libraries contain the `mediaUpload` +parameter in the Discovery document, then a convenience method is created for +these methods that takes an [InputStreamContent][input-stream-content] as a +parameter. (For more about using media upload with the Google APIs Discovery +Service, see [Media upload][media-upload].) + +For example, the `insert` method of the Drive API supports `mediaUpload`, and +you can use the following code to upload a file: + +```java +class CustomProgressListener implements MediaHttpUploaderProgressListener { + public void progressChanged(MediaHttpUploader uploader) throws IOException { + switch (uploader.getUploadState()) { + case INITIATION_STARTED: + System.out.println("Initiation has started!"); + break; + case INITIATION_COMPLETE: + System.out.println("Initiation is complete!"); + break; + case MEDIA_IN_PROGRESS: + System.out.println(uploader.getProgress()); + break; + case MEDIA_COMPLETE: + System.out.println("Upload is complete!"); + } + } +} + +File mediaFile = new File("/tmp/driveFile.jpg"); +InputStreamContent mediaContent = + new InputStreamContent("image/jpeg", + new BufferedInputStream(new FileInputStream(mediaFile))); +mediaContent.setLength(mediaFile.length()); + +Drive.Files.Insert request = drive.files().insert(fileMetadata, mediaContent); +request.getMediaHttpUploader().setProgressListener(new CustomProgressListener()); +request.execute(); +``` + +You can also use the resumable media upload feature without the service-specific +generated libraries. Here is an example: + +```java +File mediaFile = new File("/tmp/Test.jpg"); +InputStreamContent mediaContent = + new InputStreamContent("image/jpeg", + new BufferedInputStream(new FileInputStream(mediaFile))); +mediaContent.setLength(mediaFile.length()); + + +MediaHttpUploader uploader = new MediaHttpUploader(mediaContent, transport, httpRequestInitializer); +uploader.setProgressListener(new CustomProgressListener()); +HttpResponse response = uploader.upload(requestUrl); +if (!response.isSuccessStatusCode()) { + throw GoogleJsonResponseException(jsonFactory, response); +} +``` + +## Direct media upload + +Resumable media upload is enabled by default, but you can disable it and use +direct media upload instead, for example if you are uploading a small file. +Direct media upload was introduced in the 1.9.0-beta version of the Google API +Client Library for Java. + +Direct media upload uploads the whole file in one HTTP request, as opposed to +the resumable media upload protocol, which uploads the file in multiple +requests. Doing a direct upload reduces the number of HTTP requests but +increases the chance of failures (such as connection failures) that can happen +with large uploads. + +The usage for direct media upload is the same as what is described above for +resumable media upload, plus the following call that tells +[MediaHttpUploader][media-http-uploader] to only do direct uploads: + +```java +mediaHttpUploader.setDirectUploadEnabled(true); +``` + +[google-drive-documentation]: https://developers.google.com/drive/web/manage-uploads#resumable +[media-http-uploader]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/media/MediaHttpUploader.html +[media-http-progress-listener]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/media/MediaHttpUploaderProgressListener.html +[input-stream-content]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/http/InputStreamContent.html +[media-upload]: https://developers.google.com/discovery/v1/using#discovery-doc-methods-mediaupload +[resumable-media-upload-protocol-diagram]: https://github.com/googleapis/google-api-java-client/raw/master/Resumable-Media-Upload-Sequence-Diagram.png diff --git a/docs/oauth-2.0.md b/docs/oauth-2.0.md new file mode 100644 index 000000000..df8a044ee --- /dev/null +++ b/docs/oauth-2.0.md @@ -0,0 +1,582 @@ +--- +title: OAuth 2.0 +--- + +# Using OAuth 2.0 with the Google API Client Library for Java + +This document explains how to use the [`GoogleCredential`][google-credential] +utility class to do OAuth 2.0 authorization with Google services. For +information about the generic [OAuth 2.0 functions that we provide, see OAuth +2.0 and the Google OAuth Client Library for Java][google-oauth-client-instructions]. + +To access protected data stored on Google services, use [OAuth 2.0][oauth2] for +authorization. Google APIs support OAuth 2.0 flows for different types of client +applications. In all of these flows, the client application requests an access +token that is associated with only your client application and the owner of the +protected data being accessed. The access token is also associated with a +limited scope that defines the kind of data your client application has access +to (for example "Manage your tasks"). An important goal for OAuth 2.0 is to +provide secure and convenient access to the protected data, while minimizing the +potential impact if an access token is stolen. + +The OAuth 2.0 packages in the Google API Client Library for Java are built on +the general-purpose +[Google OAuth 2.0 Client Library for Java][google-oauth-client-instructions]. + +For details, see the Javadoc documentation for the following packages: + +* [`com.google.api.client.googleapis.auth.oauth2`][javadoc-oauth2] (from `google-api-client`) +* [`com.google.api.client.googleapis.extensions.appengine.auth.oauth2`][javadoc-appengine-oauth2] (from google-api-client-appengine) + +## Google API Console + +Before you can access Google APIs, you need to set up a project on the +[Google API Console][console] for auth and billing purposes, whether your client +is an installed application, a mobile application, a web server, or a client +that runs in browser. + +For instructions on setting up your credentials properly, see the +[API Console Help][console-help]. + +## Credential + +### GoogleCredential + +[`GoogleCredential`][google-credential] is a thread-safe helper class for OAuth +2.0 for accessing protected resources using an access token. For example, if you +already have an access token, you can make a request in the following way: + +```java +GoogleCredential credential = new GoogleCredential().setAccessToken(accessToken); +Plus plus = new Plus.builder(new NetHttpTransport(), + JacksonFactory.getDefaultInstance(), + credential) + .setApplicationName("Google-PlusSample/1.0") + .build(); +``` + +### Google App Engine identity + +This alternative credential is based on the +[Google App Engine App Identity Java API][identity-api]. Unlike the credential +in which a client application requests access to an end-user's data, the App +Identity API provides access to the client application's own data. + +Use [`AppIdentityCredential`][app-identity-credential] (from +`google-api-client-appengine`). This credential is much simpler because Google +App Engine takes care of all of the details. You only specify the OAuth 2.0 +scope you need. + +Example code taken from [urlshortener-robots-appengine-sample][urlshortener-sample]: + +```java +static Urlshortener newUrlshortener() { + AppIdentityCredential credential = + new AppIdentityCredential( + Collections.singletonList(UrlshortenerScopes.URLSHORTENER)); + return new Urlshortener.Builder(new UrlFetchTransport(), + JacksonFactory.getDefaultInstance(), + credential) + .build(); +} +``` + +## Data store + +An access token typically has an expiration date of 1 hour, after which you will +get an error if you try to use it. [GoogleCredential][google-credential] takes +care of automatically "refreshing" the token, which simply means getting a new +access token. This is done by means of a long-lived refresh token, which is +typically received along with the access token if you use the +`access_type=offline` parameter during the authorization code flow (see +[`GoogleAuthorizationCodeFlow.Builder.setAccessType(String)`][auth-code-flow-set-access-type]. + +Most applications will need to persist the credential's access token and/or +refresh token. To persist the credential's access and/or refresh tokens, you can +provide your own implementation of [`DataStoreFactory`][data-store-factory]) +with [`StoredCredential`][stored-credential]; or you can use one of the +following implementations provided by the library: + +* [`AppEngineDataStoreFactory`][appengine-data-store-factory]: persists the + credential using the Google App Engine Data Store API. +* [`MemoryDataStoreFactory`][memory-data-store-factory]: "persists" the + credential in memory, which is only useful as a short-term storage for the + lifetime of the process. +* [`FileDataStoreFactory`][file-data-store-factory]: persists the credential in + a file. + +### Google App Engine users + + +[`AppEngineCredentialStore`][appengine-credential-store] is deprecated and is being removed. + +We recommend that you use +[`AppEngineDataStoreFactory`][appengine-data-store-factory] with +[`StoredCredential`][stored-credential]. If you have credentials stored in the +old way, you can use the added helper methods +[`migrateTo(AppEngineDataStoreFactory)`][appengine-migrate] or +[`migrateTo(DataStore)`][datastore-migrate] to migrate. + +Use [`DataStoreCredentialRefreshListener`][datastore-credential-listener] and +set it for the credential using +[`GoogleCredential.Builder.addRefreshListener(CredentialRefreshListener)`][add-refresh-listener]. + +## Authorization code flow + +Use the authorization code flow to allow the end user to grant your application +access to their protected data. The protocol for this flow is specified in the +[Authorization Code Grant specification][authorization-code-grant]. + +This flow is implemented using [`AuthorizationCodeFlow`][authorization-code-flow]. +The steps are: + +* An end user logs in to your application. You need to associate that user with + a user ID that is unique for your application. +* Call [`AuthorizationCodeFlow.loadCredential(String)`][auth-code-flow-load], + based on the user ID, to check if the user's credentials are already known. + If so, you're done. +* If not, call [`AuthorizationCodeFlow.newAuthorizationUrl()`][auth-code-flow-new] + and direct the end user's browser to an authorization page where they can grant + your application access to their protected data. +* The web browser then redirects to the redirect URL with a "code" query + parameter that can then be used to request an access token using + [`AuthorizationCodeFlow.newTokenRequest(String)`][token-request]. +* Use + [`AuthorizationCodeFlow.createAndStoreCredential(TokenResponse, String)`][create-and-store] + to store and obtain a credential for accessing protected resources. + +Alternatively, if you are not using +[`AuthorizationCodeFlow`][authorization-code-flow], you may use the lower-level +classes: + +* Use [`DataStore.get(String)`][datastore-get] to load the credential from the + store, based on the user ID. +* Use [`AuthorizationCodeRequestUrl`][auth-code-request-url] to direct the + browser to the authorization page. +* Use [`AuthorizationCodeResponseUrl`][auth-code-response-url] to process the + authorization response and parse the authorization code. +* Use [`AuthorizationCodeTokenRequest`][auth-code-token-request] to request an + access token and possibly a refresh token. +* Create a new [`Credential`][credential] and store it using + [`DataStore.set(String, V)`][datastore-set]. +* Access protected resources using the [`Credential`][credential]. Expired access + tokens are automatically refreshed using the refresh token, if applicable. + Make sure to use + [`DataStoreCredentialRefreshListener`][datastore-credential-listener] and set + it for the credential using + [`Credential.Builder.addRefreshListener(CredentialRefreshListener)`][add-refresh-listener]. + +### Web server applications + +The protocol for this flow is explained in +[Using OAuth 2.0 for Web Server Applications][oauth-web-server]. + +This library provides servlet helper classes to significantly simplify the +authorization code flow for basic use cases. You just provide concrete subclasses +of [`AbstractAuthorizationCodeServlet`][abstract-code-servlet] +and [`AbstractAuthorizationCodeCallbackServlet`][abstract-code-callback-servlet] +(from `google-oauth-client-servlet`) and add them to your `web.xml` file. Note +that you still need to take care of user login for your web application and +extract a user ID. + +```java +public class CalendarServletSample extends AbstractAuthorizationCodeServlet { + + @Override + protected void doGet(HttpServletRequest request, HttpServletResponse response) + throws IOException { + // do stuff + } + + @Override + protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { + GenericUrl url = new GenericUrl(req.getRequestURL().toString()); + url.setRawPath("/oauth2callback"); + return url.build(); + } + + @Override + protected AuthorizationCodeFlow initializeFlow() throws IOException { + return new GoogleAuthorizationCodeFlow.Builder( + new NetHttpTransport(), JacksonFactory.getDefaultInstance(), + "[[ENTER YOUR CLIENT ID]]", "[[ENTER YOUR CLIENT SECRET]]", + Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory( + DATA_STORE_FACTORY).setAccessType("offline").build(); + } + + @Override + protected String getUserId(HttpServletRequest req) throws ServletException, IOException { + // return user ID + } +} + +public class CalendarServletCallbackSample extends AbstractAuthorizationCodeCallbackServlet { + + @Override + protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential) + throws ServletException, IOException { + resp.sendRedirect("/"); + } + + @Override + protected void onError( + HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse) + throws ServletException, IOException { + // handle error + } + + @Override + protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { + GenericUrl url = new GenericUrl(req.getRequestURL().toString()); + url.setRawPath("/oauth2callback"); + return url.build(); + } + + @Override + protected AuthorizationCodeFlow initializeFlow() throws IOException { + return new GoogleAuthorizationCodeFlow.Builder( + new NetHttpTransport(), JacksonFactory.getDefaultInstance() + "[[ENTER YOUR CLIENT ID]]", "[[ENTER YOUR CLIENT SECRET]]", + Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory( + DATA_STORE_FACTORY).setAccessType("offline").build(); + } + + @Override + protected String getUserId(HttpServletRequest req) throws ServletException, IOException { + // return user ID + } +} +``` + +### Google App Engine applications + +The authorization code flow on App Engine is almost identical to the servlet +authorization code flow, except that we can leverage Google App Engine's +[Users Java API][users-api]. The user needs to be logged in for the Users Java +API to be enabled; for information about redirecting users to a login page if +they are not already logged in, see +[Security and Authentication][security-authentication] (in `web.xml`). + +The primary difference from the servlet case is that you provide concrete +subclasses of [`AbstractAppEngineAuthorizationCodeServlet`][abstract-gae-code-servlet] +and [`AbstractAppEngineAuthorizationCodeCallbackServlet`][abstract-gae-code-callback-servlet] +(from `google-oauth-client-appengine`). They extend the abstract servlet classes +and implement the `getUserId` method for you using the Users Java API. +[`AppEngineDataStoreFactory`][appengine-data-store-factory] (from +[Google HTTP Client Library for Java][google-http-client]) is a good option for +persisting the credential using the Google App Engine Data Store API. + +Example taken (slightly modified) from [calendar-appengine-sample][calendar-sample]: + +```java +public class CalendarAppEngineSample extends AbstractAppEngineAuthorizationCodeServlet { + + @Override + protected void doGet(HttpServletRequest request, HttpServletResponse response) + throws IOException { + // do stuff + } + + @Override + protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { + return Utils.getRedirectUri(req); + } + + @Override + protected AuthorizationCodeFlow initializeFlow() throws IOException { + return Utils.newFlow(); + } +} + +class Utils { + static String getRedirectUri(HttpServletRequest req) { + GenericUrl url = new GenericUrl(req.getRequestURL().toString()); + url.setRawPath("/oauth2callback"); + return url.build(); + } + + static GoogleAuthorizationCodeFlow newFlow() throws IOException { + return new GoogleAuthorizationCodeFlow.Builder(HTTP_TRANSPORT, JSON_FACTORY, + getClientCredential(), Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory( + DATA_STORE_FACTORY).setAccessType("offline").build(); + } +} + +public class OAuth2Callback extends AbstractAppEngineAuthorizationCodeCallbackServlet { + + private static final long serialVersionUID = 1L; + + @Override + protected void onSuccess(HttpServletRequest req, HttpServletResponse resp, Credential credential) + throws ServletException, IOException { + resp.sendRedirect("/"); + } + + @Override + protected void onError( + HttpServletRequest req, HttpServletResponse resp, AuthorizationCodeResponseUrl errorResponse) + throws ServletException, IOException { + String nickname = UserServiceFactory.getUserService().getCurrentUser().getNickname(); + resp.getWriter().print("

" + nickname + ", why don't you want to play with me?

"); + resp.setStatus(200); + resp.addHeader("Content-Type", "text/html"); + } + + @Override + protected String getRedirectUri(HttpServletRequest req) throws ServletException, IOException { + return Utils.getRedirectUri(req); + } + + @Override + protected AuthorizationCodeFlow initializeFlow() throws IOException { + return Utils.newFlow(); + } +} +``` + +For an additional sample, see +[storage-serviceaccount-appengine-sample][storage-sample]. + +### Service accounts + +[GoogleCredential][google-credential] also supports [service accounts][service-accounts]. +Unlike the credential in which a client application requests access to an +end-user's data, Service Accounts provide access to the client application's +own data. Your client application signs the request for an access token using +a private key downloaded from the [Google API Console][console]. + +Example code taken from [plus-serviceaccount-cmdline-sample][plus-sample]: + +```java +HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport(); +JsonFactory jsonFactory = JacksonFactory.getDefaultInstance(); +... +// Build service account credential. + +GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json")) + .createScoped(Collections.singleton(PlusScopes.PLUS_ME)); +// Set up global Plus instance. +plus = new Plus.Builder(httpTransport, jsonFactory, credential) + .setApplicationName(APPLICATION_NAME).build(); +... +``` + +For an additional sample, see [storage-serviceaccount-cmdline-sample][storage-sample]. + +**Note:** Although you can use service accounts in applications that run from a +Google Apps domain, service accounts are not members of your Google Apps account +and aren't subject to domain policies set by Google Apps administrators. For +example, a policy set in the Google Apps admin console to restrict the ability +of Apps end users to share documents outside of the domain would not apply to +service accounts. + +#### Impersonation + +You can also use the service account flow to impersonate a user in a domain that +you own. This is very similar to the service account flow above, but you +additionally call [`GoogleCredential.Builder.setServiceAccountUser(String)`][set-service-account-user]. + +### Installed applications + +This is the command-line authorization code flow described in [Using OAuth 2.0 for Installed Applications][oauth2-installed-app]. + +Example snippet from [plus-cmdline-sample][plus-sample]: + +```java +public static void main(String[] args) { + try { + httpTransport = GoogleNetHttpTransport.newTrustedTransport(); + dataStoreFactory = new FileDataStoreFactory(DATA_STORE_DIR); + // authorization + Credential credential = authorize(); + // set up global Plus instance + plus = new Plus.Builder(httpTransport, JSON_FACTORY, credential).setApplicationName( + APPLICATION_NAME).build(); + // ... +} + +private static Credential authorize() throws Exception { + // load client secrets + GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(JSON_FACTORY, + new InputStreamReader(PlusSample.class.getResourceAsStream("/client_secrets.json"))); + // set up authorization code flow + GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder( + httpTransport, JSON_FACTORY, clientSecrets, + Collections.singleton(PlusScopes.PLUS_ME)).setDataStoreFactory( + dataStoreFactory).build(); + // authorize + return new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user"); +} +``` + +### Client-side applications + +To use the browser-based client flow described in +[Using OAuth 2.0 for Client-side Applications][oauth2-user-agent], you would +typically follow these steps: + +1. Redirect the end user in the browser to the authorization page using + [`GoogleBrowserClientRequestUrl`][browser-client-request] to grant your + browser application access to the end user's protected data. +1. Use the [Google API Client Library for JavaScript][javascript-client] to + process the access token found in the URL fragment at the redirect URI + registered at the [Google API Console][console]. + +Sample usage for a web application: + +```java +public void doGet(HttpServletRequest request, HttpServletResponse response)throws IOException { + String url = new GoogleBrowserClientRequestUrl("812741506391.apps.googleusercontent.com", + "https://oauth2.example.com/oauthcallback", Arrays.asList( + "https://www.googleapis.com/auth/userinfo.email", + "https://www.googleapis.com/auth/userinfo.profile")).setState("/profile").build(); + response.sendRedirect(url); +} +``` + +### Android (@Beta) + +**Which library to use with Android:** + +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. If the Google API you want to use with Android +is not part of the Google Play Services library, you can use the Google API +Client Library for Java, which supports Android 4.0 (Ice Cream Sandwich) +(or higher), and which is described here. The support for Android in the Google +API Client Library for Java is `@Beta`. + +**Background:** + +Starting with Eclair (SDK 2.1), user accounts are managed on an Android device +using the Account Manager. All Android application authorization is centrally +managed by the SDK using [AccountManager][account-manager]. You specify the +OAuth 2.0 scope your application needs, and it returns an access token to use. + +The OAuth 2.0 scope is specified via the `authTokenType` parameter as `oauth2:` +plus the scope. For example: + +``` +oauth2:https://www.googleapis.com/auth/tasks +``` + +This specifies read/write access to the Google Tasks API. If you need multiple +OAuth 2.0 scopes, use a space-separated list. + +Some APIs have special `authTokenType` parameters that also work. For example, +"Manage your tasks" is an alias for the `authtokenType` example shown above. + +You must also specify the API key from the [Google API Console][console]. +Otherwise, the token that the AccountManager gives you only provides you with +anonymous quota, which is usually very low. By contrast, by specifying an API +key you receive a higher free quota, and can optionally set up billing for usage +above that. + +Example code snippet taken from [tasks-android-sample][tasks-sample]: + +```java +com.google.api.services.tasks.Tasks service; + +@Override +public void onCreate(Bundle savedInstanceState) { + credential = + GoogleAccountCredential.usingOAuth2(this, Collections.singleton(TasksScopes.TASKS)); + SharedPreferences settings = getPreferences(Context.MODE_PRIVATE); + credential.setSelectedAccountName(settings.getString(PREF_ACCOUNT_NAME, null)); + service = + new com.google.api.services.tasks.Tasks.Builder(httpTransport, jsonFactory, credential) + .setApplicationName("Google-TasksAndroidSample/1.0").build(); +} + +private void chooseAccount() { + startActivityForResult(credential.newChooseAccountIntent(), REQUEST_ACCOUNT_PICKER); +} + +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + super.onActivityResult(requestCode, resultCode, data); + switch (requestCode) { + case REQUEST_GOOGLE_PLAY_SERVICES: + if (resultCode == Activity.RESULT_OK) { + haveGooglePlayServices(); + } else { + checkGooglePlayServicesAvailable(); + } + break; + case REQUEST_AUTHORIZATION: + if (resultCode == Activity.RESULT_OK) { + AsyncLoadTasks.run(this); + } else { + chooseAccount(); + } + break; + case REQUEST_ACCOUNT_PICKER: + if (resultCode == Activity.RESULT_OK && data != null && data.getExtras() != null) { + String accountName = data.getExtras().getString(AccountManager.KEY_ACCOUNT_NAME); + if (accountName != null) { + credential.setSelectedAccountName(accountName); + SharedPreferences settings = getPreferences(Context.MODE_PRIVATE); + SharedPreferences.Editor editor = settings.edit(); + editor.putString(PREF_ACCOUNT_NAME, accountName); + editor.commit(); + AsyncLoadTasks.run(this); + } + } + break; + } +} +``` + +[google-credential]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.html +[google-oauth-client-instructions]: https://developers.google.com/api-client-library/java/google-oauth-java-client/oauth2 +[oauth2]: https://developers.google.com/accounts/docs/OAuth2 +[javadoc-oauth2]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/package-frame.html +[javadoc-appengine-oauth2]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/extensions/appengine/auth/oauth2/package-frame.html +[console]: https://console.developers.google.com/ +[console-help]: https://developer.google.com/console/help/console/ +[identity-api]: https://cloud.google.com/appengine/docs/java/appidentity/?csw=1#Asserting_Identity_to_Google_APIs +[app-identity-credential]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/extensions/appengine/auth/oauth2/AppIdentityCredential.html +[urlshortener-sample]: https://github.com/google/google-api-java-client-samples/tree/master/urlshortener-robots-appengine-sample +[auth-code-flow-set-access-type]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleAuthorizationCodeFlow.Builder.html#setAccessType-java.lang.String- +[data-store-factory]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/DataStoreFactory.html +[stored-credential]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/StoredCredential.html +[appengine-data-store-factory]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/extensions/appengine/datastore/AppEngineDataStoreFactory.html +[google-http-client]: https://github.com/googleapis/google-http-java-client +[memory-data-store-factory]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/MemoryDataStoreFactory.html +[file-data-store-factory]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/FileDataStoreFactory.html +[appengine-credential-store]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AppEngineCredentialStore.html +[appengine-migrate]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AppEngineCredentialStore.html#migrateTo-com.google.api.client.extensions.appengine.datastore.AppEngineDataStoreFactory- +[datastore-migrate]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AppEngineCredentialStore.html#migrateTo-com.google.api.client.util.store.DataStore- +[datastore-credential-listener]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/DataStoreCredentialRefreshListener.html +[add-refresh-listener]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.Builder.html#addRefreshListener-com.google.api.client.auth.oauth2.CredentialRefreshListener- +[authorization-code-grant]: https://tools.ietf.org/html/rfc6749#section-4.1 +[authorization-code-flow]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html +[auth-code-flow-load]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#loadCredential-java.lang.String- +[auth-code-flow-new]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#newAuthorizationUrl-- +[token-request]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#newTokenRequest-java.lang.String- +[create-and-store]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeFlow.html#createAndStoreCredential-com.google.api.client.auth.oauth2.TokenResponse-java.lang.String- +[datastore-get]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/DataStore.html#get-java.lang.String- +[auth-code-request-url]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeRequestUrl.html +[auth-code-response-url]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeResponseUrl.html +[auth-code-token-request]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/AuthorizationCodeTokenRequest.html +[datastore-set]: https://googleapis.dev/java/google-http-client/latest/com/google/api/client/util/store/DataStore.html#set(java.lang.String,%20V) +[credential]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/auth/oauth2/Credential.html +[oauth2-web-server]: https://developers.google.com/accounts/docs/OAuth2WebServer +[abstract-code-servlet]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/servlet/auth/oauth2/AbstractAuthorizationCodeServlet.html +[abstract-code-callback-servlet]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/servlet/auth/oauth2/AbstractAuthorizationCodeCallbackServlet.html +[users-api]: https://cloud.google.com/appengine/docs/java/users/ +[security-authentication]: https://cloud.google.com/appengine/docs/java/config/webxml#Security_and_Authentication +[abstract-gae-code-servlet]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AbstractAppEngineAuthorizationCodeServlet.html +[abstract-gae-code-callback-servlet]: https://googleapis.dev/java/google-oauth-client/latest/com/google/api/client/extensions/appengine/auth/oauth2/AbstractAppEngineAuthorizationCodeCallbackServlet.html +[calendar-sample]: https://github.com/google/google-api-java-client-samples/tree/master/calendar-appengine-sample +[storage-sample]: https://github.com/GoogleCloudPlatform/cloud-storage-docs-xml-api-examples +[service-accounts]: https://developers.google.com/accounts/docs/OAuth2ServiceAccount +[plus-sample]: https://github.com/google/google-api-java-client-samples/tree/master/plus-serviceaccount-cmdline-sample +[set-service-account-user]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleCredential.Builder.html#setServiceAccountUser-java.lang.String- +[oauth2-installed-app]: https://developers.google.com/accounts/docs/OAuth2InstalledApp +[oauth2-user-agent]: https://developers.google.com/accounts/docs/OAuth2UserAgent +[browser-client-request]: https://googleapis.dev/java/google-api-client/latest/com/google/api/client/googleapis/auth/oauth2/GoogleBrowserClientRequestUrl.html +[javascript-client]: https://developers.google.com/api-client-library/javascript/ +[play-services]: https://developer.android.com/google/play-services/index.html +[account-manager]: http://developer.android.com/reference/android/accounts/AccountManager.html +[tasks-sample]: https://github.com/google/google-api-java-client-samples/tree/master/tasks-android-sample \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 000000000..d62852330 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,79 @@ +--- +title: Setup Instructions +--- + +# Setup Instructions + +You can download the Google API Client Library for Java and its dependencies in +a zip file, or you can use a dependency manager such as Maven or gradle to +install the necessary jars from the Maven Central repository. + +## Maven + +The Google API Client Library for Java is in the central Maven repository. The +Maven `groupId` for all artifacts for this library is `com.google.api-client`. + +To ensure all dependency versions work together and to avoid having to manually +choose and specify versions for each dependency, we recommend first importing +the `com.google.cloud:libraries-bom` in the `dependencyManagement` section of +your `pom.xml`: + +```xml + + + + com.google.cloud + libraries-bom + 2.2.0 + pom + import + + + +``` + +Then you add the individual dependencies you need without version numbers to the +dependencies section: + +```xml + + com.google.api-client + google-api-client + +``` + +On Android, you may need to explicitly exclude unused dependencies: + +```xml + + com.google.api-client + google-api-client + + + xpp3 + xpp3 + + + httpclient + org.apache.httpcomponents + + + junit + junit + + + android + com.google.android + + + +``` + +## Download the library with dependencies + +Download the latest assembly zip file from Maven Central and extract it on your +computer. This zip contains the client library class jar files and the +associated source jar files for each artifact and their dependencies. You can +find dependency graphs and licenses for the different libraries in the +dependencies folder. For more details about the contents of the download, +see the contained `readme.html` file. diff --git a/docs/support.md b/docs/support.md new file mode 100644 index 000000000..e2806b871 --- /dev/null +++ b/docs/support.md @@ -0,0 +1,67 @@ +--- +title: Support +--- + +# Support + +## The Google API Client Library for Java community + +### Ask development questions + +Ask questions on StackOverflow: + +* When you ask questions about the Google API Client Library for Java, use the + [google-api-java-client][so-google-api-client] tag. Before you post a new + question, review the [most asked questions][so-maq]. +* For questions about Google APIs, use the [google-api][so-google-api] tag. +* Optionally include a tag to specify the language or platform, for example + [java][so-java], [android][so-android], or [google-app-engine][so-java-gae]. +* For tips on asking StackOverflow questions, see [How to Ask][so-how-to-ask]. + + + +### File feature requests and defects + +You can suggest features and report issues on our public [Issue Tracker][issues]. +This is a great place for the community to discuss and track implementations of +features or resolution of bug fixes, as well as share workarounds and patches. + +If you find a bug: + +* View [known bugs][bugs], and if a known bug corresponds to the issue you are + seeing, "star" it or comment on it. +* If the issue you are seeing has not yet been reported, + [file a bug report][new-issue]. + +If you have a feature request: + +* View [existing feature requests][feature-requests], and if a requested feature + corresponds to a feature you would like, "star" it or comment on it . +* If the feature has not yet been requested, + [file a feature request][new-issue]. + +### Contribute + +This is an [open-source][api-client] library, and [contributions][contributions] +are welcome. + +### Keep up with the library + +You can also take a look at the [release notes][releases]. + +[so-google-api-client]: http://stackoverflow.com/questions/tagged/google-api-java-client +[so-maq]: http://stackoverflow.com/questions/tagged/google-api-java-client?sort=faq&pagesize=50 +[so-google-api]: http://stackoverflow.com/questions/tagged/google-api +[so-java]: http://stackoverflow.com/questions/tagged/google-api-java-client+java +[so-android]: http://stackoverflow.com/questions/tagged/google-api-java-client+android +[so-java-gae]: http://stackoverflow.com/questions/tagged/google-api-java-client+java+google-app-engine +[so-how-to-ask]: http://stackoverflow.com/questions/ask +[issues]: https://github.com/googleapis/google-api-java-client/issues +[bugs]: https://github.com/googleapis/google-api-java-client/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+bug%22 +[feature-requests]: https://github.com/googleapis/google-api-java-client/issues?q=is%3Aissue+is%3Aopen+label%3A%22type%3A+feature+request%22 +[new-issue]: https://github.com/google/google-api-java-client/issues/new +[api-client]: https://github.com/googleapis/google-api-java-client +[contributions]: https://github.com/googleapis/google-api-java-client/blob/master/CONTRIBUTING.md +[releases]: https://github.com/googleapis/google-api-java-client/releases + From 502cf1d1f2b7b6231ace109f3162c069c5f2234c Mon Sep 17 00:00:00 2001 From: Renovate Bot Date: Fri, 25 Oct 2019 00:39:12 +0300 Subject: [PATCH 09/10] deps: update dependency com.google.oauth-client:google-oauth-client-bom to v1.30.4 (#1401) --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 78adf5371..d3369f576 100644 --- a/pom.xml +++ b/pom.xml @@ -494,7 +494,7 @@ --> UTF-8 1.32.1 - 1.30.3 + 1.30.4 3.0.2 2.8.5 1.9.13 From 2a49408c95b01f11b808eafd5b0199f820a443ab Mon Sep 17 00:00:00 2001 From: "release-please[bot]" <55107282+release-please[bot]@users.noreply.github.com> Date: Thu, 24 Oct 2019 14:59:00 -0700 Subject: [PATCH 10/10] chore: release 1.30.5 (#1398) * updated CHANGELOG.md [ci skip] * updated README.md [ci skip] * updated versions.txt [ci skip] * updated google-api-client-android/pom.xml [ci skip] * updated google-api-client-appengine/pom.xml [ci skip] * updated google-api-client-assembly/pom.xml [ci skip] * updated google-api-client-bom/pom.xml [ci skip] * updated google-api-client-gson/pom.xml [ci skip] * updated google-api-client-jackson2/pom.xml [ci skip] * updated google-api-client-java6/pom.xml [ci skip] * updated google-api-client-protobuf/pom.xml [ci skip] * updated google-api-client-servlet/pom.xml [ci skip] * updated google-api-client-xml/pom.xml [ci skip] * updated google-api-client/pom.xml [ci skip] * updated pom.xml [ci skip] --- CHANGELOG.md | 18 ++++++++++++++++++ README.md | 4 ++-- google-api-client-android/pom.xml | 2 +- google-api-client-appengine/pom.xml | 2 +- google-api-client-assembly/pom.xml | 2 +- google-api-client-bom/pom.xml | 22 +++++++++++----------- google-api-client-gson/pom.xml | 2 +- google-api-client-jackson2/pom.xml | 2 +- google-api-client-java6/pom.xml | 2 +- google-api-client-protobuf/pom.xml | 2 +- google-api-client-servlet/pom.xml | 2 +- google-api-client-xml/pom.xml | 2 +- google-api-client/pom.xml | 2 +- pom.xml | 2 +- versions.txt | 2 +- 15 files changed, 43 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b05531eac..b486aa3e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +### [1.30.5](https://www.github.com/googleapis/google-api-java-client/compare/v1.30.4...v1.30.5) (2019-10-24) + + +### Bug Fixes + +* add details to GoogleJsonResponseExceptions created with GoogleJsonResponseExceptionFactoryTesting ([#1395](https://www.github.com/googleapis/google-api-java-client/issues/1395)) ([1ffdba6](https://www.github.com/googleapis/google-api-java-client/commit/1ffdba6071d716d9843fada802c3cb4d2dcaedf7)) +* specify Metadata-Flavor for metadata requests ([#1397](https://www.github.com/googleapis/google-api-java-client/issues/1397)) ([d3dcfe9](https://www.github.com/googleapis/google-api-java-client/commit/d3dcfe9c049f72207b30e75f073b4b8ccc14c46d)) + + +### Dependencies + +* update dependency com.google.oauth-client:google-oauth-client-bom to v1.30.4 ([#1401](https://www.github.com/googleapis/google-api-java-client/issues/1401)) ([502cf1d](https://www.github.com/googleapis/google-api-java-client/commit/502cf1d1f2b7b6231ace109f3162c069c5f2234c)) + + +### Documentation + +* migrate docs from wiki ([#1399](https://www.github.com/googleapis/google-api-java-client/issues/1399)) ([173adca](https://www.github.com/googleapis/google-api-java-client/commit/173adcaed0d96b3771486ee59d0b4a4cf87df895)) + ### [1.30.4](https://www.github.com/googleapis/google-api-java-client/compare/v1.30.3...v1.30.4) (2019-09-20) diff --git a/README.md b/README.md index fb825b02e..e2b33d5af 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ To use Maven, add the following lines to your pom.xml file: com.google.api-client google-api-client - 1.30.4 + 1.30.5 @@ -47,7 +47,7 @@ repositories { mavenCentral() } dependencies { - compile 'com.google.api-client:google-api-client:1.30.4' + compile 'com.google.api-client:google-api-client:1.30.5' } ``` [//]: # ({x-version-update-end}) diff --git a/google-api-client-android/pom.xml b/google-api-client-android/pom.xml index 47606af40..3e234338d 100644 --- a/google-api-client-android/pom.xml +++ b/google-api-client-android/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml google-api-client-android diff --git a/google-api-client-appengine/pom.xml b/google-api-client-appengine/pom.xml index 1b857ab30..9db572d68 100644 --- a/google-api-client-appengine/pom.xml +++ b/google-api-client-appengine/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml google-api-client-appengine diff --git a/google-api-client-assembly/pom.xml b/google-api-client-assembly/pom.xml index f8d85b193..aa1e02a07 100644 --- a/google-api-client-assembly/pom.xml +++ b/google-api-client-assembly/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml com.google.api-client diff --git a/google-api-client-bom/pom.xml b/google-api-client-bom/pom.xml index 829c346eb..a01133af1 100644 --- a/google-api-client-bom/pom.xml +++ b/google-api-client-bom/pom.xml @@ -3,7 +3,7 @@ 4.0.0 com.google.api-client google-api-client-bom - 1.30.5-SNAPSHOT + 1.30.5 pom Google API Client Library for Java BOM @@ -63,52 +63,52 @@ com.google.api-client google-api-client - 1.30.5-SNAPSHOT + 1.30.5 com.google.api-client google-api-client-android - 1.30.5-SNAPSHOT + 1.30.5 com.google.api-client google-api-client-appengine - 1.30.5-SNAPSHOT + 1.30.5 com.google.api-client google-api-client-assembly - 1.30.5-SNAPSHOT + 1.30.5 com.google.api-client google-api-client-gson - 1.30.5-SNAPSHOT + 1.30.5 com.google.api-client google-api-client-jackson2 - 1.30.5-SNAPSHOT + 1.30.5 com.google.api-client google-api-client-java6 - 1.30.5-SNAPSHOT + 1.30.5 com.google.api-client google-api-client-protobuf - 1.30.5-SNAPSHOT + 1.30.5 com.google.api-client google-api-client-servlet - 1.30.5-SNAPSHOT + 1.30.5 com.google.api-client google-api-client-xml - 1.30.5-SNAPSHOT + 1.30.5 diff --git a/google-api-client-gson/pom.xml b/google-api-client-gson/pom.xml index 636c5c597..091a0d70b 100644 --- a/google-api-client-gson/pom.xml +++ b/google-api-client-gson/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml google-api-client-gson diff --git a/google-api-client-jackson2/pom.xml b/google-api-client-jackson2/pom.xml index 36279cda9..a2deb1532 100644 --- a/google-api-client-jackson2/pom.xml +++ b/google-api-client-jackson2/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml google-api-client-jackson2 diff --git a/google-api-client-java6/pom.xml b/google-api-client-java6/pom.xml index 6219dc325..78f9c6e61 100644 --- a/google-api-client-java6/pom.xml +++ b/google-api-client-java6/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml google-api-client-java6 diff --git a/google-api-client-protobuf/pom.xml b/google-api-client-protobuf/pom.xml index f45a5d198..59d84747b 100644 --- a/google-api-client-protobuf/pom.xml +++ b/google-api-client-protobuf/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml google-api-client-protobuf diff --git a/google-api-client-servlet/pom.xml b/google-api-client-servlet/pom.xml index 60059d02a..32302d44b 100644 --- a/google-api-client-servlet/pom.xml +++ b/google-api-client-servlet/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml google-api-client-servlet diff --git a/google-api-client-xml/pom.xml b/google-api-client-xml/pom.xml index 130e447bc..7d52776b0 100644 --- a/google-api-client-xml/pom.xml +++ b/google-api-client-xml/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml google-api-client-xml diff --git a/google-api-client/pom.xml b/google-api-client/pom.xml index dab63ed67..518cf64e0 100644 --- a/google-api-client/pom.xml +++ b/google-api-client/pom.xml @@ -4,7 +4,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 ../pom.xml google-api-client diff --git a/pom.xml b/pom.xml index d3369f576..4b7582fa8 100644 --- a/pom.xml +++ b/pom.xml @@ -9,7 +9,7 @@ com.google.api-client google-api-client-parent - 1.30.5-SNAPSHOT + 1.30.5 pom Parent for the Google API Client Library for Java diff --git a/versions.txt b/versions.txt index bd82a17a5..42c13b531 100644 --- a/versions.txt +++ b/versions.txt @@ -1,4 +1,4 @@ # Format: # module:released-version:current-version -google-api-client:1.30.4:1.30.5-SNAPSHOT +google-api-client:1.30.5:1.30.5