diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..033a37caa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,51 @@ +--- +name: Bug report +about: Create a report to help us improve + +--- + +Thanks for stopping by to let us know something could be better! + +**PLEASE READ**: If you have a support contract with Google, please create an issue in the [support console](https://cloud.google.com/support/) instead of filing on GitHub. This will ensure a timely response. + +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 + - 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: + +#### Environment details + +1. Specify the API at the beginning of the title. For example, "BigQuery: ..."). + General, Core, and Other are also allowed as types +2. OS type and version: +3. Java version: +4. google-api-client version(s): + +#### Steps to reproduce + + 1. ? + 2. ? + +#### Code example + +```java +// example +``` + +#### Stack trace +``` +Any relevant stacktrace here. +``` + +#### External references such as API reference guides + +- ? + +#### Any additional information below + + +Following these steps guarantees the quickest resolution possible. + +Thanks! \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 000000000..754e30c68 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,21 @@ +--- +name: Feature request +about: Suggest an idea for this library + +--- + +Thanks for stopping by to let us know something could be better! + +**PLEASE READ**: If you have a support contract with Google, please create an issue in the [support console](https://cloud.google.com/support/) instead of filing on GitHub. This will ensure a timely response. + +**Is your feature request related to a problem? Please describe.** +What the problem is. Example: I'm always frustrated when [...] + +**Describe the solution you'd like** +What you want to happen. + +**Describe alternatives you've considered** +Any alternative solutions or features you've considered. + +**Additional context** +Any other context or screenshots about the feature request. diff --git a/.github/ISSUE_TEMPLATE/support_request.md b/.github/ISSUE_TEMPLATE/support_request.md new file mode 100644 index 000000000..995869032 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/support_request.md @@ -0,0 +1,7 @@ +--- +name: Support request +about: If you have a support contract with Google, please create an issue in the Google Cloud Support console. + +--- + +**PLEASE READ**: If you have a support contract with Google, please create an issue in the [support console](https://cloud.google.com/support/) instead of filing on GitHub. This will ensure a timely response. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3af206e9c..0bd0ee062 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,4 +1 @@ -Fixes # (it's a good idea to open an issue first for discussion) - -- [ ] Tests pass -- [ ] Appropriate docs were updated (if necessary) +Fixes # (it's a good idea to open an issue first for context and/or discussion) \ No newline at end of file diff --git a/.gitignore b/.gitignore index 62b082961..3ca4b1fa5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,32 @@ -target/ -bin/ -.classpath -.settings +.gitignore + +# Packages +dist +bin +var +sdist +target + +# Unit test / coverage reports +.coverage +.tox +nosetests.xml + +# Translations +*.mo + +# Mr Developer +.mr.developer.cfg .project +.pydevproject *.iml .idea +.settings +.DS_Store +.classpath + +# Built documentation +docs/ + +# Python utilities +*.pyc diff --git a/.kokoro/build.bat b/.kokoro/build.bat new file mode 100644 index 000000000..1d90ef3f2 --- /dev/null +++ b/.kokoro/build.bat @@ -0,0 +1,3 @@ +:: See documentation in type-shell-output.bat + +"C:\Program Files\Git\bin\bash.exe" github/google-api-java-client/.kokoro/build.sh diff --git a/.kokoro/build.sh b/.kokoro/build.sh index bc3321aef..2ffb5ef7f 100755 --- a/.kokoro/build.sh +++ b/.kokoro/build.sh @@ -1,5 +1,5 @@ #!/bin/bash -# Copyright 2018 Google Inc. +# 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. @@ -15,15 +15,40 @@ set -eo pipefail -cd github/google-api-java-client/ +## 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}/.. -# Print out Java +# Print out Java version java -version -echo $JOB_TYPE +echo ${JOB_TYPE} -# Skip android and assembly tests? Imported from Travis config -sed -i 's/google-api-client-android<\/module>//' pom.xml -sed -i 's/google-api-client-assembly<\/module>//' pom.xml +mvn install -B -V \ + -DskipTests=true \ + -Dmaven.javadoc.skip=true \ + -Dgcloud.download.skip=true \ + -T 1C -mvn install -DskipTests=true -Dmaven.javadoc.skip=true -B -V -mvn test -B +# if GOOGLE_APPLICATION_CREDIENTIALS is specified as a relative path prepend Kokoro root directory onto it +if [[ ! -z "${GOOGLE_APPLICATION_CREDENTIALS}" && "${GOOGLE_APPLICATION_CREDENTIALS}" != /* ]]; then + export GOOGLE_APPLICATION_CREDENTIALS=$(realpath ${KOKORO_ROOT}/src/${GOOGLE_APPLICATION_CREDENTIALS}) +fi + +case ${JOB_TYPE} in +test) + mvn test -B + bash ${KOKORO_GFILE_DIR}/codecov.sh + ;; +lint) + mvn com.coveo:fmt-maven-plugin:check + ;; +javadoc) + mvn javadoc:javadoc javadoc:test-javadoc + ;; +integration) + mvn -B ${INTEGRATION_TEST_ARGS} -DtrimStackTrace=false -fae verify + ;; +*) + ;; +esac \ No newline at end of file diff --git a/.kokoro/common.cfg b/.kokoro/common.cfg index 6a4f57d3b..7ba13c29d 100644 --- a/.kokoro/common.cfg +++ b/.kokoro/common.cfg @@ -8,6 +8,6 @@ build_file: "google-api-java-client/.kokoro/trampoline.sh" # Tell the trampoline which build file to use. env_vars: { - key: "TRAMPOLINE_BUILD_FILE" - value: "github/google-api-java-client/.kokoro/build.sh" + key: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/build.sh" } diff --git a/.kokoro/continuous/dependencies.cfg b/.kokoro/continuous/dependencies.cfg new file mode 100644 index 000000000..e23bcb07e --- /dev/null +++ b/.kokoro/continuous/dependencies.cfg @@ -0,0 +1,12 @@ +# 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: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/dependencies.sh" +} diff --git a/.kokoro/continuous/integration.cfg b/.kokoro/continuous/integration.cfg new file mode 100644 index 000000000..3b017fc80 --- /dev/null +++ b/.kokoro/continuous/integration.cfg @@ -0,0 +1,7 @@ +# 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" +} diff --git a/.kokoro/continuous/java8-osx.cfg b/.kokoro/continuous/java8-osx.cfg new file mode 100644 index 000000000..59d051c1b --- /dev/null +++ b/.kokoro/continuous/java8-osx.cfg @@ -0,0 +1,3 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +build_file: "google-api-java-client/.kokoro/build.sh" diff --git a/.kokoro/continuous/java8-win.cfg b/.kokoro/continuous/java8-win.cfg new file mode 100644 index 000000000..a4d91e3ca --- /dev/null +++ b/.kokoro/continuous/java8-win.cfg @@ -0,0 +1,3 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +build_file: "google-api-java-client/.kokoro/build.bat" diff --git a/.kokoro/continuous/lint.cfg b/.kokoro/continuous/lint.cfg new file mode 100644 index 000000000..6d323c8ae --- /dev/null +++ b/.kokoro/continuous/lint.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: "lint" +} \ No newline at end of file diff --git a/.kokoro/continuous/propose_release.cfg b/.kokoro/continuous/propose_release.cfg new file mode 100644 index 000000000..d192d119e --- /dev/null +++ b/.kokoro/continuous/propose_release.cfg @@ -0,0 +1,53 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +# Build logs will be here +action { + define_artifacts { + regex: "**/*sponge_log.xml" + } +} + +# Download trampoline resources. +gfile_resources: "/bigstore/cloud-devrel-kokoro-resources/trampoline" + +# Use the trampoline script to run in docker. +build_file: "google-api-java-client/.kokoro/trampoline.sh" + +# Configure the docker image for kokoro-trampoline. +env_vars: { + key: "TRAMPOLINE_IMAGE" + value: "gcr.io/cloud-devrel-kokoro-resources/node:10-user" +} + +env_vars: { + key: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/release/bump_snapshot.sh" +} + +# tokens used by release-please to keep an up-to-date release PR. +before_action { + fetch_keystore { + keystore_resource { + keystore_config_id: 73713 + keyname: "github-magic-proxy-key-release-please" + } + } +} + +before_action { + fetch_keystore { + keystore_resource { + keystore_config_id: 73713 + keyname: "github-magic-proxy-token-release-please" + } + } +} + +before_action { + fetch_keystore { + keystore_resource { + keystore_config_id: 73713 + keyname: "github-magic-proxy-url-release-please" + } + } +} diff --git a/.kokoro/continuous/propose_release.sh b/.kokoro/continuous/propose_release.sh new file mode 100644 index 000000000..9f0a5979e --- /dev/null +++ b/.kokoro/continuous/propose_release.sh @@ -0,0 +1,29 @@ +#!/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 +# +# https://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. + +set -eo pipefail + +export NPM_CONFIG_PREFIX=/home/node/.npm-global + +if [ -f ${KOKORO_KEYSTORE_DIR}/73713_github-magic-proxy-url-release-please ]; then + # Groom the release PR as new commits are merged. + npx release-please release-pr --token=${KOKORO_KEYSTORE_DIR}/73713_github-magic-proxy-token-release-please \ + --repo-url=googleapis/google-api-java-client \ + --package-name="google-api-client" \ + --api-url=${KOKORO_KEYSTORE_DIR}/73713_github-magic-proxy-url-release-please \ + --proxy-key=${KOKORO_KEYSTORE_DIR}/73713_github-magic-proxy-key-release-please \ + --release-type=java-auth-yoshi +fi diff --git a/.kokoro/dependencies.sh b/.kokoro/dependencies.sh new file mode 100755 index 000000000..e7faa9b61 --- /dev/null +++ b/.kokoro/dependencies.sh @@ -0,0 +1,27 @@ +#!/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. + +set -eo pipefail + +cd github/google-api-java-client/ + +# Print out Java +java -version +echo $JOB_TYPE + +export MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=128m" + +mvn install -DskipTests=true -B -V +mvn -B dependency:analyze -DfailOnWarning=true diff --git a/.kokoro/linkage-monitor.sh b/.kokoro/linkage-monitor.sh new file mode 100755 index 000000000..343eb763a --- /dev/null +++ b/.kokoro/linkage-monitor.sh @@ -0,0 +1,33 @@ +#!/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. + +set -eo pipefail +# Display commands being run. +set -x + +cd github/google-api-java-client/ + +# Print out Java version +java -version +echo ${JOB_TYPE} + +mvn install -DskipTests=true -Dmaven.javadoc.skip=true -Dgcloud.download.skip=true -B -V + +# Kokoro job cloud-opensource-java/ubuntu/linkage-monitor-gcs creates this JAR +JAR=linkage-monitor-latest-all-deps.jar +curl -v -O "https://storage.googleapis.com/cloud-opensource-java-linkage-monitor/${JAR}" + +# Fails if there's new linkage errors compared with baseline +java -jar ${JAR} com.google.cloud:libraries-bom diff --git a/.kokoro/nightly/common.cfg b/.kokoro/nightly/common.cfg new file mode 100644 index 000000000..7c562d48d --- /dev/null +++ b/.kokoro/nightly/common.cfg @@ -0,0 +1,24 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +# Build logs will be here +action { + define_artifacts { + regex: "**/*sponge_log.xml" + } +} + +# Download trampoline resources. +gfile_resources: "/bigstore/cloud-devrel-kokoro-resources/trampoline" + +# Use the trampoline script to run in docker. +build_file: "google-api-java-client/.kokoro/trampoline.sh" + +env_vars: { + key: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/build.sh" +} + +env_vars: { + key: "JOB_TYPE" + value: "test" +} diff --git a/.kokoro/nightly/dependencies.cfg b/.kokoro/nightly/dependencies.cfg new file mode 100644 index 000000000..e23bcb07e --- /dev/null +++ b/.kokoro/nightly/dependencies.cfg @@ -0,0 +1,12 @@ +# 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: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/dependencies.sh" +} diff --git a/.kokoro/nightly/integration.cfg b/.kokoro/nightly/integration.cfg new file mode 100644 index 000000000..3b017fc80 --- /dev/null +++ b/.kokoro/nightly/integration.cfg @@ -0,0 +1,7 @@ +# 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" +} diff --git a/.kokoro/nightly/java11.cfg b/.kokoro/nightly/java11.cfg new file mode 100644 index 000000000..709f2b4c7 --- /dev/null +++ b/.kokoro/nightly/java11.cfg @@ -0,0 +1,7 @@ +# 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/java11" +} diff --git a/.kokoro/nightly/java7.cfg b/.kokoro/nightly/java7.cfg new file mode 100644 index 000000000..cb24f44ee --- /dev/null +++ b/.kokoro/nightly/java7.cfg @@ -0,0 +1,7 @@ +# 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/java7" +} diff --git a/.kokoro/nightly/java8-osx.cfg b/.kokoro/nightly/java8-osx.cfg new file mode 100644 index 000000000..59d051c1b --- /dev/null +++ b/.kokoro/nightly/java8-osx.cfg @@ -0,0 +1,3 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +build_file: "google-api-java-client/.kokoro/build.sh" diff --git a/.kokoro/nightly/java8-win.cfg b/.kokoro/nightly/java8-win.cfg new file mode 100644 index 000000000..a4d91e3ca --- /dev/null +++ b/.kokoro/nightly/java8-win.cfg @@ -0,0 +1,3 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +build_file: "google-api-java-client/.kokoro/build.bat" diff --git a/.kokoro/nightly/java8.cfg b/.kokoro/nightly/java8.cfg new file mode 100644 index 000000000..3b017fc80 --- /dev/null +++ b/.kokoro/nightly/java8.cfg @@ -0,0 +1,7 @@ +# 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" +} diff --git a/.kokoro/nightly/lint.cfg b/.kokoro/nightly/lint.cfg new file mode 100644 index 000000000..6d323c8ae --- /dev/null +++ b/.kokoro/nightly/lint.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: "lint" +} \ No newline at end of file diff --git a/.kokoro/presubmit/common.cfg b/.kokoro/presubmit/common.cfg index 7c562d48d..fd684c7e1 100644 --- a/.kokoro/presubmit/common.cfg +++ b/.kokoro/presubmit/common.cfg @@ -22,3 +22,12 @@ env_vars: { key: "JOB_TYPE" value: "test" } + +before_action { + fetch_keystore { + keystore_resource { + keystore_config_id: 73713 + keyname: "dpebot_codecov_token" + } + } +} diff --git a/.kokoro/presubmit/dependencies.cfg b/.kokoro/presubmit/dependencies.cfg new file mode 100644 index 000000000..e23bcb07e --- /dev/null +++ b/.kokoro/presubmit/dependencies.cfg @@ -0,0 +1,12 @@ +# 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: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/dependencies.sh" +} diff --git a/.kokoro/presubmit/integration.cfg b/.kokoro/presubmit/integration.cfg new file mode 100644 index 000000000..3b017fc80 --- /dev/null +++ b/.kokoro/presubmit/integration.cfg @@ -0,0 +1,7 @@ +# 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" +} diff --git a/.kokoro/presubmit/java8-osx.cfg b/.kokoro/presubmit/java8-osx.cfg new file mode 100644 index 000000000..59d051c1b --- /dev/null +++ b/.kokoro/presubmit/java8-osx.cfg @@ -0,0 +1,3 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +build_file: "google-api-java-client/.kokoro/build.sh" diff --git a/.kokoro/presubmit/java8-win.cfg b/.kokoro/presubmit/java8-win.cfg new file mode 100644 index 000000000..a4d91e3ca --- /dev/null +++ b/.kokoro/presubmit/java8-win.cfg @@ -0,0 +1,3 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +build_file: "google-api-java-client/.kokoro/build.bat" diff --git a/.kokoro/presubmit/linkage-monitor.cfg b/.kokoro/presubmit/linkage-monitor.cfg new file mode 100644 index 000000000..5bb77dd41 --- /dev/null +++ b/.kokoro/presubmit/linkage-monitor.cfg @@ -0,0 +1,12 @@ +# 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: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/linkage-monitor.sh" +} \ No newline at end of file diff --git a/.kokoro/presubmit/lint.cfg b/.kokoro/presubmit/lint.cfg new file mode 100644 index 000000000..6d323c8ae --- /dev/null +++ b/.kokoro/presubmit/lint.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: "lint" +} \ No newline at end of file diff --git a/.kokoro/release/bump_snapshot.cfg b/.kokoro/release/bump_snapshot.cfg new file mode 100644 index 000000000..d192d119e --- /dev/null +++ b/.kokoro/release/bump_snapshot.cfg @@ -0,0 +1,53 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +# Build logs will be here +action { + define_artifacts { + regex: "**/*sponge_log.xml" + } +} + +# Download trampoline resources. +gfile_resources: "/bigstore/cloud-devrel-kokoro-resources/trampoline" + +# Use the trampoline script to run in docker. +build_file: "google-api-java-client/.kokoro/trampoline.sh" + +# Configure the docker image for kokoro-trampoline. +env_vars: { + key: "TRAMPOLINE_IMAGE" + value: "gcr.io/cloud-devrel-kokoro-resources/node:10-user" +} + +env_vars: { + key: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/release/bump_snapshot.sh" +} + +# tokens used by release-please to keep an up-to-date release PR. +before_action { + fetch_keystore { + keystore_resource { + keystore_config_id: 73713 + keyname: "github-magic-proxy-key-release-please" + } + } +} + +before_action { + fetch_keystore { + keystore_resource { + keystore_config_id: 73713 + keyname: "github-magic-proxy-token-release-please" + } + } +} + +before_action { + fetch_keystore { + keystore_resource { + keystore_config_id: 73713 + keyname: "github-magic-proxy-url-release-please" + } + } +} diff --git a/.kokoro/release/bump_snapshot.sh b/.kokoro/release/bump_snapshot.sh new file mode 100644 index 000000000..6ebc38ad0 --- /dev/null +++ b/.kokoro/release/bump_snapshot.sh @@ -0,0 +1,30 @@ +#!/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 +# +# https://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. + +set -eo pipefail + +export NPM_CONFIG_PREFIX=/home/node/.npm-global + +if [ -f ${KOKORO_KEYSTORE_DIR}/73713_github-magic-proxy-url-release-please ]; then + # Groom the snapshot release PR immediately after publishing a release + npx release-please release-pr --token=${KOKORO_KEYSTORE_DIR}/73713_github-magic-proxy-token-release-please \ + --repo-url=googleapis/google-api-java-client \ + --package-name="google-api-client" \ + --api-url=${KOKORO_KEYSTORE_DIR}/73713_github-magic-proxy-url-release-please \ + --proxy-key=${KOKORO_KEYSTORE_DIR}/73713_github-magic-proxy-key-release-please \ + --snapshot \ + --release-type=java-auth-yoshi +fi diff --git a/.kokoro/release/common.cfg b/.kokoro/release/common.cfg index 73e295f10..ea8de3624 100644 --- a/.kokoro/release/common.cfg +++ b/.kokoro/release/common.cfg @@ -1,12 +1,5 @@ # Format: //devtools/kokoro/config/proto/build.proto -# Build logs will be here -action { - define_artifacts { - regex: "**/*sponge_log.xml" - } -} - # Download trampoline resources. gfile_resources: "/bigstore/cloud-devrel-kokoro-resources/trampoline" diff --git a/.kokoro/release/common.sh b/.kokoro/release/common.sh old mode 100644 new mode 100755 index f7d538b3a..6e3f65999 --- a/.kokoro/release/common.sh +++ b/.kokoro/release/common.sh @@ -47,4 +47,4 @@ create_settings_xml_file() { " > $1 -} +} \ No newline at end of file diff --git a/.kokoro/release/drop.cfg b/.kokoro/release/drop.cfg index 395a94c00..cd34c356b 100644 --- a/.kokoro/release/drop.cfg +++ b/.kokoro/release/drop.cfg @@ -1,7 +1,9 @@ # Format: //devtools/kokoro/config/proto/build.proto -# Tell the trampoline which build file to use. env_vars: { - key: "TRAMPOLINE_BUILD_FILE" - value: "github/google-api-java-client/.kokoro/release/drop.sh" + key: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/release/drop.sh" } + +# Download staging properties file. +gfile_resources: "/bigstore/cloud-devrel-kokoro-resources/java/releases/google-api-java-client" \ No newline at end of file diff --git a/.kokoro/release/promote.cfg b/.kokoro/release/promote.cfg index 8703880cd..a9520917c 100644 --- a/.kokoro/release/promote.cfg +++ b/.kokoro/release/promote.cfg @@ -1,7 +1,10 @@ # Format: //devtools/kokoro/config/proto/build.proto -# Tell the trampoline which build file to use. env_vars: { - key: "TRAMPOLINE_BUILD_FILE" - value: "github/google-api-java-client/.kokoro/release/promote.sh" + key: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/release/promote.sh" } + +# Download staging properties file. +gfile_resources: "/bigstore/cloud-devrel-kokoro-resources/java/releases/google-api-java-client" + diff --git a/.kokoro/release/publish_javadoc.cfg b/.kokoro/release/publish_javadoc.cfg index 0cf24e1b5..cf25be2a6 100644 --- a/.kokoro/release/publish_javadoc.cfg +++ b/.kokoro/release/publish_javadoc.cfg @@ -1,12 +1,12 @@ # Format: //devtools/kokoro/config/proto/build.proto env_vars: { - key: "STAGING_BUCKET" - value: "docs-staging" + key: "STAGING_BUCKET" + value: "docs-staging" } env_vars: { - key: "TRAMPOLINE_BUILD_FILE" - value: "github/google-api-java-client/.kokoro/release/publish_javadoc.sh" + key: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/release/publish_javadoc.sh" } before_action { diff --git a/.kokoro/release/publish_javadoc.sh b/.kokoro/release/publish_javadoc.sh index d231b3da6..48f82f4e8 100755 --- a/.kokoro/release/publish_javadoc.sh +++ b/.kokoro/release/publish_javadoc.sh @@ -37,7 +37,7 @@ NAME=google-api-client VERSION=$(grep ${NAME}: versions.txt | cut -d: -f3) # build the docs -mvn site +mvn site -B pushd target/site/apidocs diff --git a/.kokoro/release/snapshot.cfg b/.kokoro/release/snapshot.cfg new file mode 100644 index 000000000..166c105ba --- /dev/null +++ b/.kokoro/release/snapshot.cfg @@ -0,0 +1,6 @@ +# Format: //devtools/kokoro/config/proto/build.proto + +env_vars: { + key: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/release/snapshot.sh" +} \ No newline at end of file diff --git a/.kokoro/release/snapshot.sh b/.kokoro/release/snapshot.sh new file mode 100644 index 000000000..bf738c56d --- /dev/null +++ b/.kokoro/release/snapshot.sh @@ -0,0 +1,30 @@ +#!/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. + +set -eo pipefail + +source $(dirname "$0")/common.sh +MAVEN_SETTINGS_FILE=$(realpath $(dirname "$0")/../../)/settings.xml +pushd $(dirname "$0")/../../ + +setup_environment_secrets +create_settings_xml_file "settings.xml" + +mvn clean install deploy -B \ + --settings ${MAVEN_SETTINGS_FILE} \ + -DperformRelease=true \ + -Dgpg.executable=gpg \ + -Dgpg.passphrase=${GPG_PASSPHRASE} \ + -Dgpg.homedir=${GPG_HOMEDIR} \ No newline at end of file diff --git a/.kokoro/release/stage.cfg b/.kokoro/release/stage.cfg index 8defcfb20..7de6d9acb 100644 --- a/.kokoro/release/stage.cfg +++ b/.kokoro/release/stage.cfg @@ -1,9 +1,16 @@ # Format: //devtools/kokoro/config/proto/build.proto -# Tell the trampoline which build file to use. env_vars: { - key: "TRAMPOLINE_BUILD_FILE" - value: "github/google-api-java-client/.kokoro/release/stage.sh" + key: "TRAMPOLINE_BUILD_FILE" + value: "github/google-api-java-client/.kokoro/release/stage.sh" +} + +# Need to save the properties file +action { + define_artifacts { + regex: "github/google-api-java-client/target/nexus-staging/staging/*.properties" + strip_prefix: "github/google-api-java-client" + } } # Fetch the token needed for reporting release status to GitHub diff --git a/.kokoro/release/stage.sh b/.kokoro/release/stage.sh index 16b44a403..b1b1b01c6 100755 --- a/.kokoro/release/stage.sh +++ b/.kokoro/release/stage.sh @@ -20,24 +20,22 @@ python3 -m pip install gcp-releasetool python3 -m releasetool publish-reporter-script > /tmp/publisher-script; source /tmp/publisher-script source $(dirname "$0")/common.sh -source $(dirname "$0")/../install_dependencies.sh - +MAVEN_SETTINGS_FILE=$(realpath $(dirname "$0")/../../)/settings.xml pushd $(dirname "$0")/../../ setup_environment_secrets create_settings_xml_file "settings.xml" mvn clean install deploy -B \ - --settings settings.xml \ + --settings ${MAVEN_SETTINGS_FILE} \ -DperformRelease=true \ -Dgpg.executable=gpg \ -Dgpg.passphrase=${GPG_PASSPHRASE} \ -Dgpg.homedir=${GPG_HOMEDIR} - if [[ -n "${AUTORELEASE_PR}" ]] then mvn nexus-staging:release -B \ -DperformRelease=true \ --settings=settings.xml -fi +fi \ No newline at end of file diff --git a/.repo-metadata.json b/.repo-metadata.json new file mode 100644 index 000000000..a43864403 --- /dev/null +++ b/.repo-metadata.json @@ -0,0 +1,10 @@ +{ + "name": "google-api-client", + "name_pretty": "Google API Java Client", + "client_documentation": "https://googleapis.dev/java/google-api-client/latest/", + "release_level": "ga", + "language": "java", + "repo": "googleapis/google-api-java-client", + "repo_short": "google-api-java-client", + "distribution_name": "google-api-java-client" +} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 46b2a08ea..f3e2cc574 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,43 +1,93 @@ -# Contributor Code of Conduct +# Code of Conduct -As contributors and maintainers of this project, -and in the interest of fostering an open and welcoming community, -we pledge to respect all people who contribute through reporting issues, -posting feature requests, updating documentation, -submitting pull requests or patches, and other activities. +## Our Pledge -We are committed to making participation in this project -a harassment-free experience for everyone, -regardless of level of experience, gender, gender identity and expression, -sexual orientation, disability, personal appearance, -body size, race, ethnicity, age, religion, or nationality. +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of +experience, education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery -* Personal attacks -* Trolling or insulting/derogatory comments -* Public or private harassment -* Publishing other's private information, -such as physical or electronic -addresses, without explicit permission -* Other unethical or unprofessional conduct. +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct. -By adopting this Code of Conduct, -project maintainers commit themselves to fairly and consistently -applying these principles to every aspect of managing this project. -Project maintainers who do not follow or enforce the Code of Conduct -may be permanently removed from the project team. - -This code of conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. - -Instances of abusive, harassing, or otherwise unacceptable behavior -may be reported by opening an issue -or contacting one or more of the project maintainers. - -This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, -available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/) +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, or to ban temporarily or permanently any +contributor for other behaviors that they deem inappropriate, threatening, +offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +This Code of Conduct also applies outside the project spaces when the Project +Steward has a reasonable belief that an individual's behavior may have a +negative impact on the project or its community. + +## Conflict Resolution + +We do not believe that all conflict is bad; healthy debate and disagreement +often yield positive results. However, it is never okay to be disrespectful or +to engage in behavior that violates the project’s code of conduct. + +If you see someone violating the code of conduct, you are encouraged to address +the behavior directly with those involved. Many issues can be resolved quickly +and easily, and this gives people more control over the outcome of their +dispute. If you are unable to resolve the matter for any reason, or if the +behavior is threatening or harassing, report it. We are dedicated to providing +an environment where participants feel welcome and safe. + +Reports should be directed to Jeff Ching , the +Project Steward for google-api-java-client. It is the Project Steward’s duty to +receive and address reported violations of the code of conduct. They will then +work with a committee consisting of representatives from the Open Source +Programs Office and the Google Open Source Strategy team. If for any reason you +are uncomfortable reaching out the Project Steward, please email +opensource@google.com. + +We will investigate every complaint, but you may not receive a direct response. +We will use our discretion in determining when and how to follow up on reported +incidents, which may range from not taking action to permanent expulsion from +the project and project-sponsored spaces. We will notify the accused of the +report and provide them an opportunity to discuss it before any action is taken. +The identity of the reporter will be omitted from the details of the report +supplied to the accused. In potentially harmful situations, such as ongoing +harassment or threats to anyone's safety, we may take action without notice. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 1.4, +available at +https://www.contributor-covenant.org/version/1/4/code-of-conduct.html \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..ebbb59e53 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,28 @@ +# How to Contribute + +We'd love to accept your patches and contributions to this project. There are +just a few small guidelines you need to follow. + +## Contributor License Agreement + +Contributions to this project must be accompanied by a Contributor License +Agreement. You (or your employer) retain the copyright to your contribution; +this simply gives us permission to use and redistribute your contributions as +part of the project. Head over to to see +your current agreements on file or to sign a new one. + +You generally only need to submit a CLA once, so if you've already submitted one +(even if it was for a different project), you probably don't need to do it +again. + +## Code reviews + +All submissions, including submissions by project members, require review. We +use GitHub pull requests for this purpose. Consult +[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more +information on using pull requests. + +## Community Guidelines + +This project follows +[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/). \ No newline at end of file diff --git a/LICENSE b/LICENSE index 980a15ac2..d64569567 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,5 @@ - Apache License + + Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ @@ -178,7 +179,7 @@ APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" + boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a @@ -186,7 +187,7 @@ same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright {yyyy} {name of copyright owner} + Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/README.md b/README.md index 4259fa719..438db361e 100644 --- a/README.md +++ b/README.md @@ -1,383 +1,29 @@ # Google APIs Client Library for Java -- [Library Maintenance](#maintenance) -- [Overview](#Overview) -- [Highlighted Features](#Highlighted_Features) -- [Dependencies](#Dependencies) -- [Important Warnings](#Beta) - - [@Beta](#Beta) - - [Deprecations](#Deprecations) -- [Documentation](#Documentation) -- [Links](#Links) - -## Library Maintenance -These client libraries are officially supported by Google. However, these libraries are considered complete and are in maintenance mode. This means that we will address critical bugs and security issues, but will not add any new features. If you're working with **Google Cloud Platform** APIs such as Datastore, Pub/Sub and many others, -consider using the [Cloud Client Libraries for Java](https://github.com/googleapis/google-cloud-java) -instead. These are the new and idiomatic Java libraries targeted specifically at Google Cloud -Platform Services. - -## Building locally - -##### One time setup - -``` -mkdir /tmp/foo && cd /tmp/foo -wget https://dl.google.com/dl/android/maven2/com/google/android/gms/play-services-basement/8.3.0/play-services-basement-8.3.0.aar -unzip play-services-basement-8.3.0.aar -mvn install:install-file \ - -Dfile=classes.jar \ - -DgroupId=com.google.android.google-play-services \ - -DartifactId=google-play-services \ - -Dversion=1 \ - -Dpackaging=jar -cd - - -# we need the google-http-java-client jar cached locally -git clone https://github.com/google/google-http-java-client.git -cd google-http-java-client && mvn compile && mvn install && cd .. - -# we need the google-oauth-java-client jar cached locally -git clone https://github.com/google/google-oauth-java-client.git -cd google-oauth-java-client && mvn compile && mvn install -``` - -##### Building And Testing - -``` -mvn install -``` - -## 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](https://developers.google.com/api-client-library/java/google-api-java-client/oauth2) library with a consistent interface. + - A powerful [OAuth 2.0](https://github.com/googleapis/google-api-java-client/wiki/OAuth2) library with a consistent interface. - Lightweight, efficient XML and JSON data models that support any data schema. - Support for [protocol buffers](https://github.com/google/protobuf/). - - A set of [generated libraries for Google APIs](https://developers.google.com/api-client-library/java/apis/). - -### 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](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). -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](https://developers.google.com/api-client-library/java/apis/). -The API-specific Java packages include both the core google-api-java-client and the client-specific -libraries. - -If you are using the old GData library, you need to -[migrate](https://github.com/google/gdata-java-client/blob/wiki/MigratingToGoogleApiJavaClient.md). - -### Developing for Android + - A set of [generated libraries for Google APIs](https://github.com/googleapis/google-api-java-client-services#supported-google-apis). -If you are developing for Android and the Google API you want to use is included in the -[Google Play Services library](https://developer.android.com/google/play-services/index.html), use that library for the best performance and experience. - -To access other Google APIs, use the Google APIs Client Library for Java, which supports -[Android 4.0 (Ice Cream Sandwich) (or higher)](https://developers.google.com/api-client-library/java/google-api-java-client/android). - -### Other Java environments +## Supported Java environments - Java 7 (or higher) - Android 1.6 (or higher) -- [Google App Engine](https://developers.google.com/api-client-library/java/google-api-java-client/app-engine) - -## Highlighted Features - -### Simple to call Google APIs - -You can call Google APIs using Google service-specific generated libraries with the Google APIs -Client Library for Java. Here's an example that makes a call to the -[Google Calendar API](https://developers.google.com/google-apps/calendar/): - -```java -// Show events on user's calendar. -View.header("Show Calendars"); -CalendarList feed = client.calendarList().list().execute(); -View.display(feed); -``` - -### Authentication - -The authentication library can reduce the amount of code needed to handle -[OAuth 2.0](https://developers.google.com/api-client-library/java/google-api-java-client/oauth2), -and sometimes a few lines is all you need. For example: - -```java -/** Authorizes the installed application to access user's protected data. */ -private static Credential authorize() throws Exception { - // load client secrets - GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(JSON_FACTORY, - new InputStreamReader(CalendarSample.class.getResourceAsStream("/client_secrets.json"))); - // set up authorization code flow - GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder( - httpTransport, JSON_FACTORY, clientSecrets, - Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory(dataStoreFactory) - .build(); - // authorize - return new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user"); -} -``` - -### 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(); -``` - -### 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 +- [Google App Engine](https://github.com/googleapis/google-api-java-client/wiki/App-Engine) -The main classes of interest are [MediaHttpUploader][media-http-uploader] and -[MediaHttpProgressListener][media-http-progress-listener]. +## Usage -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 detailed instructions on usage, please visit the [wiki](https://github.com/googleapis/google-api-java-client/wiki). -For example, the `insert` method of the Drive API supports `mediaUpload`, and you can use the following code to upload a -file: +## Installation -```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); -``` - -### 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); -``` - -### Running on Google App Engine - -[App Engine-specific helpers](https://developers.google.com/api-client-library/java/google-api-java-client/app-engine) -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(); - ... -} -``` - -### 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](https://developer.android.com/google/play-services/index.html), -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](http://developer.android.com/reference/android/accounts/AccountManager.html). -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(); -} -``` - -### Installation - -The Google APIs Client Library for Java is easy to install, and you can download the binary -directly from the [Downloads page](https://developers.google.com/api-client-library/java/google-api-java-client/download), -or you can use Maven or Gradle. +The Google APIs Client Library for Java is easy to install. To use Maven, add the following lines to your pom.xml file: @@ -406,6 +52,24 @@ dependencies { ``` [//]: # ({x-version-update-end}) + +## Building locally + +## One time setup + +``` +mkdir /tmp/foo && cd /tmp/foo +wget https://dl.google.com/dl/android/maven2/com/google/android/gms/play-services-basement/8.3.0/play-services-basement-8.3.0.aar +unzip play-services-basement-8.3.0.aar +mvn install:install-file \ + -Dfile=classes.jar \ + -DgroupId=com.google.android.google-play-services \ + -DartifactId=google-play-services \ + -Dversion=1 \ + -Dpackaging=jar +cd - +``` + ## CI Status Java Version | Status @@ -438,26 +102,17 @@ might result, and you are not guaranteed a compilation error. ## Documentation -- [Developer's Guide](https://developers.google.com/api-client-library/java/google-api-java-client/dev-guide) -- [Libraries and Samples](https://developers.google.com/api-client-library/java/apis/) +- [Libraries and Samples](https://github.com/googleapis/google-api-java-client-services/) - [JavaDoc](https://googleapis.dev/java/google-api-client/latest/) -- [Get Help](https://developers.google.com/api-client-library/java/google-api-java-client/support) -## Links +## Contributing -- [Discuss](https://groups.google.com/forum/#!forum/google-api-java-client) +Contributions to this library are always welcome and highly encouraged. -For questions or concerns, please file an issue in the GitHub repository. +See [CONTRIBUTING](CONTRIBUTING.md) documentation for more information on how to get started. + +Please note that this project is released with a Contributor Code of Conduct. By participating in +this project you agree to abide by its terms. See [Code of Conduct](CODE_OF_CONDUCT.md) for more +information. -[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 -[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]: ./Resumable-Media-Upload-Sequence-Diagram.png -[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 +For questions or concerns, please file an issue in the GitHub repository. diff --git a/codecov.yaml b/codecov.yaml new file mode 100644 index 000000000..5724ea947 --- /dev/null +++ b/codecov.yaml @@ -0,0 +1,4 @@ +--- +codecov: + ci: + - source.cloud.google.com diff --git a/synth.metadata b/synth.metadata new file mode 100644 index 000000000..a3f263b4e --- /dev/null +++ b/synth.metadata @@ -0,0 +1,12 @@ +{ + "updateTime": "2019-08-19T17:59:15.646987Z", + "sources": [ + { + "template": { + "name": "java_library", + "origin": "synthtool.gcp", + "version": "2019.5.2" + } + } + ] +} \ No newline at end of file diff --git a/synth.py b/synth.py new file mode 100644 index 000000000..61dfd4323 --- /dev/null +++ b/synth.py @@ -0,0 +1,30 @@ + +# 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 is used to synthesize generated parts of this library.""" +import synthtool as s +import synthtool.gcp as gcp +import logging + +logging.basicConfig(level=logging.DEBUG) +common_templates = gcp.CommonTemplates() +templates = common_templates.java_library() +s.copy(templates, excludes=[ + "README.md", + "java.header", + "checkstyle.xml", + "renovate.json", + "license-checks.xml", + "CODE_OF_CONDUCT.md", +])