datastore: better document emulator functions (#2828)

pongad · web-flow · commit b5fb39c8b6c7 · 2018-02-05T11:40:24.000+11:00
Fixes #2800. The API is unstable since we're still working on how to better expose emulators.
diff --git a/google-cloud-datastore/src/main/java/com/google/cloud/datastore/testing/LocalDatastoreHelper.java b/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;
