docs: samples and tests for auto-generated createDatabase and createInstance APIs.

samples/install-without-bom/pom.xml

@@ -142,9 +142,9 @@
         <version>3.1.2</version>
         <configuration>
           <systemPropertyVariables>
-            <spanner.test.instance>spanner-testing-east1</spanner.test.instance>
-            <spanner.test.instance.mr>spanner-mr-testing</spanner.test.instance.mr>
-            <spanner.test.instance.config>nam6</spanner.test.instance.config>
+            <spanner.test.instance>java-client-integration-test</spanner.test.instance>
+            <spanner.test.instance.mr>java-client-mr-integration-test</spanner.test.instance.mr>
+            <spanner.test.instance.config>nam15</spanner.test.instance.config>
             <spanner.test.key.location>us-east1</spanner.test.key.location>
             <spanner.test.key.ring>cmek-test-key-ring</spanner.test.key.ring>
             <spanner.test.key.name>cmek-test-key</spanner.test.key.name>

samples/snapshot/pom.xml

@@ -141,13 +141,14 @@
         <version>3.1.2</version>
         <configuration>
           <systemPropertyVariables>
-            <spanner.test.instance>spanner-testing-east1</spanner.test.instance>
-            <spanner.test.instance.mr>spanner-mr-testing</spanner.test.instance.mr>
-            <spanner.test.instance.config>nam6</spanner.test.instance.config>
+            <spanner.test.instance>java-client-integration-test</spanner.test.instance>
+            <spanner.test.instance.mr>java-client-mr-integration-test</spanner.test.instance.mr>
+            <spanner.test.instance.config>nam15</spanner.test.instance.config>
             <spanner.test.key.location>us-east1</spanner.test.key.location>
             <spanner.test.key.ring>cmek-test-key-ring</spanner.test.key.ring>
             <spanner.test.key.name>cmek-test-key</spanner.test.key.name>
             <spanner.sample.database>mysample</spanner.sample.database>
+            <spanner.sample.instance>mysample-instance</spanner.sample.instance>
             <spanner.quickstart.database>quick-db</spanner.quickstart.database>
           </systemPropertyVariables>
         </configuration>

samples/snippets/pom.xml

@@ -178,9 +178,9 @@
         <version>3.1.2</version>
         <configuration>
           <systemPropertyVariables>
-            <spanner.test.instance>spanner-testing-east1</spanner.test.instance>
-            <spanner.test.instance.mr>spanner-mr-testing</spanner.test.instance.mr>
-            <spanner.test.instance.config>nam6</spanner.test.instance.config>
+            <spanner.test.instance>java-client-integration-test</spanner.test.instance>
+            <spanner.test.instance.mr>java-client-mr-integration-test</spanner.test.instance.mr>
+            <spanner.test.instance.config>nam15</spanner.test.instance.config>
             <spanner.test.key.location>us-east1</spanner.test.key.location>
             <spanner.test.key.ring>cmek-test-key-ring</spanner.test.key.ring>
             <spanner.test.key.name>cmek-test-key</spanner.test.key.name>

samples/snippets/src/main/java/com/example/spanner/v2/CreateDatabaseWithDefaultLeaderSample.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2023 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.example.spanner.v2;
+
+import com.google.api.gax.longrunning.OperationFuture;
+import com.google.cloud.spanner.SpannerExceptionFactory;
+import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
+import com.google.common.collect.ImmutableList;
+import com.google.spanner.admin.database.v1.CreateDatabaseMetadata;
+import com.google.spanner.admin.database.v1.CreateDatabaseRequest;
+import com.google.spanner.admin.database.v1.Database;
+import java.io.IOException;
+import java.util.concurrent.ExecutionException;
+
+public class CreateDatabaseWithDefaultLeaderSample {
+
+  static void createDatabaseWithDefaultLeader() throws IOException {
+    // TODO(developer): Replace these variables before running the sample.
+    final String instanceName = "my-instance-name";
+    final String databaseId = "my-database-name";
+    final String defaultLeader = "my-default-leader";
+    createDatabaseWithDefaultLeader(instanceName, databaseId, defaultLeader);
+  }
+
+  static void createDatabaseWithDefaultLeader(String instanceName, String databaseId,
+      String defaultLeader) throws IOException {
+    DatabaseAdminClient databaseAdminClient = DatabaseAdminClient.create();
+
+    try {
+      OperationFuture<Database, CreateDatabaseMetadata> op1 =
+          databaseAdminClient.createDatabaseAsync(
+              CreateDatabaseRequest.newBuilder()
+                  .setParent(instanceName)
+                  .setCreateStatement("CREATE DATABASE " + "`" + databaseId + "`")
+                  .addAllExtraStatements(
+                      ImmutableList.of("CREATE TABLE Singers ("
+                              + "  SingerId   INT64 NOT NULL,"
+                              + "  FirstName  STRING(1024),"
+                              + "  LastName   STRING(1024),"
+                              + "  SingerInfo BYTES(MAX)"
+                              + ") PRIMARY KEY (SingerId)",
+                          "CREATE TABLE Albums ("
+                              + "  SingerId     INT64 NOT NULL,"
+                              + "  AlbumId      INT64 NOT NULL,"
+                              + "  AlbumTitle   STRING(MAX)"
+                              + ") PRIMARY KEY (SingerId, AlbumId),"
+                              + "  INTERLEAVE IN PARENT Singers ON DELETE CASCADE",
+                          "ALTER DATABASE " + "`" + databaseId + "`"
+                              + " SET OPTIONS ( default_leader = '" + defaultLeader + "' )"))
+                  .build());
+      Database createdDatabase = op1.get();
+      System.out.println("Created database [" + createdDatabase.getName() + "]");
+      System.out.println("\tDefault leader: " + createdDatabase.getDefaultLeader());
+    } catch (ExecutionException e) {
+      // If the operation failed during execution, expose the cause.
+      throw SpannerExceptionFactory.asSpannerException(e);
+    } catch (InterruptedException e) {
+      // Throw when a thread is waiting, sleeping, or otherwise occupied,
+      // and the thread is interrupted, either before or during the activity.
+      throw SpannerExceptionFactory.propagateInterrupt(e);
+    }
+  }
+}

samples/snippets/src/main/java/com/example/spanner/v2/CreateInstanceSample.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2023 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.example.spanner.v2;
+
+import com.google.api.gax.longrunning.OperationFuture;
+import com.google.cloud.spanner.SpannerExceptionFactory;
+import com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;
+import com.google.cloud.spanner.admin.instance.v1.InstanceAdminSettings;
+import com.google.spanner.admin.instance.v1.CreateInstanceMetadata;
+import com.google.spanner.admin.instance.v1.CreateInstanceRequest;
+import com.google.spanner.admin.instance.v1.Instance;
+import com.google.spanner.admin.instance.v1.InstanceConfigName;
+import com.google.spanner.admin.instance.v1.ProjectName;
+import java.io.IOException;
+import java.util.concurrent.ExecutionException;
+
+class CreateInstanceSample {
+
+  static void createInstance() throws IOException {
+    // TODO(developer): Replace these variables before running the sample.
+    String projectId = "my-project";
+    String instanceId = "my-instance";
+    createInstance(projectId, instanceId);
+  }
+
+  static void createInstance(String projectId, String instanceId) throws IOException {
+    InstanceAdminSettings instanceAdminSettings =
+        InstanceAdminSettings.newBuilder().setQuotaProjectId(projectId).build();
+    InstanceAdminClient instanceAdminClient = InstanceAdminClient.create(instanceAdminSettings);
+
+
+    // Set Instance configuration.
+    int nodeCount = 2;
+    String displayName = "Descriptive name";
+
+    // Create an Instance object that will be used to create the instance.
+    Instance instance =
+        Instance.newBuilder()
+            .setDisplayName(displayName)
+            .setNodeCount(nodeCount)
+            .setConfig(
+                InstanceConfigName.of(projectId, "regional-us-central1").toString())
+            .build();
+    OperationFuture<Instance, CreateInstanceMetadata> operation =
+        instanceAdminClient.createInstanceAsync(
+            CreateInstanceRequest.newBuilder()
+                .setParent(ProjectName.of(projectId).toString())
+                .setInstanceId(instanceId)
+                .setInstance(instance)
+                .build());
+
+    try {
+      // Wait for the createInstance operation to finish.
+      Instance createdInstance = operation.get();
+      System.out.printf("Instance %s was successfully created%n", createdInstance.getName());
+    } catch (ExecutionException e) {
+      System.out.printf(
+          "Error: Creating instance %s failed with error message %s%n",
+          instance.getName(), e.getMessage());
+      throw SpannerExceptionFactory.asSpannerException(e);
+    } catch (InterruptedException e) {
+      System.out.println("Error: Waiting for createInstance operation to finish was interrupted");
+      throw SpannerExceptionFactory.propagateInterrupt(e);
+    }
+  }
+}

samples/snippets/src/test/java/com/example/spanner/SampleIdGenerator.java

@@ -26,24 +26,38 @@
  */
 public class SampleIdGenerator {
 
+  private static final int INSTANCE_NAME_MAX_LENGTH = 30;
   private static final int DATABASE_NAME_MAX_LENGTH = 30;
   private static final int BACKUP_NAME_MAX_LENGTH = 30;
   private static final int INSTANCE_CONFIG_ID_MAX_LENGTH = 30;
+  private final List<String> instanceIds;
   private final List<String> databaseIds;
   private final List<String> backupIds;
   private final List<String> instanceConfigIds;
   private final String baseDatabaseId;
   private final String baseBackupId;
   private final String baseInstanceConfigId;
+  private final String baseInstanceId;
 
-  public SampleIdGenerator(
-      String baseDatabaseId, String baseBackupId, String baseInstanceConfigId) {
+  public SampleIdGenerator(String baseDatabaseId, String baseBackupId,
+      String baseInstanceConfigId, String baseInstanceId) {
     this.baseDatabaseId = baseDatabaseId;
     this.baseBackupId = baseBackupId;
     this.baseInstanceConfigId = baseInstanceConfigId;
+    this.baseInstanceId = baseInstanceId;
     this.databaseIds = new ArrayList<>();
     this.backupIds = new ArrayList<>();
     this.instanceConfigIds = new ArrayList<>();
+    this.instanceIds = new ArrayList<>();
+  }
+
+  public String generateInstanceId() {
+    final String instanceId =
+        (baseInstanceId + "-" + UUID.randomUUID().toString().replaceAll("-", ""))
+            .substring(0, INSTANCE_NAME_MAX_LENGTH);
+
+    instanceIds.add(instanceId);
+    return instanceId;
   }
 
   public String generateDatabaseId() {
@@ -81,6 +95,10 @@ public List<String> getBackupIds() {
     return backupIds;
   }
 
+  public List<String> getInstanceIds() {
+    return instanceIds;
+  }
+
   public List<String> getInstanceConfigIds() {
     return instanceConfigIds;
   }

samples/snippets/src/test/java/com/example/spanner/SampleTestBase.java

@@ -25,7 +25,8 @@
 
 /** Base class for sample integration tests. */
 public class SampleTestBase {
-
+  private static final String BASE_INSTANCE_ID =
+      System.getProperty("spanner.sample.instance", "mysample-instance");
   private static final String BASE_DATABASE_ID =
       System.getProperty("spanner.sample.database", "sampledb");
   private static final String BASE_BACKUP_ID = "samplebk";
@@ -56,11 +57,27 @@ public static void beforeClass() {
     spanner = options.getService();
     databaseAdminClient = spanner.getDatabaseAdminClient();
     instanceAdminClient = spanner.getInstanceAdminClient();
-    idGenerator = new SampleIdGenerator(BASE_DATABASE_ID, BASE_BACKUP_ID, BASE_INSTANCE_CONFIG_ID);
+    idGenerator = new SampleIdGenerator(
+        BASE_DATABASE_ID, BASE_BACKUP_ID, BASE_INSTANCE_CONFIG_ID, BASE_INSTANCE_ID);
   }
 
   @AfterClass
   public static void afterClass() {
+    for (String instanceId : idGenerator.getInstanceIds()) {
+      System.out.println("Trying to drop " + instanceId);
+      try {
+        // If the database is not found, it is ignored (no exception is thrown)
+        instanceAdminClient.deleteInstance(instanceId);
+      } catch (Exception e) {
+        System.out.println(
+            "Failed to drop instance "
+                + instanceId
+                + " due to "
+                + e.getMessage()
+                + ", skipping...");
+      }
+    }
+
     for (String databaseId : idGenerator.getDatabaseIds()) {
       System.out.println("Trying to drop " + databaseId);
       try {

samples/snippets/src/test/java/com/example/spanner/v2/CreateDatabaseWithDefaultLeaderSampleIT.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2023 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.example.spanner.v2;
+
+import static org.junit.Assert.assertTrue;
+
+import com.example.spanner.SampleRunner;
+import com.google.spanner.admin.instance.v1.InstanceConfig;
+import com.google.spanner.admin.instance.v1.InstanceName;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+@RunWith(JUnit4.class)
+public class CreateDatabaseWithDefaultLeaderSampleIT extends SampleTestBaseV2 {
+
+  @Test
+  public void testCreateDatabaseWithDefaultLeader() throws Exception {
+    final String databaseId = idGenerator.generateDatabaseId();
+
+    // Finds possible default leader
+
+    final String instanceConfigId = instanceAdminClient.getInstance(
+        InstanceName.of(projectId, multiRegionalInstanceId)).getConfig();
+    final InstanceConfig config = instanceAdminClient.getInstanceConfig(instanceConfigId);
+    assertTrue(
+        "Expected instance config " + instanceConfigId + " to have at least one leader option",
+        config.getLeaderOptionsCount() > 0
+    );
+    final String defaultLeader = config.getLeaderOptions(0);
+
+    // Runs sample
+    final String out = SampleRunner.runSample(() ->
+        CreateDatabaseWithDefaultLeaderSample.createDatabaseWithDefaultLeader(
+            getInstanceName(projectId, multiRegionalInstanceId),
+            databaseId,
+            defaultLeader
+        )
+    );
+
+    assertTrue(
+        "Expected created database to have default leader " + defaultLeader + "."
+            + " Output received was " + out,
+        out.contains("Default leader: " + defaultLeader)
+    );
+  }
+}