Add snippets for waitFor().

This moves the hand-written snippets to JobSnippets and adds IT tests.

Author: tswast

google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java

@@ -136,11 +136,14 @@ public boolean exists() {
 
   /**
    * Checks if this job has completed its execution, either failing or succeeding. If the job does
-   * not exist this method returns {@code true}. You can wait for job completion with:
+   * not exist this method returns {@code true}.
+   *
+   * <p>Example of waiting for a job until it reports that it is done.
    * <pre> {@code
-   * while(!job.isDone()) {
+   * while (!job.isDone()) {
    *   Thread.sleep(1000L);
-   * }}</pre>
+   * }
+   * }</pre>
    *
    * @return {@code true} if this job is in {@link JobStatus.State#DONE} state or if it does not
    *     exist, {@code false} if the state is not {@link JobStatus.State#DONE}
@@ -158,7 +161,7 @@ public boolean isDone() {
    * value use {@link WaitForOption#checkEvery(long, TimeUnit)}. Use
    * {@link WaitForOption#timeout(long, TimeUnit)} to set the maximum time to wait.
    *
-   * <p>Example usage of {@code waitFor()}:
+   * <p>Example usage of {@code waitFor()}.
    * <pre> {@code
    * Job completedJob = job.waitFor();
    * if (completedJob == null) {
@@ -167,19 +170,23 @@ public boolean isDone() {
    *   // job failed, handle error
    * } else {
    *   // job completed successfully
-   * }}</pre>
+   * }
+   * }</pre>
    *
-   * <p>Example usage of {@code waitFor()} with checking period and timeout:
+   * <p>Example usage of {@code waitFor()} with checking period and timeout.
    * <pre> {@code
-   * Job completedJob = job.waitFor(WaitForOption.checkEvery(1, TimeUnit.SECONDS),
-   *     WaitForOption.timeout(60, TimeUnit.SECONDS));
+   * Job completedJob =
+   *     job.waitFor(
+   *         WaitForOption.checkEvery(1, TimeUnit.SECONDS),
+   *         WaitForOption.timeout(60, TimeUnit.SECONDS));
    * if (completedJob == null) {
    *   // job no longer exists
    * } else if (completedJob.status().error() != null) {
    *   // job failed, handle error
    * } else {
    *   // job completed successfully
-   * }}</pre>
+   * }
+   * }</pre>
    *
    * @param waitOptions options to configure checking period and timeout
    * @throws BigQueryException upon failure

google-cloud-examples/src/main/java/com/google/cloud/examples/bigquery/snippets/JobSnippets.java

@@ -22,8 +22,12 @@
 
 package com.google.cloud.examples.bigquery.snippets;
 
+import com.google.cloud.WaitForOption;
 import com.google.cloud.bigquery.Job;
 
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
 public class JobSnippets {
 
   private final Job job;
@@ -36,16 +40,59 @@ public JobSnippets(Job job) {
    * Example of waiting for a job until it reports that it is done.
    */
   // [TARGET isDone()]
-  public boolean isDone() {
+  public void isDone() throws InterruptedException {
+    // [START isDone]
+    while (!job.isDone()) {
+      Thread.sleep(1000L);
+    }
+    // [END isDone]
+  }
+
+  /**
+   * Example usage of {@code waitFor()}.
+   */
+  // [TARGET waitFor(WaitForOption...)]
+  public boolean waitFor() throws InterruptedException {
     try {
-      // [START isDone]
-      while (!job.isDone()) {
-        Thread.sleep(1000L);
+      // [START waitFor]
+      Job completedJob = job.waitFor();
+      if (completedJob == null) {
+        // job no longer exists
+      } else if (completedJob.status().error() != null) {
+        // job failed, handle error
+      } else {
+        // job completed successfully
       }
-      // [END isDone]
-    } catch (InterruptedException e) {
+      // [END waitFor]
+    } catch (TimeoutException e) {
+      // Timeouts shouldn't happen without a timeout option.
       return false;
     }
     return true;
   }
+
+  /**
+   * Example usage of {@code waitFor()} with checking period and timeout.
+   */
+  // [TARGET waitFor(WaitForOption...)]
+  public boolean waitForWithOptions() throws InterruptedException {
+    try {
+      // [START waitFor]
+      Job completedJob =
+          job.waitFor(
+              WaitForOption.checkEvery(1, TimeUnit.SECONDS),
+              WaitForOption.timeout(60, TimeUnit.SECONDS));
+      if (completedJob == null) {
+        // job no longer exists
+      } else if (completedJob.status().error() != null) {
+        // job failed, handle error
+      } else {
+        // job completed successfully
+      }
+      // [END waitFor]
+    } catch (TimeoutException e) {
+      return true;
+    }
+    return true;
+  }
 }

google-cloud-examples/src/test/java/com/google/cloud/examples/bigquery/snippets/ITJobSnippets.java

@@ -30,6 +30,9 @@
 
 public class ITJobSnippets {
 
+  private static final String QUERY =
+      "SELECT corpus FROM `publicdata.samples.shakespeare` GROUP BY corpus;";
+
   private static BigQuery bigquery;
 
   @BeforeClass
@@ -39,15 +42,31 @@ public static void beforeClass() {
 
   @Test
   public void testIsDone() throws Exception {
-    JobConfiguration jobConfig =
-        QueryJobConfiguration.builder(
-                "SELECT corpus FROM `publicdata.samples.shakespeare` GROUP BY corpus;")
-            .useLegacySql(false)
-            .build();
+    JobConfiguration jobConfig = QueryJobConfiguration.builder(QUERY).useLegacySql(false).build();
+    JobInfo jobInfo = JobInfo.builder(jobConfig).build();
+    Job job = bigquery.create(jobInfo);
+    JobSnippets jobSnippets = new JobSnippets(job);
+    jobSnippets.isDone();
+    assertTrue(job.isDone());
+  }
+
+  @Test
+  public void testWaitFor() throws Exception {
+    JobConfiguration jobConfig = QueryJobConfiguration.builder(QUERY).useLegacySql(false).build();
+    JobInfo jobInfo = JobInfo.builder(jobConfig).build();
+    Job job = bigquery.create(jobInfo);
+    JobSnippets jobSnippets = new JobSnippets(job);
+    boolean result = jobSnippets.waitFor();
+    assertTrue(result);
+  }
+
+  @Test
+  public void testWaitForWithOptions() throws Exception {
+    JobConfiguration jobConfig = QueryJobConfiguration.builder(QUERY).useLegacySql(false).build();
     JobInfo jobInfo = JobInfo.builder(jobConfig).build();
     Job job = bigquery.create(jobInfo);
     JobSnippets jobSnippets = new JobSnippets(job);
-    boolean result = jobSnippets.isDone();
+    boolean result = jobSnippets.waitForWithOptions();
     assertTrue(result);
   }
 }