Renames LocalGcdHelper --> LocalDatastoreHelper and RemoteGcsHelper --> RemoteStorageHelper, also removes main()-related functions from LocalDatastoreHelper

Author: Ajay Kannan

TESTING.md

@@ -11,56 +11,57 @@ This library provides tools to help write tests for code that uses the following
 
 #### On your machine
 
-You can test against a temporary local datastore by following these steps:
+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 `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);
-    ```
+1. Start the local Datastore emulator before running your tests using `LocalDatastoreHelper`'s `start` method. This will create a temporary folder on your computer and bind a port for communication with the local datastore. There are two optional arguments for `start`: project ID and consistency. The consistency setting controls the fraction of Datastore writes that are immediately visible in global queries.
+  ```java
+  // Use defaults for project ID and consistency
+  LocalDatastoreHelper helper = LocalDatastoreHelper.start();
+  // or explicitly provide them
+  helper = LocalDatastoreHelper.start("my-project-id", 0.6);
+  ```
 
-2. In your program, create and use a `Datastore` object with the options given by the `LocalGcdHelper` instance.  For example:
+2. In your program, create and use a `Datastore` object with the options given by the `LocalDatastoreHelper` instance.  For example:
   ```java
-  Datastore localDatastore = helper.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 the `LocalGcdHelper.start` method to start the emulator, call the `stop()` method on the `LocalGcdHelper` object returned by `LocalGcdHelper.start`.
+4. Stop the local datastore emulator by calling the `stop()` method, like so:
+  ```java
+  helper.stop();
+  ```
 
 #### On a remote machine
 
-You can test against a remote datastore emulator as well.  To do this, set the `DatastoreOptions` project endpoint to the hostname of the remote machine, like the example below.
+You can test against a remote Datastore emulator as well.  To do this, set the `DatastoreOptions` project endpoint to the hostname of the remote machine, like the example below.
 
   ```java
-  DatastoreOptions options = DatastoreOptions.builder()
-      .projectId(PROJECT_ID)
+  DatastoreOptions options = LocalDatastoreHelper.options()
+      .toBuilder()
       .host("http://<hostname of machine>:<port>")
-      .authCredentials(AuthCredentials.noAuth())
       .build();
   Datastore localDatastore = options.service();
   ```
 
-Note that the remote datastore must be running before your tests are run.
+Note that the remote Datastore emulator must be running before your tests are run.
 
 ### Testing code that uses Storage
 
-Currently, there isn't an emulator for Google Cloud Storage, so an alternative is to create a test project.  `RemoteGcsHelper` contains convenience methods to make setting up and cleaning up the test project easier.  To use this class, follow the steps below:
+Currently, there isn't an emulator for Google Cloud Storage, so an alternative is to create a test project.  `RemoteStorageHelper` contains convenience methods to make setting up and cleaning up the test project easier.  To use this class, follow the steps below:
 
 1. Create a test Google Cloud project.
 
 2. Download a JSON service account credentials file from the Google Developer's Console.  See more about this on the [Google Cloud Platform Storage Authentication page][cloud-platform-storage-authentication]. 
 
-3. Create a `RemoteGcsHelper` object using your project ID and JSON key.
-Here is an example that uses the `RemoteGcsHelper` to create a bucket.
+3. Create a `RemoteStorageHelper` object using your project ID and JSON key.
+Here is an example that uses the `RemoteStorageHelper` to create a bucket.
   ```java
-  RemoteGcsHelper gcsHelper =
-      RemoteGcsHelper.create(PROJECT_ID, new FileInputStream("/path/to/my/JSON/key.json"));
-  Storage storage = gcsHelper.options().service();
-  String bucket = RemoteGcsHelper.generateBucketName();
+  RemoteStorageHelper helper =
+      RemoteStorageHelper.create(PROJECT_ID, new FileInputStream("/path/to/my/JSON/key.json"));
+  Storage storage = helper.options().service();
+  String bucket = RemoteStorageHelper.generateBucketName();
   storage.create(BucketInfo.of(bucket));
   ```
 
@@ -69,7 +70,7 @@ Here is an example that uses the `RemoteGcsHelper` to create a bucket.
 5. Clean up the test project by using `forceDelete` to clear any buckets used.
 Here is an example that clears the bucket created in Step 3 with a timeout of 5 seconds.
   ```java
-  RemoteGcsHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS);
+  RemoteStorageHelper.forceDelete(storage, bucket, 5, TimeUnit.SECONDS);
   ```
 
 ### Testing code that uses Resource Manager

gcloud-java-bigquery/src/test/java/com/google/gcloud/bigquery/it/ITBigQueryTest.java

@@ -67,7 +67,7 @@
 import com.google.gcloud.storage.BlobInfo;
 import com.google.gcloud.storage.BucketInfo;
 import com.google.gcloud.storage.Storage;
-import com.google.gcloud.storage.testing.RemoteGcsHelper;
+import com.google.gcloud.storage.testing.RemoteStorageHelper;
 
 import org.junit.AfterClass;
 import org.junit.BeforeClass;
@@ -134,7 +134,7 @@ public class ITBigQueryTest {
   private static final String LOAD_FILE = "load.csv";
   private static final String JSON_LOAD_FILE = "load.json";
   private static final String EXTRACT_FILE = "extract.csv";
-  private static final String BUCKET = RemoteGcsHelper.generateBucketName();
+  private static final String BUCKET = RemoteStorageHelper.generateBucketName();
   private static final TableId TABLE_ID = TableId.of(DATASET, "testing_table");
   private static final String CSV_CONTENT = "StringValue1\nStringValue2\n";
   private static final String JSON_CONTENT = "{"
@@ -171,7 +171,7 @@ public class ITBigQueryTest {
   @BeforeClass
   public static void beforeClass() throws InterruptedException {
     RemoteBigQueryHelper bigqueryHelper = RemoteBigQueryHelper.create();
-    RemoteGcsHelper gcsHelper = RemoteGcsHelper.create();
+    RemoteStorageHelper gcsHelper = RemoteStorageHelper.create();
     bigquery = bigqueryHelper.options().service();
     storage = gcsHelper.options().service();
     storage.create(BucketInfo.of(BUCKET));
@@ -199,7 +199,7 @@ public static void afterClass() throws ExecutionException, InterruptedException
       RemoteBigQueryHelper.forceDelete(bigquery, DATASET);
     }
     if (storage != null) {
-      boolean wasDeleted = RemoteGcsHelper.forceDelete(storage, BUCKET, 10, TimeUnit.SECONDS);
+      boolean wasDeleted = RemoteStorageHelper.forceDelete(storage, BUCKET, 10, TimeUnit.SECONDS);
       if (!wasDeleted && LOG.isLoggable(Level.WARNING)) {
         LOG.log(Level.WARNING, "Deletion of bucket {0} timed out, bucket is not empty", BUCKET);
       }

gcloud-java-core/src/main/java/com/google/gcloud/AuthCredentials.java

@@ -260,7 +260,7 @@ public RestorableState<AuthCredentials> capture() {
   /**
    * A placeholder for credentials to signify that requests sent to the server should not be
    * authenticated. This is typically useful when using the local service emulators, such as
-   * {@code LocalGcdHelper} and {@code LocalResourceManagerHelper}.
+   * {@code LocalDatastoreHelper} and {@code LocalResourceManagerHelper}.
    */
   public static class NoAuthCredentials extends AuthCredentials {
 
@@ -341,7 +341,7 @@ public static ServiceAccountAuthCredentials createFor(String account, PrivateKey
 
   /**
    * Creates a placeholder denoting that no credentials should be used. This is typically useful
-   * when using the local service emulators, such as {@code LocalGcdHelper} and
+   * when using the local service emulators, such as {@code LocalDatastoreHelper} and
    * {@code LocalResourceManagerHelper}.
    */
   public static AuthCredentials noAuth() {

gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/LocalDatastoreHelper.java

@@ -64,6 +64,7 @@
  */
 public class LocalDatastoreHelper {
   private static final Logger log = Logger.getLogger(LocalDatastoreHelper.class.getName());
+  public static final String DEFAULT_PROJECT_ID = "projectid1";
   private static final double DEFAULT_CONSISTENCY = 0.9;
   private static final String GCD_VERSION = "v1beta2";
   private static final String GCD_BUILD = "rev1-2.1.2b";
@@ -81,6 +82,7 @@ public class LocalDatastoreHelper {
   private ProcessStreamReader processReader;
   private ProcessErrorStreamReader processErrorReader;
   private final int port;
+  private final double consistency;
 
   static {
     INSTALLED_GCD_PATH = installedGcdPath();
@@ -537,8 +539,9 @@ public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) throws IO
     });
   }
 
-  private LocalDatastoreHelper(String projectId) {
+  private LocalDatastoreHelper(String projectId, double consistency) {
     this.projectId = projectId;
+    this.consistency = consistency;
     this.port = findAvailablePort();
   }
 
@@ -576,6 +579,13 @@ public int port() {
     return port;
   }
 
+  /**
+   * Returns the consistency setting for the local Datastore emulator.
+   */
+  public double consistency() {
+    return consistency;
+  }
+
   /**
    * Starts the local Datastore for the specific project.
    *
@@ -590,24 +600,23 @@ public int port() {
    */
   public static LocalDatastoreHelper start(String projectId, double consistency)
       throws IOException, InterruptedException {
-    LocalDatastoreHelper helper = new LocalDatastoreHelper(projectId);
-    helper.start(consistency);
+    LocalDatastoreHelper helper = new LocalDatastoreHelper(projectId, consistency);
+    helper.findAndStartGcd();
     return helper;
   }
 
   /**
-   * Starts the local Datastore for the specific project using a default consistency setting of 0.9.
+   * Starts the local Datastore using defaults for project ID and consistency setting of 0.9.
    *
    * This will unzip the gcd tool, create the project and start it. All content is written to a
    * temporary directory that will be deleted when {@link #stop()} is called (or when the program
    * terminates) to make sure that no left-over data from prior runs is used.
    */
-  public static LocalDatastoreHelper start(String projectId)
-      throws IOException, InterruptedException {
-    return start(projectId, DEFAULT_CONSISTENCY);
+  public static LocalDatastoreHelper start() throws IOException, InterruptedException {
+    return start(DEFAULT_PROJECT_ID, DEFAULT_CONSISTENCY);
   }
 
-  private void start(double consistency) throws IOException, InterruptedException {
+  private void findAndStartGcd() throws IOException, InterruptedException {
     // send a quick request in case we have a hanging process from a previous run
     checkArgument(consistency >= 0.0 && consistency <= 1.0, "Consistency must be between 0 and 1");
     sendQuitRequest(port);

gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/testing/package-info.java

@@ -20,13 +20,13 @@
  * <p>A simple usage example:
  * <p>Before the test:
  * <pre> {@code
- * LocalGcdHelper gcdHelper = LocalGcdHelper.start(PROJECT_ID, PORT_NUMBER, CONSISTENCY);
- * Datastore localDatastore = gcdHelper.options().service();
+ * LocalDatastoreHelper helper = LocalDatastoreHelper.start();
+ * Datastore localDatastore = helper.options().service();
  * } </pre>
  *
  * <p>After the test:
  * <pre> {@code
- * gcdHelper.stop();
+ * helper.stop();
  * } </pre>
  *
  * @see <a href="https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md#testing-code-that-uses-datastore">

gcloud-java-datastore/src/test/java/com/google/gcloud/datastore/DatastoreOptionsTest.java

@@ -24,16 +24,15 @@
 
 import com.google.gcloud.datastore.spi.DatastoreRpc;
 import com.google.gcloud.datastore.spi.DatastoreRpcFactory;
-import com.google.gcloud.datastore.testing.LocalDatastoreHelper;
 
 import org.easymock.EasyMock;
 import org.junit.Before;
 import org.junit.Test;
 
 public class DatastoreOptionsTest {
 
-  private static final String PROJECT_ID = "project_id";
-  private static final int PORT = LocalDatastoreHelper.findAvailablePort(LocalDatastoreHelper.DEFAULT_PORT);
+  private static final String PROJECT_ID = "project-id";
+  private static final int PORT = 8080;
   private DatastoreRpcFactory datastoreRpcFactory;
   private DatastoreRpc datastoreRpc;
   private DatastoreOptions.Builder options;

gcloud-java-datastore/src/test/java/com/google/gcloud/datastore/LocalDatastoreHelperTest.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2015 Google Inc. All Rights Reserved.
+ *
+ * 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.
+ */
+
+package com.google.gcloud.datastore;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+import com.google.gcloud.AuthCredentials;
+import com.google.gcloud.datastore.testing.LocalDatastoreHelper;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+import java.io.IOException;
+
+@RunWith(JUnit4.class)
+public class LocalDatastoreHelperTest {
+
+  private static final String PROJECT_ID = "some-project-id";
+  private static final double TOLERANCE = 0.00001;
+
+  @Test
+  public void testStart() throws IOException, InterruptedException {
+    LocalDatastoreHelper helper = LocalDatastoreHelper.start(PROJECT_ID, 0.75);
+    assertTrue(Math.abs(0.75 - helper.consistency()) < TOLERANCE);
+    assertEquals(PROJECT_ID, helper.projectId());
+    helper.stop();
+    helper = LocalDatastoreHelper.start();
+    assertTrue(Math.abs(0.9 - helper.consistency()) < TOLERANCE);
+    assertEquals(LocalDatastoreHelper.DEFAULT_PROJECT_ID, helper.projectId());
+    helper.stop();
+  }
+
+  @Test
+  public void testOptions() throws IOException, InterruptedException {
+    LocalDatastoreHelper helper = LocalDatastoreHelper.start();
+    DatastoreOptions options = helper.options();
+    assertEquals(LocalDatastoreHelper.DEFAULT_PROJECT_ID, options.projectId());
+    assertEquals("http://localhost:" + helper.port(), options.host());
+    assertSame(AuthCredentials.noAuth(), options.authCredentials());
+    helper.stop();
+  }
+}