BigQuery: Add "managing datasets" snippets.

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

@@ -318,6 +318,20 @@ public DatasetId getDatasetId() {
   /**
    * Returns the dataset's access control configuration.
    *
+   * <p>Update the ACLs for a dataset.
+   * <pre> {@code
+   * Dataset dataset = bigquery.getDataset(DatasetId.of("my_dataset"));
+   * List<Acl> beforeAcls = dataset.getAcl();
+   * 
+   * // Make a copy of the ACLs so that they can be modified.
+   * ArrayList<Acl> acls = new ArrayList<>(beforeAcls);
+   * acls.add(Acl.of(new Acl.User("sample.bigquery.dev@gmail.com"), Acl.Role.READER));
+   * Dataset.Builder builder = dataset.toBuilder();
+   * builder.setAcl(acls);
+   * 
+   * bigquery.update(builder.build());  // API request.
+   * }</pre>
+   *
    * @see <a href="https://cloud.google.com/bigquery/access-control">Access Control</a>
    */
   public List<Acl> getAcl() {
@@ -341,6 +355,18 @@ public Long getCreationTime() {
    * will be deleted automatically. If a table's expirationTime is modified or removed before the
    * table expires, or if you provide an explicit expirationTime when creating a table, that value
    * takes precedence over the default expiration time indicated by this property.
+   *
+   * <p>Update the default table expiration time for a dataset.
+   * <pre> {@code
+   * Dataset dataset = bigquery.getDataset(DatasetId.of("my_dataset"));
+   * Long beforeExpiration = dataset.getDefaultTableLifetime();
+   * 
+   * Long oneDayMilliseconds = 24 * 60 * 60 * 1000L;
+   * Dataset.Builder builder = dataset.toBuilder();
+   * builder.setDefaultTableLifetime(oneDayMilliseconds);
+   * bigquery.update(builder.build());  // API request.
+   * }</pre>
+   *
    */
   public Long getDefaultTableLifetime() {
     return defaultTableLifetime;

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

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2018 Google LLC
+ *
+ * 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 DatasetInfo’s javadoc. Any change to this file should be reflected in
+ * DatasetInfo’s javadoc. Use utilities/add_snipptets_to_file.py to copy.
+ */
+
+package com.google.cloud.examples.bigquery.snippets;
+
+import com.google.cloud.bigquery.Acl;
+import com.google.cloud.bigquery.BigQuery;
+import com.google.cloud.bigquery.DatasetInfo;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * This class contains a number of snippets for the {@link DatasetInfo} interface.
+ */
+public class DatasetInfoSnippets {
+
+  private final BigQuery bigquery;
+
+  public DatasetInfoSnippets(BigQuery bigquery) {
+    this.bigquery = bigquery;
+  }
+
+  /**
+   * Update the ACLs for a dataset.
+   */
+  // [TARGET getAcl()]
+  // [VARIABLE bigquery.getDataset(DatasetId.of("my_dataset"))]
+  public List<Acl> updateDatasetAccess(DatasetInfo dataset) {
+    // [START bigquery_update_dataset_access]
+    List<Acl> beforeAcls = dataset.getAcl();
+
+    // Make a copy of the ACLs so that they can be modified.
+    ArrayList<Acl> acls = new ArrayList<>(beforeAcls);
+    acls.add(Acl.of(new Acl.User("sample.bigquery.dev@gmail.com"), Acl.Role.READER));
+    DatasetInfo.Builder builder = dataset.toBuilder();
+    builder.setAcl(acls);
+
+    bigquery.update(builder.build());  // API request.
+    // [END bigquery_update_dataset_access]
+
+    return beforeAcls;
+  }
+
+  /**
+   * Update the default table expiration time for a dataset.
+   */
+  // [TARGET getDefaultTableLifetime()]
+  // [VARIABLE bigquery.getDataset(DatasetId.of("my_dataset"))]
+  public Long updateDatasetExpiration(DatasetInfo dataset) {
+    // [START bigquery_update_dataset_expiration]
+    Long beforeExpiration = dataset.getDefaultTableLifetime();
+
+    Long oneDayMilliseconds = 24 * 60 * 60 * 1000L;
+    DatasetInfo.Builder builder = dataset.toBuilder();
+    builder.setDefaultTableLifetime(oneDayMilliseconds);
+    bigquery.update(builder.build());  // API request.
+    // [END bigquery_update_dataset_expiration]
+
+    return beforeExpiration;
+  }
+}

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

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2018 Google LLC
+ *
+ * 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.
+ */
+
+package com.google.cloud.examples.bigquery.snippets;
+
+import com.google.cloud.bigquery.Acl;
+import com.google.cloud.bigquery.BigQuery;
+import com.google.cloud.bigquery.BigQuery.DatasetDeleteOption;
+import com.google.cloud.bigquery.Dataset;
+import com.google.cloud.bigquery.DatasetInfo;
+import com.google.cloud.bigquery.testing.RemoteBigQueryHelper;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.Timeout;
+
+import java.io.ByteArrayOutputStream;
+import java.io.PrintStream;
+import java.util.List;
+import java.util.concurrent.ExecutionException;
+
+import static org.junit.Assert.*;
+
+public class ITDatasetInfoSnippets {
+
+  private static final String DATASET = RemoteBigQueryHelper.generateDatasetName();
+
+  private static BigQuery bigquery;
+  private static DatasetInfoSnippets datasetInfoSnippets;
+  private static ByteArrayOutputStream bout;
+  private static PrintStream out;
+
+  @Rule public Timeout globalTimeout = Timeout.seconds(300);
+
+  @BeforeClass
+  public static void beforeClass() {
+    bigquery = RemoteBigQueryHelper.create().getOptions().getService();
+    datasetInfoSnippets = new DatasetInfoSnippets(bigquery);
+    bigquery.create(DatasetInfo.newBuilder(DATASET).build());
+    bout = new ByteArrayOutputStream();
+    out = new PrintStream(bout);
+    System.setOut(out);
+  }
+
+  @AfterClass
+  public static void afterClass() throws ExecutionException, InterruptedException {
+    bigquery.delete(DATASET, DatasetDeleteOption.deleteContents());
+    System.setOut(null);
+  }
+
+  @Test
+  public void testUpdateDatasetAccess() throws InterruptedException {
+    Dataset dataset = bigquery.getDataset(DATASET);
+    List<Acl> beforeAcls = datasetInfoSnippets.updateDatasetAccess(dataset);
+    dataset = bigquery.getDataset(DATASET);
+    List<Acl> afterAcls = dataset.getAcl();
+    assertEquals(beforeAcls.size() + 1, afterAcls.size());
+  }
+
+  @Test
+  public void testUpdateDatasetExpiration() throws InterruptedException {
+    Dataset dataset = bigquery.getDataset(DATASET);
+    Long beforeExpiration = datasetInfoSnippets.updateDatasetExpiration(dataset);
+    dataset = bigquery.getDataset(DATASET);
+    Long afterExpiration = dataset.getDefaultTableLifetime();
+    assertNotEquals(beforeExpiration, afterExpiration);
+  }
+}

utilities/add_snippets_to_file.py

@@ -330,6 +330,9 @@ def __init__(self, data, methods):
             for match in pattern.finditer(data):
                 line_number = len(NEWLINE_PATTERN.findall(data[:match.start()])) + 1
                 signature = method.signature
+                if signature in self.line_numbers:
+                    LOGGER.warning('Method %s duplicate at line %d.', signature, line_number)
+                    continue
                 LOGGER.info('Method %s found at line %d.', signature, line_number)
                 self.line_numbers[signature] = line_number