Add snippets for BigQuery Dataset class and tests.

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

@@ -19,6 +19,7 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 
 import com.google.cloud.Page;
+import com.google.cloud.bigquery.BigQuery.DatasetDeleteOption;
 import com.google.cloud.bigquery.BigQuery.DatasetOption;
 import com.google.cloud.bigquery.BigQuery.TableListOption;
 import com.google.cloud.bigquery.BigQuery.TableOption;
@@ -144,6 +145,16 @@ public Dataset build() {
   /**
    * Checks if this dataset exists.
    *
+   * <p>Example of checking whether a dataset exists.
+   * <pre> {@code
+   * boolean exists = dataset.exists();
+   * if (exists) {
+   *   // the dataset exists
+   * } else {
+   *   // the dataset was not found
+   * }
+   * }</pre>
+   *
    * @return {@code true} if this dataset exists, {@code false} otherwise
    * @throws BigQueryException upon failure
    */
@@ -155,6 +166,14 @@ public boolean exists() {
    * Fetches current dataset's latest information. Returns {@code null} if the dataset does not
    * exist.
    *
+   * <p>Example of reloading a dataset.
+   * <pre> {@code
+   * Dataset latestDataset = dataset.reload();
+   * if (latestDataset == null) {
+   *   // The dataset was not found
+   * }
+   * }</pre>
+   *
    * @param options dataset options
    * @return a {@code Dataset} object with latest information or {@code null} if not found
    * @throws BigQueryException upon failure
@@ -167,6 +186,14 @@ public Dataset reload(DatasetOption... options) {
    * Updates the dataset's information with this dataset's information. Dataset's user-defined id
    * cannot be changed. A new {@code Dataset} object is returned.
    *
+   * <p>Example of updating a dataset.
+   * <pre> {@code
+   * String friendlyName = "my_friendly_name";
+   * Builder builder = dataset.toBuilder();
+   * builder.friendlyName(friendlyName);
+   * Dataset updatedDataset = builder.build().update();
+   * }</pre>
+   *
    * @param options dataset options
    * @return a {@code Dataset} object with updated information
    * @throws BigQueryException upon failure
@@ -178,16 +205,36 @@ public Dataset update(DatasetOption... options) {
   /**
    * Deletes this dataset.
    *
+   * <p>Example of deleting a dataset.
+   * <pre> {@code
+   * boolean deleted = dataset.delete();
+   * if (deleted) {
+   *   // The dataset was deleted
+   * } else {
+   *   // The dataset was not found
+   * }
+   * }</pre>
+   *
    * @return {@code true} if dataset was deleted, {@code false} if it was not found
    * @throws BigQueryException upon failure
    */
-  public boolean delete() {
-    return bigquery.delete(datasetId());
+  public boolean delete(DatasetDeleteOption... options) {
+    return bigquery.delete(datasetId(), options);
   }
 
   /**
    * Returns the paginated list of tables in this dataset.
    *
+   * <p>Example of listing tables in the dataset.
+   * <pre> {@code
+   * Page<Table> tables = dataset.list();
+   * Iterator<Table> tableIterator = tables.iterateAll();
+   * while (tableIterator.hasNext()) {
+   *   Table table = tableIterator.next();
+   *   // do something with the table
+   * }
+   * }</pre>
+   *
    * @param options options for listing tables
    * @throws BigQueryException upon failure
    */
@@ -198,6 +245,12 @@ public Page<Table> list(TableListOption... options) {
   /**
    * Returns the requested table in this dataset or {@code null} if not found.
    *
+   * <p>Example of getting a table in the dataset.
+   * <pre> {@code
+   * String tableName = “my_table”;
+   * Table table = dataset.get(tableName);
+   * }</pre>
+   *
    * @param table user-defined id of the requested table
    * @param options table options
    * @throws BigQueryException upon failure
@@ -209,6 +262,18 @@ public Table get(String table, TableOption... options) {
   /**
    * Creates a new table in this dataset.
    *
+   * <p>Example of creating a table in the dataset with schema and time partitioning.
+   * <pre> {@code
+   * String tableName = “my_table”;
+   * String fieldName = “my_field”;
+   * Schema schema = Schema.of(Field.of(fieldName, Type.string()));
+   * StandardTableDefinition definition = StandardTableDefinition.builder()
+   *     .schema(schema)
+   *     .timePartitioning(TimePartitioning.of(TimePartitioning.Type.DAY))
+   *     .build();
+   * Table table = dataset.create(tableName, definition);
+   * }</pre>
+   *
    * @param table the table's user-defined id
    * @param definition the table's definition
    * @param options options for table creation

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

@@ -0,0 +1,153 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * EDITING INSTRUCTIONS
+ * This file is referenced in Dataset’s javadoc. Any change to this file should be reflected in
+ * Dataset’s javadoc.
+*/
+
+package com.google.cloud.examples.bigquery.snippets;
+
+import com.google.cloud.Page;
+import com.google.cloud.bigquery.Dataset;
+import com.google.cloud.bigquery.Dataset.Builder;
+import com.google.cloud.bigquery.Field;
+import com.google.cloud.bigquery.Field.Type;
+import com.google.cloud.bigquery.Schema;
+import com.google.cloud.bigquery.StandardTableDefinition;
+import com.google.cloud.bigquery.Table;
+import com.google.cloud.bigquery.TimePartitioning;
+
+import java.util.Iterator;
+
+/**
+ * This class contains a number of snippets for the {@link Dataset} interface.
+ */
+public class DatasetSnippets {
+
+  private final Dataset dataset;
+
+  public DatasetSnippets(Dataset dataset) {
+    this.dataset = dataset;
+  }
+
+  /**
+   * Example of checking whether a dataset exists.
+   */
+  // [TARGET exists()]
+  public boolean doesDatasetExist() {
+    // [START exists]
+    boolean exists = dataset.exists();
+    if (exists) {
+      // the dataset exists
+    } else {
+      // the dataset was not found
+    }
+    // [END exists]
+    return exists;
+  }
+
+  /**
+   * Example of reloading a dataset.
+   */
+  // [TARGET reload(DatasetOption...)]
+  public Dataset reloadDataset() {
+    // [START reload]
+    Dataset latestDataset = dataset.reload();
+    if (latestDataset == null) {
+      // The dataset was not found
+    }
+    // [END reload]
+    return latestDataset;
+  }
+
+  /**
+   * Example of updating a dataset.
+   */
+  // [TARGET update(DatasetOption...)]
+  // [VARIABLE "my_friendly_name"]
+  public Dataset updateDataset(String friendlyName) {
+    // [START update]
+    Builder builder = dataset.toBuilder();
+    builder.friendlyName(friendlyName);
+    Dataset updatedDataset = builder.build().update();
+    // [END update]
+    return updatedDataset;
+  }
+
+  /**
+   * Example of deleting a dataset.
+   */
+  // [TARGET delete(DatasetDeleteOption...)]
+  public boolean deleteDataset() {
+    // [START delete]
+    boolean deleted = dataset.delete();
+    if (deleted) {
+      // The dataset was deleted
+    } else {
+      // The dataset was not found
+    }
+    // [END delete]
+    return deleted;
+  }
+
+  /**
+   * Example of listing tables in the dataset.
+   */
+  // [TARGET list(TableListOption...)]
+  public Page<Table> list() {
+     // [START list]
+    Page<Table> tables = dataset.list();
+    Iterator<Table> tableIterator = tables.iterateAll();
+    while (tableIterator.hasNext()) {
+      Table table = tableIterator.next();
+      // do something with the table
+    }
+    // [END list]
+   return tables;
+  }
+
+  /**
+   * Example of getting a table in the dataset.
+   */
+  // [TARGET get(String, TableOption...)]
+  // [VARIABLE “my_table”]
+  public Table getTable(String tableName) {
+    // [START getTable]
+    Table table = dataset.get(tableName);
+    // [END getTable]
+    return table;
+  }
+
+  /**
+   * Example of creating a table in the dataset with schema and time partitioning.
+   */
+  // [TARGET create(String, TableDefinition, TableOption...)]
+  // [VARIABLE “my_table”]
+  // [VARIABLE “my_field”]
+  public Table createTable(String tableName, String fieldName) {
+    // [START createTable]
+    Schema schema = Schema.of(Field.of(fieldName, Type.string()));
+    StandardTableDefinition definition = StandardTableDefinition.builder()
+        .schema(schema)
+        .timePartitioning(TimePartitioning.of(TimePartitioning.Type.DAY))
+        .build();
+    Table table = dataset.create(tableName, definition);
+    // [END createTable]
+    return table;
+  }
+}