Clean up local gcd helper and docs

Author: Ajay Kannan

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
+[create-service-account]:https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount

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) {

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:

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));