From dac0698fb243f98ec816fedaba23346f2a9ced0b Mon Sep 17 00:00:00 2001
From: Ajay Kannan <ajaykannan@google.com>
Date: Tue, 29 Mar 2016 18:41:32 -0700
Subject: [PATCH] Clean up local gcd helper and docs

---
 TESTING.md                                    | 23 ++++++++++---------
 .../datastore/testing/LocalGcdHelper.java     | 19 ++++++++++++++-
 .../datastore/testing/package-info.java       |  8 ++-----
 .../gcloud/datastore/DatastoreTest.java       | 10 ++------
 4 files changed, 34 insertions(+), 26 deletions(-)

diff --git a/TESTING.md b/TESTING.md
index 3ad181310b17..f82f76f4db73 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -14,22 +14,22 @@ This library provides tools to help write tests for code that uses the following
 You can test against a temporary local datastore by following these steps:
 
 1. Start the local datastore emulator using `LocalGcdHelper`.  This can be done in two ways:
-  - Run `LocalGcdHelper.java`'s `main` method with arguments `START` and (optionally) `--port=<port number>`.  This will create a temporary folder on your computer and bind `localhost:<port number>` for communication with the local datastore.  The port number is an optional argument.  If no port number is specified, port 8080 will be used.
-  - Call `LocalGcdHelper.start(<project ID>, <port number>)` before running your tests.  Save the `LocalGcdHelper` object returned so that you can stop the emulator later.
-
-2. In your program, create and use a datastore whose host is set host to `localhost:<port number>`.  For example, 
+  - Run `LocalGcdHelper.java`'s `main` method with `START` provided as an argument, followed by optional arguments `--port=<port number>` and `--consistency=<float between 0 and 1, inclusive>`.  This will create a temporary folder on your computer and bind `localhost:<port number>` for communication with the local datastore.  If no port number is specified, port 8080 will be used.  The consistency setting controls the fraction of Datastore writes that are immediately visible in global queries.
+  - Use the `LocalGcdHelper.start(String projectId, int port, double consistency)` method before running your tests. For example, you can use the following code to start the local Datastore on any available port with the consistency set to 0.9:
+    ```java
+    int port = LocalGcdHelper.findAvailablePort(LocalGcdHelper.DEFAULT_PORT);
+    LocalGcdHelper helper = LocalGcdHelper.start("my-project-id", port, 0.9);
+    ```
+
+2. In your program, create and use a `Datastore` object with the options given by the `LocalGcdHelper` instance.  For example:
   ```java
-  DatastoreOptions options = DatastoreOptions.builder()
-      .projectId(PROJECT_ID)
-      .host("http://localhost:8080")
-      .build();
-  Datastore localDatastore = options.service();
+  Datastore localDatastore = helper.options().service()
   ```
 3. Run your tests.
 
 4. Stop the local datastore emulator.
   - If you ran `LocalGcdHelper.java`'s `main` function to start the emulator, run `LocalGcdHelper.java`'s `main` method with arguments `STOP` and (optionally) `--port=<port number>`.  If the port is not supplied, the program will attempt to close the last port started.
-  - If you ran `LocalGcdHelper.start()` to start the emulator, call the `stop()` method on the `LocalGcdHelper` object returned by `LocalGcdHelper.start()`.
+  - If you ran the `LocalGcdHelper.start` method to start the emulator, call the `stop()` method on the `LocalGcdHelper` object returned by `LocalGcdHelper.start`.
 
 #### On a remote machine
 
@@ -39,6 +39,7 @@ You can test against a remote datastore emulator as well.  To do this, set the `
   DatastoreOptions options = DatastoreOptions.builder()
       .projectId(PROJECT_ID)
       .host("http://<hostname of machine>:<port>")
+      .authCredentials(AuthCredentials.noAuth())
       .build();
   Datastore localDatastore = options.service();
   ```
@@ -134,4 +135,4 @@ Here is an example that clears the dataset created in Step 3.
   ```
 
 [cloud-platform-storage-authentication]:https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts
-[create-service-account]:https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount
\ No newline at end of file
+[create-service-account]:https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount
diff --git a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/LocalGcdHelper.java b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/LocalGcdHelper.java
index fdb6774f810f..b464e681cd76 100644
--- a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/LocalGcdHelper.java
+++ b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/LocalGcdHelper.java
@@ -21,6 +21,8 @@
 import static java.nio.charset.StandardCharsets.UTF_8;
 
 import com.google.common.base.Strings;
+import com.google.gcloud.AuthCredentials;
+import com.google.gcloud.datastore.DatastoreOptions;
 
 import java.io.BufferedInputStream;
 import java.io.BufferedOutputStream;
@@ -393,6 +395,18 @@ public LocalGcdHelper(String projectId, int port) {
     this.port = port;
   }
 
+  /**
+   * Returns a {@link DatastoreOptions} instance that sets the host to use the Datastore emulator
+   * on localhost.
+   */
+  public DatastoreOptions options() {
+    return DatastoreOptions.builder()
+        .projectId(projectId)
+        .host("http://localhost:" + Integer.toString(port))
+        .authCredentials(AuthCredentials.noAuth())
+        .build();
+  }
+
   /**
    * Starts the local datastore for the specific project.
    *
@@ -639,10 +653,13 @@ private static Map<String, String> parseArgs(String[] args) {
     for (String arg : args) {
       if (arg.startsWith("--port=")) {
         parsedArgs.put("port", arg.substring("--port=".length()));
+      } else if (arg.startsWith("--consistency=")) {
+        parsedArgs.put("consistency", arg.substring("--consistency=".length()));
       } else if (arg.equals("START") || arg.equals("STOP")) {
         parsedArgs.put("action", arg);
       } else {
-        throw new RuntimeException("Only accepts START, STOP, and --port=<port #> as arguments");
+        throw new RuntimeException("Only accepts START, STOP, --port=<port #> and "
+            + "--consistency=<double in range [0,1]> as arguments.");
       }
     }
     if (parsedArgs.get("action") == null) {
diff --git a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/package-info.java b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/package-info.java
index d03c9d85cd09..95337bf4f5f3 100644
--- a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/package-info.java
+++ b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/package-info.java
@@ -20,12 +20,8 @@
  * <p>A simple usage example:
  * <p>Before the test:
  * <pre> {@code
- * LocalGcdHelper gcdHelper = LocalGcdHelper.start(PROJECT_ID, PORT_NUMBER);
- * DatastoreOptions options = DatastoreOptions.builder()
- *     .projectId(PROJECT_ID)
- *     .host("localhost:8080")
- *     .build();
- * Datastore localDatastore = options.service();
+ * LocalGcdHelper gcdHelper = LocalGcdHelper.start(PROJECT_ID, PORT_NUMBER, CONSISTENCY);
+ * Datastore localDatastore = gcdHelper.options().service();
  * } </pre>
  *
  * <p>After the test:
diff --git a/gcloud-java-datastore/src/test/java/com/google/gcloud/datastore/DatastoreTest.java b/gcloud-java-datastore/src/test/java/com/google/gcloud/datastore/DatastoreTest.java
index e3829a2e71ce..90d105eaba9f 100644
--- a/gcloud-java-datastore/src/test/java/com/google/gcloud/datastore/DatastoreTest.java
+++ b/gcloud-java-datastore/src/test/java/com/google/gcloud/datastore/DatastoreTest.java
@@ -32,7 +32,6 @@
 import com.google.api.services.datastore.DatastoreV1.RunQueryResponse;
 import com.google.common.collect.Iterators;
 import com.google.common.collect.Lists;
-import com.google.gcloud.AuthCredentials;
 import com.google.gcloud.RetryParams;
 import com.google.gcloud.datastore.Query.ResultType;
 import com.google.gcloud.datastore.StructuredQuery.OrderBy;
@@ -126,13 +125,8 @@ public static void beforeClass() throws IOException, InterruptedException {
 
   @Before
   public void setUp() {
-    options = DatastoreOptions.builder()
-        .projectId(PROJECT_ID)
-        .host("http://localhost:" + PORT)
-        .authCredentials(AuthCredentials.noAuth())
-        .retryParams(RetryParams.noRetries())
-        .build();
-    datastore = options.service();
+    datastore =
+        gcdHelper.options().toBuilder().retryParams(RetryParams.noRetries()).build().service();
     StructuredQuery<Key> query = Query.keyQueryBuilder().build();
     QueryResults<Key> result = datastore.run(query);
     datastore.delete(Iterators.toArray(result, Key.class));