Add more BigQuery Job snippets.

This should be the last of the snippets needed for BigQuery Job.

Author: tswast

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

@@ -127,6 +127,13 @@ public Job build() {
   /**
    * Checks if this job exists.
    *
+   * <p>Example of checking that a job exists.
+   * <pre> {@code
+   * if (!job.exists()) {
+   *   // job doesn't exist
+   * }
+   * }</pre>
+   *
    * @return {@code true} if this job exists, {@code false} otherwise
    * @throws BigQueryException upon failure
    */
@@ -214,6 +221,22 @@ public Job waitFor(WaitForOption... waitOptions) throws InterruptedException, Ti
   /**
    * Fetches current job's latest information. Returns {@code null} if the job does not exist.
    *
+   * <p>Example of reloading all fields until job status is DONE.
+   * <pre> {@code
+   * while (job.status().state() != JobStatus.State.DONE) {
+   *   Thread.sleep(1000L);
+   *   job = job.reload();
+   * }
+   * }</pre>
+   *
+   * <p>Example of reloading status field until job status is DONE.
+   * <pre> {@code
+   * while (job.status().state() != JobStatus.State.DONE) {
+   *   Thread.sleep(1000L);
+   *   job = job.reload(BigQuery.JobOption.fields(BigQuery.JobField.STATUS));
+   * }
+   * }</pre>
+   *
    * @param options job options
    * @return a {@code Job} object with latest information or {@code null} if not found
    * @throws BigQueryException upon failure
@@ -225,6 +248,15 @@ public Job reload(JobOption... options) {
   /**
    * Sends a job cancel request.
    *
+   * <p>Example of cancelling a job.
+   * <pre> {@code
+   * if (job.cancel()) {
+   *   return true; // job successfully cancelled
+   * } else {
+   *   // job not found
+   * }
+   * }</pre>
+   *
    * @return {@code true} if cancel request was sent successfully, {@code false} if job was not
    *     found
    * @throws BigQueryException upon failure

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

@@ -23,7 +23,9 @@
 package com.google.cloud.examples.bigquery.snippets;
 
 import com.google.cloud.WaitForOption;
+import com.google.cloud.bigquery.BigQuery;
 import com.google.cloud.bigquery.Job;
+import com.google.cloud.bigquery.JobStatus;
 
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
@@ -36,6 +38,19 @@ public JobSnippets(Job job) {
     this.job = job;
   }
 
+  /**
+   * Example of checking that a job exists.
+   */
+  // [TARGET exists()]
+  public boolean exists() throws InterruptedException {
+    // [START exists]
+    if (!job.exists()) {
+      // job doesn't exist
+    }
+    // [END exists]
+    return job.exists();
+  }
+
   /**
    * Example of waiting for a job until it reports that it is done.
    */
@@ -77,7 +92,7 @@ public boolean waitFor() throws InterruptedException {
   // [TARGET waitFor(WaitForOption...)]
   public boolean waitForWithOptions() throws InterruptedException {
     try {
-      // [START waitFor]
+      // [START waitForWithOptions]
       Job completedJob =
           job.waitFor(
               WaitForOption.checkEvery(1, TimeUnit.SECONDS),
@@ -89,10 +104,55 @@ public boolean waitForWithOptions() throws InterruptedException {
       } else {
         // job completed successfully
       }
-      // [END waitFor]
+      // [END waitForWithOptions]
     } catch (TimeoutException e) {
       return true;
     }
     return true;
   }
+
+  /**
+   * Example of reloading all fields until job status is DONE.
+   */
+  // [TARGET reload(JobOption...)]
+  public JobStatus.State reload() throws InterruptedException {
+    Job job = this.job;
+    // [START reload]
+    while (job.status().state() != JobStatus.State.DONE) {
+      Thread.sleep(1000L);
+      job = job.reload();
+    }
+    // [END reload]
+    return job.status().state();
+  }
+
+  /**
+   * Example of reloading status field until job status is DONE.
+   */
+  // [TARGET reload(JobOption...)]
+  public JobStatus.State reloadStatus() throws InterruptedException {
+    Job job = this.job;
+    // [START reloadStatus]
+    while (job.status().state() != JobStatus.State.DONE) {
+      Thread.sleep(1000L);
+      job = job.reload(BigQuery.JobOption.fields(BigQuery.JobField.STATUS));
+    }
+    // [END reloadStatus]
+    return job.status().state();
+  }
+
+  /**
+   * Example of cancelling a job.
+   */
+  // [TARGET cancel()]
+  public boolean cancel() {
+    // [START cancel]
+    if (job.cancel()) {
+      return true; // job successfully cancelled
+    } else {
+      // job not found
+    }
+    // [END cancel]
+    return false;
+  }
 }

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

@@ -16,12 +16,14 @@
 
 package com.google.cloud.examples.bigquery.snippets;
 
+import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertTrue;
 
 import com.google.cloud.bigquery.BigQuery;
 import com.google.cloud.bigquery.Job;
 import com.google.cloud.bigquery.JobConfiguration;
 import com.google.cloud.bigquery.JobInfo;
+import com.google.cloud.bigquery.JobStatus;
 import com.google.cloud.bigquery.QueryJobConfiguration;
 import com.google.cloud.bigquery.testing.RemoteBigQueryHelper;
 
@@ -40,6 +42,16 @@ public static void beforeClass() {
     bigquery = RemoteBigQueryHelper.create().options().service();
   }
 
+  @Test
+  public void testExists() 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.exists();
+    assertTrue(result);
+  }
+
   @Test
   public void testIsDone() throws Exception {
     JobConfiguration jobConfig = QueryJobConfiguration.builder(QUERY).useLegacySql(false).build();
@@ -69,4 +81,34 @@ public void testWaitForWithOptions() throws Exception {
     boolean result = jobSnippets.waitForWithOptions();
     assertTrue(result);
   }
+
+  @Test
+  public void testReload() 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);
+    JobStatus.State result = jobSnippets.reload();
+    assertEquals(JobStatus.State.DONE, result);
+  }
+
+  @Test
+  public void testReloadStatus() 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);
+    JobStatus.State result = jobSnippets.reloadStatus();
+    assertEquals(JobStatus.State.DONE, result);
+  }
+
+  @Test
+  public void testCancel() 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.cancel();
+    assertTrue(result);
+  }
 }