---

pongad · web-flow · commit ce215f8f6f82 · 2018-02-05T11:40:24.000+11:00
yaml --- r: 8977 b: refs/heads/lesv-patch-1 c: b5fb39c h: refs/heads/master i: 8975: 6f71b0d
diff --git a/[refs] b/[refs]
@@ -66,7 +66,7 @@ refs/tags/v0.22.0: 18b298fe4bfe8ec2f20b0e0bf7ffdcce5cc3c5fe
 refs/heads/vam-google-patch-1: d0c8fee3a4074d0bf7360ce8c4f7f7223d0ee7b9
 refs/heads/vam-google-patch-CODEOWNERS: 2ac1616e25229e51d08a984708ef1918f91a35ee
 refs/heads/danoscarmike-patch-1: 7342a9916bce4ed00002c7202e2a16c5d46afaea
-refs/heads/lesv-patch-1: c572f05d606edd53e8bc2820c32d99652350c208
+refs/heads/lesv-patch-1: b5fb39c8b6c795cb3ce009c41a5632fb209166e8
 refs/heads/ml-update-branch: 079dd6610017f5c51b9d1938c12d6d55b61513cf
 refs/heads/vkedia-patch-2: 7d8241388a9769a5c069334761b06c7012c878e7
 refs/heads/vkedia-patch-3: 4d128043acaa7db9160faf439d2ca6104e8a88cb
diff --git a/branches/lesv-patch-1/google-cloud-datastore/src/main/java/com/google/cloud/datastore/testing/LocalDatastoreHelper.java b/branches/lesv-patch-1/google-cloud-datastore/src/main/java/com/google/cloud/datastore/testing/LocalDatastoreHelper.java
@@ -22,9 +22,6 @@
 import com.google.cloud.datastore.DatastoreOptions;
 import com.google.cloud.testing.BaseEmulatorHelper;
 import com.google.common.collect.ImmutableList;
-
-import org.threeten.bp.Duration;
-
 import java.io.IOException;
 import java.net.MalformedURLException;
 import java.net.URL;
@@ -40,11 +37,12 @@
 import java.util.concurrent.TimeoutException;
 import java.util.logging.Level;
 import java.util.logging.Logger;
+import org.threeten.bp.Duration;
 
 /**
- * Utility to start and stop local Google Cloud Datastore process.
- * 
- * Internal testing use only
+ * Utility to start and stop local Google Cloud Datastore emulators.
+ *
+ * <p>This class is unstable.
  */
 @InternalApi
 public class LocalDatastoreHelper extends BaseEmulatorHelper<DatastoreOptions> {
@@ -185,6 +183,8 @@ public static LocalDatastoreHelper create() {
   /**
    * Starts the local Datastore emulator through {@code gcloud}, downloads and caches the zip file
    * if user does not have {@code gcloud} or a compatible emulator version installed.
+   *
+   * <p>Currently the emulator does not persist any state across runs.
    */
   @Override
   public void start() throws IOException, InterruptedException {
@@ -193,21 +193,47 @@ public void start() throws IOException, InterruptedException {
   }
 
   /**
-   * Reset the internal state of the Datastore emulator.
+   * Resets the internal state of the Datastore emulator.
+   *
+   * <p>When running tests, one might {@code reset()} before each test, so earlier tests would not
+   * affect later ones.
    */
+  @Override
   public void reset() throws IOException {
     sendPostRequest("/reset");
   }
 
   /**
    * Stops the Datastore emulator.
+   *
+   * <p>It is important to stop the emulator. Since the emulator runs in its own process, not
+   * stopping it might cause it to become orphan.
+   *
+   * <p>It is not required to call {@link #reset()} before {@code stop}.
+   *
+   * @param timeout The duration to wait for the emulator process to stop. It is recommended to set
+   *     this value high to ensure proper shutdown, like 5 seconds or more.
    */
+  @Override
   public void stop(Duration timeout) throws IOException, InterruptedException, TimeoutException {
     sendPostRequest("/shutdown");
     waitForProcess(timeout);
     deleteRecursively(gcdPath);
   }
 
+  /**
+   * Stops the Datastore emulator. The same as {@link stop(Duration)} but with timeout duration of
+   * 20 seconds.
+   *
+   * <p>It is important to stop the emulator. Since the emulator runs in its own process, not
+   * stopping it might cause it to become orphan.
+   *
+   * <p>It is not required to call {@link #reset()} before {@code stop()}.
+   */
+  public void stop() throws IOException, InterruptedException, TimeoutException {
+    stop(Duration.ofSeconds(20));
+  }
+
   private static void deleteRecursively(Path path) throws IOException {
     if (path == null || !Files.exists(path)) {
       return;
