---

pongad · web-flow · commit 194ad6e3921d · 2018-02-05T11:40:24.000+11:00
yaml --- r: 8691 b: refs/heads/master c: b5fb39c h: refs/heads/master i: 8689: 095adb8 8687: 0b962bf
diff --git a/[refs] b/[refs]
@@ -1,5 +1,5 @@
 ---
-refs/heads/master: c572f05d606edd53e8bc2820c32d99652350c208
+refs/heads/master: b5fb39c8b6c795cb3ce009c41a5632fb209166e8
 refs/heads/travis: 47e4fee4fd5af9b2a8ce46f23c72ec95f9b195b2
 refs/heads/gh-pages: 6daca92127d91b7c2c99490080ecf8a13fa94cde
 refs/tags/0.0.9: 22f1839238f66c39e67ed4dfdcd273b1ae2e8444
diff --git a/trunk/google-cloud-datastore/src/main/java/com/google/cloud/datastore/testing/LocalDatastoreHelper.java b/trunk/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;
