From b89d7d1de7254e798d0a9c23abf9c466c295c5c2 Mon Sep 17 00:00:00 2001 From: Thomas Coffee Date: Fri, 30 Jun 2017 15:25:51 -0700 Subject: [PATCH 1/4] Make Translate auth documentation clear and consistent Additional updates prompted by #1594 / #2147. --- README.md | 24 +++++++++---------- .../snippets/DetectLanguageAndTranslate.java | 5 ++-- google-cloud-translate/README.md | 6 ++--- .../google/cloud/translate/package-info.java | 15 ++++++------ 4 files changed, 26 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 4c18e989cd09..5fedecffe9b9 100644 --- a/README.md +++ b/README.md @@ -177,7 +177,7 @@ Storage storage = StorageOptions.getDefaultInstance().getService(); ``` If no credentials are provided, `google-cloud` will attempt to detect them from the environment -using `GoogleCredentials.getApplicationDefault()` which will search for Default Application +using `GoogleCredentials.getApplicationDefault()` which will search for Application Default Credentials in the following locations (in order): 1. The credentials file pointed to by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable @@ -497,8 +497,8 @@ Google Cloud Language (Beta) ### Preview -Here is a code snippet showing a simple usage example of LanguageServiceClient. The example assumes that either default application -credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) +Here is a code snippet showing a simple usage example of LanguageServiceClient. The example assumes that either Application Default +Credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) ```java try (LanguageServiceClient languageServiceClient = LanguageServiceClient.create()) { Document document = Document.newBuilder().build(); @@ -515,7 +515,7 @@ Google Cloud Vision (Beta) ### Preview Here is a code snippet showing a simple usage example of ImageAnnotatorClient. -The example assumes that either default application credentials or a valid API key +The example assumes that either Application Default Credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) ```java try (ImageAnnotatorClient imageAnnotatorClient = ImageAnnotatorClient.create()) { @@ -731,8 +731,8 @@ Google Translation (Beta) #### Preview Here's a snippet showing a simple usage example. The example shows how to detect the language of -some text and how to translate some text. The example assumes that either default application -credentials or a valid API key are available. An API key stored in the `GOOGLE_API_KEY` environment +some text and how to translate some text. The example assumes that either Application Default +Credentials or a valid API key are available. An API key stored in the `GOOGLE_API_KEY` environment variable will be automatically detected. Complete source code can be found at [DetectLanguageAndTranslate.java](./google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java). @@ -764,8 +764,8 @@ Google Cloud Speech (Alpha) ### Preview -Here is a code snippet showing a simple usage example of SpeechClient. The example assumes that either default application -credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) +Here is a code snippet showing a simple usage example of SpeechClient. The example assumes that either Application Default +Credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) Note that you must provide a uri to a FLAC audio file to run this. ```java @@ -794,8 +794,8 @@ Google Cloud Trace (Alpha) ### Preview -Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either default application -credentials or a valid API key are available. +Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either Application Default +Credentials or a valid API key are available. Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere. ```java try (TraceServiceClient traceServiceClient = TraceServiceClient.create()) { @@ -812,8 +812,8 @@ Google Cloud Video Intelligence (Alpha) ### Preview -Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either default application -credentials or a valid API key are available. +Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either Application Default +Credentials or a valid API key are available. Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere. ```java try (VideoIntelligenceServiceClient videoIntelligenceServiceClient = diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java index 6a65fefa16ef..b953b9f26230 100644 --- a/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java +++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java @@ -37,8 +37,9 @@ public class DetectLanguageAndTranslate { public static void main(String... args) { // Create a service object // - // Requests are authenticated using default application credentials if available; otherwise, - // using an API key from the GOOGLE_API_KEY environment variable + // If no explicit credentials or API key are set, requests are authenticated using Application + // Default Credentials if available; otherwise, using an API key from the GOOGLE_API_KEY + // environment variable Translate translate = TranslateOptions.getDefaultInstance().getService(); // Detect the language of some text diff --git a/google-cloud-translate/README.md b/google-cloud-translate/README.md index 284a80e6348b..0d1b656cc99d 100644 --- a/google-cloud-translate/README.md +++ b/google-cloud-translate/README.md @@ -80,7 +80,7 @@ section to add `google-cloud-translate` as a dependency in your code. #### Creating an authorized service object To make authenticated requests to Google Translation, you must create a service object with -credentials or with an API key. The simplest way to authenticate is to use +credentials or use an API key. The simplest way to authenticate is to use [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). These credentials are automatically inferred from your environment, so you only need the following code to create your service object: @@ -142,8 +142,8 @@ Translation translation = translate.translate( In [DetectLanguageAndTranslate.java](../google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java) -we put together all the code shown above into one program. The program assumes that either default -application credentials or a valid api key are available. +we put together all the code shown above into one program. The program assumes that either Application +Default Credentials or a valid API key are available. Troubleshooting --------------- diff --git a/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java b/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java index ef5bc85a8ead..aa8e9907d3ea 100644 --- a/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java +++ b/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java @@ -18,14 +18,15 @@ * A client to Google Translation. * *

Here's a simple usage example for using google-cloud. This example shows how to detect the - * language of some text and how to translate some text. The example assumes that the - * {@code GOOGLE_API_KEY} is set and contains a valid API key. Alternatively, you can use + * language of some text and how to translate some text. The example assumes that either Application + * Default Credentials are available or that the {@code GOOGLE_API_KEY} environment variable is set + * and contains a valid API key. Alternatively, you can use + * {@link ServiceOptions.Builder#setCredentials setCredentials} to set credentials, or * {@link com.google.cloud.translate.TranslateOptions.Builder#setApiKey(java.lang.String)} to set - * the API key. For the complete source code see - * - * DetectLanguageAndTranslate.java. - * 

 {@code
- * Translate translate = TranslateOptions.getDefaultInstance().getService();
+ * an API key. For the complete source code see 
+ * DetectLanguageAndTranslate.java.  
+ * {@code Translate translate = TranslateOptions.getDefaultInstance().getService();
  *
  * Detection detection = translate.detect("Hola");
  * String detectedLanguage = detection.getLanguage();

From 0171f0679bcc2cac8245e02eeea1266ddb1a1504 Mon Sep 17 00:00:00 2001
From: Thomas Coffee 
Date: Thu, 13 Jul 2017 16:30:19 -0700
Subject: [PATCH 2/4] Fix doc link

---
 .../src/main/java/com/google/cloud/translate/package-info.java  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java b/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java
index aa8e9907d3ea..f773eb000bf5 100644
--- a/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java
+++ b/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java
@@ -21,7 +21,7 @@
  * language of some text and how to translate some text. The example assumes that either Application
  * Default Credentials are available or that the {@code GOOGLE_API_KEY} environment variable is set
  * and contains a valid API key. Alternatively, you can use
- * {@link ServiceOptions.Builder#setCredentials setCredentials} to set credentials, or
+ * {@link com.google.cloud.ServiceOptions.Builder#setCredentials setCredentials} to set credentials, or
  * {@link com.google.cloud.translate.TranslateOptions.Builder#setApiKey(java.lang.String)} to set
  * an API key. For the complete source code see 

From 320a61b587f6831a51e183f1f03522c7215cc2d7 Mon Sep 17 00:00:00 2001
From: Thomas Coffee 
Date: Thu, 13 Jul 2017 18:17:01 -0700
Subject: [PATCH 3/4] Fix Spanner doc example

---
 .../src/main/java/com/google/cloud/spanner/DatabaseClient.java  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
index e7d18a9c9352..142253f9decd 100644
--- a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
+++ b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
@@ -222,7 +222,7 @@ public interface DatabaseClient {
    * long singerId = my_singer_id;
    * TransactionRunner runner = dbClient.readWriteTransaction();
    * runner.run(
-   *     new TransactionCallable() {
+   *     new TransactionCallable<Void>() {
    * 
    *       @Override
    *       public Void run(TransactionContext transaction) throws Exception {

From 8353ebd83b75c0ffa4975aa2b990a2abf40635fa Mon Sep 17 00:00:00 2001
From: Thomas Coffee 
Date: Thu, 13 Jul 2017 21:53:47 -0700
Subject: [PATCH 4/4] Work around Javadoc bug

https://bugs.openjdk.java.net/browse/JDK-8130754
---
 .../main/java/com/google/cloud/spanner/DatabaseClient.java  | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
index 142253f9decd..22e2bc8692ff 100644
--- a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
+++ b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
@@ -218,13 +218,13 @@ public interface DatabaseClient {
    * returned runner can only be used once.
    *
    * 
Example of a read write transaction.
-   * 
 {@code
+   * 
 
    * long singerId = my_singer_id;
    * TransactionRunner runner = dbClient.readWriteTransaction();
    * runner.run(
    *     new TransactionCallable<Void>() {
    * 
-   *       @Override
+   *       {@literal @}Override
    *       public Void run(TransactionContext transaction) throws Exception {
    *         String column = "FirstName";
    *         Struct row =
@@ -235,7 +235,7 @@ public interface DatabaseClient {
    *         return null;
    *       }
    *     });
-   * }

+   * 

    *
    */
   TransactionRunner readWriteTransaction();