docs: samples and tests for instance APIs.

README.md

@@ -57,13 +57,13 @@ implementation 'com.google.cloud:google-cloud-spanner'
 If you are using Gradle without BOM, add this to your dependencies:
 
 ```Groovy
-implementation 'com.google.cloud:google-cloud-spanner:6.55.0'
+implementation 'com.google.cloud:google-cloud-spanner:6.56.0'
 ```
 
 If you are using SBT, add this to your dependencies:
 
 ```Scala
-libraryDependencies += "com.google.cloud" % "google-cloud-spanner" % "6.55.0"
+libraryDependencies += "com.google.cloud" % "google-cloud-spanner" % "6.56.0"
 ```
 <!-- {x-version-update-end} -->
 
@@ -331,7 +331,15 @@ Samples are in the [`samples/`](https://github.com/googleapis/java-spanner/tree/
 | Update Numeric Data Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/UpdateNumericDataSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/UpdateNumericDataSample.java) |
 | Update Using Dml Returning Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/UpdateUsingDmlReturningSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/UpdateUsingDmlReturningSample.java) |
 | Create Database With Default Leader Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateDatabaseWithDefaultLeaderSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateDatabaseWithDefaultLeaderSample.java) |
+| Create Instance Config Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceConfigSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceConfigSample.java) |
 | Create Instance Example | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceExample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceExample.java) |
+| Create Instance With Autoscaling Config Example | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceWithAutoscalingConfigExample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceWithAutoscalingConfigExample.java) |
+| Create Instance With Processing Units Example | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceWithProcessingUnitsExample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceWithProcessingUnitsExample.java) |
+| Delete Instance Config Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/DeleteInstanceConfigSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/DeleteInstanceConfigSample.java) |
+| Get Instance Config Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/GetInstanceConfigSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/GetInstanceConfigSample.java) |
+| List Instance Config Operations Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/ListInstanceConfigOperationsSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/ListInstanceConfigOperationsSample.java) |
+| List Instance Configs Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/ListInstanceConfigsSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/ListInstanceConfigsSample.java) |
+| Update Instance Config Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/admin/generated/UpdateInstanceConfigSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-spanner&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/spanner/admin/generated/UpdateInstanceConfigSample.java) |
 
 
 
@@ -435,7 +443,7 @@ Java is a registered trademark of Oracle and/or its affiliates.
 [kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-spanner/java11.html
 [stability-image]: https://img.shields.io/badge/stability-stable-green
 [maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-spanner.svg
-[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-spanner/6.55.0
+[maven-version-link]: https://central.sonatype.com/artifact/com.google.cloud/google-cloud-spanner/6.56.0
 [authentication]: https://github.com/googleapis/google-cloud-java#authentication
 [auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
 [predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles

samples/install-without-bom/pom.xml

@@ -15,6 +15,7 @@
     <groupId>com.google.cloud.samples</groupId>
     <artifactId>shared-configuration</artifactId>
     <version>1.2.0</version>
+    <relativePath></relativePath>
   </parent>
 
   <properties>
@@ -144,7 +145,7 @@
           <systemPropertyVariables>
             <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.instance.config>nam11</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/native-image/pom.xml

@@ -14,6 +14,7 @@
     <groupId>com.google.cloud.samples</groupId>
     <artifactId>shared-configuration</artifactId>
     <version>1.2.0</version>
+    <relativePath></relativePath>
   </parent>
 
   <properties>

samples/snapshot/pom.xml

@@ -15,6 +15,7 @@
     <groupId>com.google.cloud.samples</groupId>
     <artifactId>shared-configuration</artifactId>
     <version>1.2.0</version>
+    <relativePath></relativePath>
   </parent>
 
   <properties>
@@ -143,7 +144,7 @@
           <systemPropertyVariables>
             <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.instance.config>nam11</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/pom.xml

@@ -180,7 +180,7 @@
           <systemPropertyVariables>
             <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.instance.config>nam11</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/admin/generated/CreateDatabaseWithDefaultLeaderSample.java

@@ -39,9 +39,7 @@ static void createDatabaseWithDefaultLeader() throws IOException {
 
   static void createDatabaseWithDefaultLeader(String instanceName, String databaseId,
       String defaultLeader) throws IOException {
-    DatabaseAdminClient databaseAdminClient = DatabaseAdminClient.create();
-
-    try {
+    try (DatabaseAdminClient databaseAdminClient = DatabaseAdminClient.create()) {
       Database createdDatabase =
           databaseAdminClient.createDatabaseAsync(
               CreateDatabaseRequest.newBuilder()

samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceConfigSample.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2024 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.admin.generated;
+
+// [START spanner_create_instance_config]
+
+import com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;
+import com.google.spanner.admin.instance.v1.CreateInstanceConfigRequest;
+import com.google.spanner.admin.instance.v1.InstanceConfig;
+import com.google.spanner.admin.instance.v1.InstanceConfigName;
+import com.google.spanner.admin.instance.v1.ProjectName;
+import com.google.spanner.admin.instance.v1.ReplicaInfo;
+import java.io.IOException;
+import java.util.List;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+class CreateInstanceConfigSample {
+
+  static void createInstanceConfig() throws IOException {
+    // TODO(developer): Replace these variables before running the sample.
+    String projectId = "my-project";
+    String baseInstanceConfigId = "nam11";
+    String instanceConfigId = "custom-instance-config4";
+
+    createInstanceConfig(projectId, baseInstanceConfigId, instanceConfigId);
+  }
+
+  static void createInstanceConfig(
+      String projectId, String baseInstanceConfigId, String instanceConfigId) throws IOException {
+    try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
+      final InstanceConfigName baseInstanceConfigName = InstanceConfigName.of(projectId,
+          baseInstanceConfigId);
+      final InstanceConfig baseConfig =
+          instanceAdminClient.getInstanceConfig(baseInstanceConfigName.toString());
+      final InstanceConfigName instanceConfigName = InstanceConfigName.of(projectId,
+          instanceConfigId);
+      /**
+       * The replicas for the custom instance configuration must include all the replicas of the
+       * base configuration, in addition to at least one from the list of optional replicas of the
+       * base configuration.
+       */
+      final List<ReplicaInfo> replicas =
+          Stream.concat(baseConfig.getReplicasList().stream(),
+              baseConfig.getOptionalReplicasList().stream().limit(1)).collect(Collectors.toList());
+      final InstanceConfig instanceConfig =
+          InstanceConfig.newBuilder().setName(instanceConfigName.toString())
+              .setBaseConfig(baseInstanceConfigName.toString())
+              .setDisplayName("Instance Configuration").addAllReplicas(replicas).build();
+      final CreateInstanceConfigRequest createInstanceConfigRequest =
+          CreateInstanceConfigRequest.newBuilder().setParent(ProjectName.of(projectId).toString())
+              .setInstanceConfigId(instanceConfigId).setInstanceConfig(instanceConfig).build();
+      try {
+        System.out.printf("Waiting for create operation for %s to complete...\n",
+            instanceConfigName);
+        InstanceConfig instanceConfigResult =
+            instanceAdminClient.createInstanceConfigAsync(
+                createInstanceConfigRequest).get(5, TimeUnit.MINUTES);
+        System.out.printf("Created instance configuration %s\n", instanceConfigResult.getName());
+      } catch (ExecutionException | TimeoutException e) {
+        System.out.printf(
+            "Error: Creating instance configuration %s failed with error message %s\n",
+            instanceConfig.getName(), e.getMessage());
+      } catch (InterruptedException e) {
+        System.out.println(
+            "Error: Waiting for createInstanceConfig operation to finish was interrupted");
+      }
+    }
+  }
+}
+// [END spanner_create_instance_config]

samples/snippets/src/main/java/com/example/spanner/admin/generated/CreateInstanceExample.java

@@ -17,6 +17,7 @@
 package com.example.spanner.admin.generated;
 
 //[START spanner_create_instance]
+
 import com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;
 import com.google.spanner.admin.instance.v1.CreateInstanceRequest;
 import com.google.spanner.admin.instance.v1.Instance;
@@ -35,35 +36,35 @@ static void createInstance() throws IOException {
   }
 
   static void createInstance(String projectId, String instanceId) throws IOException {
-    InstanceAdminClient instanceAdminClient = InstanceAdminClient.create();
-
-    // Set Instance configuration.
-    int nodeCount = 2;
-    String displayName = "Descriptive name";
+    try (InstanceAdminClient instanceAdminClient = InstanceAdminClient.create()) {
+      // 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();
-    try {
-      // Wait for the createInstance operation to finish.
-      Instance createdInstance = instanceAdminClient.createInstanceAsync(
-          CreateInstanceRequest.newBuilder()
-              .setParent(ProjectName.of(projectId).toString())
-              .setInstanceId(instanceId)
-              .setInstance(instance)
-              .build()).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());
-    } catch (InterruptedException e) {
-      System.out.println("Error: Waiting for createInstance operation to finish was interrupted");
+      // 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();
+      try {
+        // Wait for the createInstance operation to finish.
+        Instance createdInstance = instanceAdminClient.createInstanceAsync(
+            CreateInstanceRequest.newBuilder()
+                .setParent(ProjectName.of(projectId).toString())
+                .setInstanceId(instanceId)
+                .setInstance(instance)
+                .build()).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());
+      } catch (InterruptedException e) {
+        System.out.println("Error: Waiting for createInstance operation to finish was interrupted");
+      }
     }
   }
 }