From cd259275cbec2e1e0480e13bd9202cc90c61e1da Mon Sep 17 00:00:00 2001 From: snehashah16 Date: Thu, 7 Sep 2017 11:59:18 -0700 Subject: [PATCH] Adding snippets for Spanner DatabaseAdminClient. (#2408) * Adding snippets for Spanner DatabaseAdminClient. --- .../snippets/DatabaseAdminClientSnippets.java | 148 ++++++++++++++++++ .../cloud/spanner/DatabaseAdminClient.java | 83 +++++++++- 2 files changed, 228 insertions(+), 3 deletions(-) create mode 100644 google-cloud-examples/src/main/java/com/google/cloud/examples/spanner/snippets/DatabaseAdminClientSnippets.java diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/spanner/snippets/DatabaseAdminClientSnippets.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/spanner/snippets/DatabaseAdminClientSnippets.java new file mode 100644 index 000000000000..e8bc94f946d5 --- /dev/null +++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/spanner/snippets/DatabaseAdminClientSnippets.java @@ -0,0 +1,148 @@ +/* + * Copyright 2017 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 DatabaseAdminClient's javadoc. Any change to this file should be reflected + * in DatabaseAdminClient's javadoc. + */ + +package com.google.cloud.examples.spanner.snippets; + +import com.google.api.gax.paging.Page; +import com.google.common.collect.Iterables; +import com.google.cloud.spanner.DatabaseAdminClient; +import com.google.cloud.spanner.Options; +import com.google.cloud.spanner.Database; +import com.google.cloud.spanner.Operation; +import com.google.spanner.admin.database.v1.CreateDatabaseMetadata; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +/** + * This class contains snippets for {@link DatabaseAdminClient} interface. + */ +public class DatabaseAdminClientSnippets { + + private final DatabaseAdminClient dbAdminClient; + + public DatabaseAdminClientSnippets(DatabaseAdminClient dbAdminClient) { + this.dbAdminClient = dbAdminClient; + } + + /** + * Example to create database. + */ + // [TARGET createDatabase(String, String, Iterable)] + // [VARIABLE my_instance_id] + // [VARIABLE my_database_id] + public Database createDatabase(String instanceId, String databaseId) { + // [START createDatabase] + Operation op = dbAdminClient + .createDatabase( + instanceId, + databaseId, + Arrays.asList( + "CREATE TABLE Singers (\n" + + " SingerId INT64 NOT NULL,\n" + + " FirstName STRING(1024),\n" + + " LastName STRING(1024),\n" + + " SingerInfo BYTES(MAX)\n" + + ") PRIMARY KEY (SingerId)", + "CREATE TABLE Albums (\n" + + " SingerId INT64 NOT NULL,\n" + + " AlbumId INT64 NOT NULL,\n" + + " AlbumTitle STRING(MAX)\n" + + ") PRIMARY KEY (SingerId, AlbumId),\n" + + " INTERLEAVE IN PARENT Singers ON DELETE CASCADE")); + Database db = op.waitFor().getResult(); + // [END createDatabase] + return db; + } + + /** + * Example to getDatabase. + */ + // [TARGET getDatabase(String, String)] + // [VARIABLE my_instance_id] + // [VARIABLE my_database_id] + public Database getDatabase(String instanceId, String databaseId) { + // [START getDatabase] + Database db = dbAdminClient.getDatabase(instanceId, databaseId); + // [END getDatabase] + return db; + } + + /** + * Example to update the database DDL. + */ + // [TARGET updateDatabaseDdl(String, String, Iterable, String)] + // [VARIABLE my_instance_id] + // [VARIABLE my_database_id] + public void updateDatabaseDdl(String instanceId, String databaseId) { + // [START updateDatabaseDdl] + dbAdminClient.updateDatabaseDdl(instanceId, + databaseId, + Arrays.asList("ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"), + null).waitFor(); + // [END updateDatabaseDdl] + } + + /** + * Example to drop a Cloud Spanner database. + */ + // [TARGET dropDatabase(String, String)] + // [VARIABLE my_instance_id] + // [VARIABLE my_database_id] + public void dropDatabase(String instanceId, String databaseId) { + // [START dropDatabase] + dbAdminClient.dropDatabase(instanceId, databaseId); + // [END dropDatabase] + } + + /** + * Example to get the schema of a Cloud Spanner database. + */ + // [TARGET getDatabaseDdl(String, String)] + // [VARIABLE my_instance_id] + // [VARIABLE my_database_id] + public List getDatabaseDdl(String instanceId, String databaseId) { + // [START getDatabaseDdl] + List statementsInDb = dbAdminClient.getDatabaseDdl(instanceId, databaseId); + // [END getDatabaseDdl] + return statementsInDb; + } + + /** + * Example to get the list of Cloud Spanner database in the given instance. + */ + // [TARGET listDatabases(String, ListOption...)] + // [VARIABLE my_instance_id] + public List listDatabases(String instanceId) { + // [START listDatabases] + Page page = dbAdminClient.listDatabases(instanceId, Options.pageSize(1)); + List dbs = new ArrayList<>(); + while (page != null) { + Database db = Iterables.getOnlyElement(page.getValues()); + dbs.add(db); + page = page.getNextPage(); + } + // [END listDatabases] + return dbs; + } +} diff --git a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java index fe3cb7e3c526..0e1cc22448b5 100644 --- a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java +++ b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java @@ -28,6 +28,30 @@ public interface DatabaseAdminClient { /** * Creates a new database in a Cloud Spanner instance. * + *

Example to create database. + *

 {@code
+   * String instanceId = my_instance_id;
+   * String databaseId = my_database_id;
+   * Operation op = dbAdminClient
+   *     .createDatabase(
+   *         instanceId,
+   *         databaseId,
+   *         Arrays.asList(
+   *             "CREATE TABLE Singers (\n"
+   *                 + "  SingerId   INT64 NOT NULL,\n"
+   *                 + "  FirstName  STRING(1024),\n"
+   *                 + "  LastName   STRING(1024),\n"
+   *                 + "  SingerInfo BYTES(MAX)\n"
+   *                 + ") PRIMARY KEY (SingerId)",
+   *             "CREATE TABLE Albums (\n"
+   *                 + "  SingerId     INT64 NOT NULL,\n"
+   *                 + "  AlbumId      INT64 NOT NULL,\n"
+   *                 + "  AlbumTitle   STRING(MAX)\n"
+   *                 + ") PRIMARY KEY (SingerId, AlbumId),\n"
+   *                 + "  INTERLEAVE IN PARENT Singers ON DELETE CASCADE"));
+   * Database db = op.waitFor().getResult();
+   * }
+ * * @param instanceId the id of the instance in which to create the database. * @param databaseId the id of the database which will be created. It must conform to the regular * expression [a-z][a-z0-9_\-]*[a-z0-9] and be between 2 and 30 characters in length @@ -37,7 +61,17 @@ public interface DatabaseAdminClient { Operation createDatabase( String instanceId, String databaseId, Iterable statements) throws SpannerException; - /** Gets the current state of a Cloud Spanner database. */ + /** + * Gets the current state of a Cloud Spanner database. + * + *

Example to getDatabase. + *

 {@code
+   * String instanceId = my_instance_id;
+   * String databaseId = my_database_id;
+   * Database db = dbAdminClient.getDatabase(instanceId, databaseId);
+   * }
+ * + */ Database getDatabase(String instanceId, String databaseId) throws SpannerException; /** @@ -49,6 +83,16 @@ Operation createDatabase( * problem like a `NULL` value in a column to which `NOT NULL` would be added). If a statement * fails, all subsequent statements in the batch are automatically cancelled. * + *

Example to update the database DDL. + *

 {@code
+   * String instanceId = my_instance_id;
+   * String databaseId = my_database_id;
+   * dbAdminClient.updateDatabaseDdl(instanceId,
+   *     databaseId,
+   *     Arrays.asList("ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"),
+   *     null).waitFor();
+   * }
+ * * @param operationId Operation id assigned to this operation. If null, system will autogenerate * one. This must be unique within a database abd must be a valid identifier * [a-zA-Z][a-zA-Z0-9_]*. @@ -60,15 +104,48 @@ Operation updateDatabaseDdl( @Nullable String operationId) throws SpannerException; - /** Drops a Cloud Spanner database. */ + /** + * Drops a Cloud Spanner database. + * + *

Example to drop a Cloud Spanner database. + *

 {@code
+   * String instanceId = my_instance_id;
+   * String databaseId = my_database_id;
+   * dbAdminClient.dropDatabase(instanceId, databaseId);
+   * }
+ * + */ void dropDatabase(String instanceId, String databaseId) throws SpannerException; /** * Returns the schema of a Cloud Spanner database as a list of formatted DDL statements. This * method does not show pending schema updates. + * + *

Example to get the schema of a Cloud Spanner database. + *

 {@code
+   * String instanceId = my_instance_id;
+   * String databaseId = my_database_id;
+   * List statementsInDb = dbAdminClient.getDatabaseDdl(instanceId, databaseId);
+   * }
+ * */ List getDatabaseDdl(String instanceId, String databaseId); - /** Returns the list of Cloud Spanner database in the given instance. */ + /** + * Returns the list of Cloud Spanner database in the given instance. + * + *

Example to get the list of Cloud Spanner database in the given instance. + *

 {@code
+   * String instanceId = my_instance_id;
+   * Page page = dbAdminClient.listDatabases(instanceId, Options.pageSize(1));
+   * List dbs = new ArrayList<>();
+   * while (page != null) {
+   *   Database db = Iterables.getOnlyElement(page.getValues());
+   *   dbs.add(db);
+   *   page = page.getNextPage();
+   * }
+   * }
+ * + */ Page listDatabases(String instanceId, ListOption... options); }