spanner: Add snippets for Spanner, BatchClient and BatchReadOnlyTrans…

…action (googleapis#3611)

google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/BatchClient.java

@@ -38,6 +38,12 @@ public interface BatchClient {
    * {@link BatchReadOnlyTransaction}.
    *
    * @param bound the timestamp bound at which to perform the read
+   *
+   * <!--SNIPPET batch_client_strong_read-->
+   * <pre>{@code
+   * BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(TimestampBound.strong());
+   * }</pre>
+   * <!--SNIPPET batch_client_strong_read-->
    */
   BatchReadOnlyTransaction batchReadOnlyTransaction(TimestampBound bound);
 
@@ -52,6 +58,13 @@ public interface BatchClient {
    *
    * @param batchTransactionId to re-initialize the transaction, re-using the timestamp for
    *     successive read/query.
+   *
+   * <!--SNIPPET batch_client_read_with_id-->
+   * <pre>{@code
+   * BatchTransactionId txnId = my_txn.getBatchTransactionId();
+   * BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(txnId);
+   * }</pre>
+   * <!--SNIPPET batch_client_read_with_id-->
    */
   BatchReadOnlyTransaction batchReadOnlyTransaction(BatchTransactionId batchTransactionId);
 }

google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/BatchReadOnlyTransaction.java

@@ -54,6 +54,29 @@ public interface BatchReadOnlyTransaction extends ReadOnlyTransaction {
    * @param columns the columns to read
    * @param options the options to configure the read, supported values are
    * {@link Options#prefetchChunks()}
+   *
+   * <!--SNIPPET partition_read-->
+   * <pre>{@code
+   * final BatchReadOnlyTransaction txn =
+   *     batchClient.batchReadOnlyTransaction(TimestampBound.strong());
+   * List<Partition> partitions =
+   *     txn.partitionRead(
+   *         PartitionOptions.getDefaultInstance(),
+   *         "Singers",
+   *         KeySet.all(),
+   *         Arrays.asList("SingerId", "FirstName", "LastName"));
+   * for (final Partition p : partitions) {
+   *   try (ResultSet results = txn.execute(p)) {
+   *     while (results.next()) {
+   *       long singerId = results.getLong(0);
+   *       String firstName = results.getString(1);
+   *       String lastName = results.getString(2);
+   *       System.out.println("P2 [" + singerId + "] " + firstName + " " + lastName);
+   *     }
+   *   }
+   * }
+   * }</pre>
+   * <!--SNIPPET partition_read-->
    */
   List<Partition> partitionRead(
       PartitionOptions partitionOptions,
@@ -76,6 +99,30 @@ List<Partition> partitionRead(
    *     rows are returned in the natural key order of the index.
    * @param columns the columns to read
    * @param options the options to configure the read
+   *
+   * <!--SNIPPET partition_read_using_index-->
+   * <pre>{@code
+   * final BatchReadOnlyTransaction txn =
+   *     batchClient.batchReadOnlyTransaction(TimestampBound.strong());
+   * List<Partition> partitions =
+   *     txn.partitionReadUsingIndex(
+   *         PartitionOptions.getDefaultInstance(),
+   *         "Singers",
+   *         "SingerId",
+   *         KeySet.all(),
+   *         Arrays.asList("FirstName"));
+   * BatchTransactionId txnID = txn.getBatchTransactionId();
+   * int numRowsRead = 0;
+   * for (Partition p : partitions) {
+   *   BatchReadOnlyTransaction batchTxnOnEachWorker = batchClient.batchReadOnlyTransaction(txnID);
+   *   try (ResultSet results = batchTxnOnEachWorker.execute(p)) {
+   *     while (results.next()) {
+   *       System.out.println(results.getString(0));
+   *     }
+   *   }
+   * }
+   * }</pre>
+   * <!--SNIPPET partition_read_using_index-->
    */
   List<Partition> partitionReadUsingIndex(
       PartitionOptions partitionOptions,
@@ -95,6 +142,26 @@ List<Partition> partitionReadUsingIndex(
    * @param partitionOptions configuration for size and count of partitions returned
    * @param statement the query statement to execute
    * @param options the options to configure the query
+   *
+   * <!--SNIPPET partition_query-->
+   * <pre>{@code
+   * final BatchReadOnlyTransaction txn =
+   *     batchClient.batchReadOnlyTransaction(TimestampBound.strong());
+   * List<Partition> partitions = txn.partitionQuery(PartitionOptions.getDefaultInstance(),
+   *     Statement.of("SELECT SingerId, FirstName, LastName FROM Singers"));
+   *
+   * for (final Partition p : partitions) {
+   *   try (ResultSet results = txn.execute(p)) {
+   *     while (results.next()) {
+   *       long singerId = results.getLong(0);
+   *       String firstName = results.getString(1);
+   *       String lastName = results.getString(2);
+   *       System.out.println("[" + singerId + "] " + firstName + " " + lastName);
+   *     }
+   *   }
+   * }
+   * }</pre>
+   * <!--SNIPPET partition_query-->
    */
   List<Partition> partitionQuery(
       PartitionOptions partitionOptions, Statement statement, QueryOption... options)
@@ -103,12 +170,41 @@ List<Partition> partitionQuery(
   /**
    * Execute the partition to return {@link ResultSet}. The result returned could be zero or more
    * rows. The row metadata may be absent if no rows are returned.
+   *
+   * <!--SNIPPET partition_query-->
+   * <pre>{@code
+   * final BatchReadOnlyTransaction txn =
+   *     batchClient.batchReadOnlyTransaction(TimestampBound.strong());
+   * List<Partition> partitions = txn.partitionQuery(PartitionOptions.getDefaultInstance(),
+   *     Statement.of("SELECT SingerId, FirstName, LastName FROM Singers"));
+   *
+   * for (final Partition p : partitions) {
+   *   try (ResultSet results = txn.execute(p)) {
+   *     while (results.next()) {
+   *       long singerId = results.getLong(0);
+   *       String firstName = results.getString(1);
+   *       String lastName = results.getString(2);
+   *       System.out.println("[" + singerId + "] " + firstName + " " + lastName);
+   *     }
+   *   }
+   * }
+   * }</pre>
+   * <!--SNIPPET partition_query-->
+   *
    */
   ResultSet execute(Partition partition) throws SpannerException;
 
   /**
    * Returns a {@link BatchTransactionId} to be re-used across several machines/processes. This
    * BatchTransactionId guarantees the subsequent read/query to be executed at the same timestamp.
+   *
+   * <!--SNIPPET batch_client_read_with_id-->
+   * <pre>{@code
+   * BatchTransactionId txnId = my_txn.getBatchTransactionId();
+   * BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(txnId);
+   * }</pre>
+   * <!--SNIPPET batch_client_read_with_id-->
+   *
    */
   BatchTransactionId getBatchTransactionId();
 }

google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/Spanner.java

@@ -26,14 +26,45 @@
  */
 public interface Spanner extends Service<SpannerOptions> {
   /** Returns a {@code DatabaseAdminClient} to do admin operations on Cloud Spanner databases. */
+  /*
+   * <!--SNIPPET get_dbadmin_client-->
+   * <pre>{@code
+   * SpannerOptions options = SpannerOptions.newBuilder().build();
+   * Spanner spanner = options.getService();
+   * DatabaseAdminClient dbAdminClient = spanner.getDatabaseAdminClient();
+   * }</pre>
+   * <!--SNIPPET get_dbadmin_client-->
+   */
   DatabaseAdminClient getDatabaseAdminClient();
 
   /** Returns an {@code InstanceAdminClient} to do admin operations on Cloud Spanner instances. */
+  /*
+   * <!--SNIPPET get_instance_admin_client-->
+   * <pre>{@code
+   * SpannerOptions options = SpannerOptions.newBuilder().build();
+   * Spanner spanner = options.getService();
+   * InstanceAdminClient instanceAdminClient = spanner.getInstanceAdminClient();
+   * }</pre>
+   * <!--SNIPPET get_instance_admin_client-->
+   */
   InstanceAdminClient getInstanceAdminClient();
 
   /**
    * Returns a {@code DatabaseClient} for the given database. It uses a pool of sessions to talk to
    * the database.
+   *
+   * <!--SNIPPET get_db_client-->
+   * <pre>{@code
+   * SpannerOptions options = SpannerOptions.newBuilder().build();
+   * Spanner spanner = options.getService();
+   * final String project = "test-project";
+   * final String instance = "test-instance";
+   * final String database = "example-db";
+   * DatabaseId db =
+   *     DatabaseId.of("span-cloud-testing", "nsujir-ins", "example-db");
+   * DatabaseClient dbClient = spanner.getDatabaseClient(db);
+   * }</pre>
+   * <!--SNIPPET get_db_client-->
    */
   DatabaseClient getDatabaseClient(DatabaseId db);
 
@@ -45,6 +76,19 @@ public interface Spanner extends Service<SpannerOptions> {
    * yet at the same snapshot.
    *
    * <p> For all other use cases, {@code DatabaseClient} is more appropriate and performant.
+   *
+   * <!--SNIPPET get_batch_client-->
+   * <pre>{@code
+   * SpannerOptions options = SpannerOptions.newBuilder().build();
+   * Spanner spanner = options.getService();
+   * final String project = "test-project";
+   * final String instance = "test-instance";
+   * final String database = "example-db";
+   * DatabaseId db =
+   *     DatabaseId.of("span-cloud-testing", "nsujir-ins", "example-db");
+   * BatchClient batchClient = spanner.getBatchClient(db);
+   * }</pre>
+   * <!--SNIPPET get_batch_client-->
    */
   BatchClient getBatchClient(DatabaseId db);
 

google-cloud-examples/src/main/java/com/google/cloud/examples/spanner/snippets/BatchClientSnippets.java

@@ -0,0 +1,138 @@
+/*
+ * 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 spanner/BatchClient's javadoc. Any change
+ * to this file should be reflected in spanner/BatchClient's javadoc.
+ */
+
+package com.google.cloud.examples.spanner.snippets;
+
+import com.google.cloud.spanner.BatchClient;
+import com.google.cloud.spanner.BatchReadOnlyTransaction;
+import com.google.cloud.spanner.BatchTransactionId;
+import com.google.cloud.spanner.KeySet;
+import com.google.cloud.spanner.Partition;
+import com.google.cloud.spanner.PartitionOptions;
+import com.google.cloud.spanner.ResultSet;
+import com.google.cloud.spanner.Statement;
+import com.google.cloud.spanner.TimestampBound;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * This class contains snippets for {@link com.google.cloud.spanner.BatchClient} interface.
+ */
+public class BatchClientSnippets {
+
+  private final BatchClient batchClient;
+
+  public BatchClientSnippets(BatchClient batchClient) {
+    this.batchClient = batchClient;
+  }
+
+  /**
+   * Example to do a batch strong read.
+   */
+  BatchReadOnlyTransaction readStrong() {
+    // [START batch_client_strong_read]
+    BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(TimestampBound.strong());
+    // [END batch_client_strong_read]
+    return txn;
+  }
+
+  /**
+   * Example to do a batch read with txn id.
+   */
+  BatchReadOnlyTransaction readWithId(BatchReadOnlyTransaction my_txn) {
+    // [START batch_client_read_with_id]
+    BatchTransactionId txnId = my_txn.getBatchTransactionId();
+    BatchReadOnlyTransaction txn = batchClient.batchReadOnlyTransaction(txnId);
+    // [END batch_client_read_with_id]
+
+    return txn;
+  }
+
+  void partitionQuery() {
+    // [START partition_query]
+    final BatchReadOnlyTransaction txn =
+        batchClient.batchReadOnlyTransaction(TimestampBound.strong());
+    List<Partition> partitions = txn.partitionQuery(PartitionOptions.getDefaultInstance(),
+        Statement.of("SELECT SingerId, FirstName, LastName FROM Singers"));
+
+    for (final Partition p : partitions) {
+      try (ResultSet results = txn.execute(p)) {
+        while (results.next()) {
+          long singerId = results.getLong(0);
+          String firstName = results.getString(1);
+          String lastName = results.getString(2);
+          System.out.println("[" + singerId + "] " + firstName + " " + lastName);
+        }
+      }
+    }
+    // [END partition_query]
+
+  }
+
+  void partitionRead() {
+    // [START partition_read]
+    final BatchReadOnlyTransaction txn =
+        batchClient.batchReadOnlyTransaction(TimestampBound.strong());
+    List<Partition> partitions =
+        txn.partitionRead(
+            PartitionOptions.getDefaultInstance(),
+            "Singers",
+            KeySet.all(),
+            Arrays.asList("SingerId", "FirstName", "LastName"));
+    for (final Partition p : partitions) {
+      try (ResultSet results = txn.execute(p)) {
+        while (results.next()) {
+          long singerId = results.getLong(0);
+          String firstName = results.getString(1);
+          String lastName = results.getString(2);
+          System.out.println("P2 [" + singerId + "] " + firstName + " " + lastName);
+        }
+      }
+    }
+    // [END partition_read]
+  }
+
+  void partitionReadUsingIndex() {
+    // [START partition_read_using_index]
+    final BatchReadOnlyTransaction txn =
+        batchClient.batchReadOnlyTransaction(TimestampBound.strong());
+    List<Partition> partitions =
+        txn.partitionReadUsingIndex(
+            PartitionOptions.getDefaultInstance(),
+            "Singers",
+            "SingerId",
+            KeySet.all(),
+            Arrays.asList("FirstName"));
+    BatchTransactionId txnID = txn.getBatchTransactionId();
+    int numRowsRead = 0;
+    for (Partition p : partitions) {
+      BatchReadOnlyTransaction batchTxnOnEachWorker = batchClient.batchReadOnlyTransaction(txnID);
+      try (ResultSet results = batchTxnOnEachWorker.execute(p)) {
+        while (results.next()) {
+          System.out.println(results.getString(0));
+        }
+      }
+    }
+    // [END partition_read_using_index]
+  }
+}
+