docs: add Multi Region Encryption samples

README.md

@@ -505,9 +505,12 @@ Samples are in the [`samples/`](https://github.com/googleapis/java-spanner/tree/
 | Batch Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/BatchSample.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/BatchSample.java) |
 | Batch Write At Least Once Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/BatchWriteAtLeastOnceSample.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/BatchWriteAtLeastOnceSample.java) |
 | Copy Backup Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/CopyBackupSample.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/CopyBackupSample.java) |
+| Copy Backup With Multi Region Encryption Key | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/CopyBackupWithMultiRegionEncryptionKey.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/CopyBackupWithMultiRegionEncryptionKey.java) |
 | Create Backup With Encryption Key | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/CreateBackupWithEncryptionKey.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/CreateBackupWithEncryptionKey.java) |
+| Create Backup With Multi Region Encryption Key | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/CreateBackupWithMultiRegionEncryptionKey.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/CreateBackupWithMultiRegionEncryptionKey.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/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/CreateDatabaseWithDefaultLeaderSample.java) |
 | Create Database With Encryption Key | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/CreateDatabaseWithEncryptionKey.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/CreateDatabaseWithEncryptionKey.java) |
+| Create Database With Multi Region Encryption Key | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/CreateDatabaseWithMultiRegionEncryptionKey.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/CreateDatabaseWithMultiRegionEncryptionKey.java) |
 | Create Database With Version Retention Period Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/CreateDatabaseWithVersionRetentionPeriodSample.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/CreateDatabaseWithVersionRetentionPeriodSample.java) |
 | Create Full Backup Schedule Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/CreateFullBackupScheduleSample.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/CreateFullBackupScheduleSample.java) |
 | Create Incremental Backup Schedule Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/CreateIncrementalBackupScheduleSample.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/CreateIncrementalBackupScheduleSample.java) |
@@ -560,6 +563,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/java-spanner/tree/
 | Quickstart Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/QuickstartSample.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/QuickstartSample.java) |
 | Read Data With Database Role | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/ReadDataWithDatabaseRole.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/ReadDataWithDatabaseRole.java) |
 | Restore Backup With Encryption Key | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/RestoreBackupWithEncryptionKey.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/RestoreBackupWithEncryptionKey.java) |
+| Restore Backup With Multi Region Encryption Key | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/RestoreBackupWithMultiRegionEncryptionKey.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/RestoreBackupWithMultiRegionEncryptionKey.java) |
 | Set Max Commit Delay Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/SetMaxCommitDelaySample.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/SetMaxCommitDelaySample.java) |
 | Singer Proto | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/SingerProto.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/SingerProto.java) |
 | Spanner Graph Sample | [source code](https://github.com/googleapis/java-spanner/blob/main/samples/snippets/src/main/java/com/example/spanner/SpannerGraphSample.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/SpannerGraphSample.java) |

samples/snippets/src/main/java/com/example/spanner/CopyBackupWithMultiRegionEncryptionKey.java

@@ -0,0 +1,125 @@
+/*
+ * Copyright 2024 Google Inc.
+ *
+ * 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;
+
+// [START spanner_copy_backup_with_MR_CMEK]
+
+import com.google.cloud.Timestamp;
+import com.google.cloud.spanner.Spanner;
+import com.google.cloud.spanner.SpannerException;
+import com.google.cloud.spanner.SpannerExceptionFactory;
+import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
+import com.google.common.collect.ImmutableList;
+import com.google.spanner.admin.database.v1.Backup;
+import com.google.spanner.admin.database.v1.BackupName;
+import com.google.spanner.admin.database.v1.CopyBackupEncryptionConfig;
+import com.google.spanner.admin.database.v1.CopyBackupEncryptionConfig.EncryptionType;
+import com.google.spanner.admin.database.v1.CopyBackupRequest;
+import com.google.spanner.admin.database.v1.InstanceName;
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.time.ZoneId;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+
+public class CopyBackupWithMultiRegionEncryptionKey {
+
+  static void copyBackupWithMultiRegionEncryptionKey() {
+    // TODO(developer): Replace these variables before running the sample.
+    String projectId = "my-project";
+    String instanceId = "my-instance";
+    String sourceBackupId = "my-backup";
+    String destinationBackupId = "my-destination-backup";
+    String[] kmsKeyNames =
+        new String[] {
+          "projects/" + projectId + "/locations/<location1>/keyRings/<keyRing>/cryptoKeys/<keyId>",
+          "projects/" + projectId + "/locations/<location2>/keyRings/<keyRing>/cryptoKeys/<keyId>",
+          "projects/" + projectId + "/locations/<location3>/keyRings/<keyRing>/cryptoKeys/<keyId>"
+        };
+
+    try (Spanner spanner =
+            SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
+        DatabaseAdminClient databaseAdminClient = spanner.createDatabaseAdminClient()) {
+      copyBackupWithMultiRegionEncryptionKey(
+          databaseAdminClient,
+          projectId,
+          instanceId,
+          sourceBackupId,
+          destinationBackupId,
+          kmsKeyNames);
+    }
+  }
+
+  static void copyBackupWithMultiRegionEncryptionKey(
+      DatabaseAdminClient databaseAdminClient,
+      String projectId,
+      String instanceId,
+      String sourceBackupId,
+      String destinationBackupId,
+      String[] kmsKeyNames) {
+
+    Timestamp expireTime =
+        Timestamp.ofTimeMicroseconds(
+            TimeUnit.MICROSECONDS.convert(
+                System.currentTimeMillis() + TimeUnit.DAYS.toMillis(14), TimeUnit.MILLISECONDS));
+
+    // Initiate the request which returns an OperationFuture.
+    System.out.println("Copying backup [" + destinationBackupId + "]...");
+    CopyBackupRequest request =
+        CopyBackupRequest.newBuilder()
+            .setParent(InstanceName.of(projectId, instanceId).toString())
+            .setBackupId(destinationBackupId)
+            .setSourceBackup(BackupName.of(projectId, instanceId, sourceBackupId).toString())
+            .setExpireTime(expireTime.toProto())
+            .setEncryptionConfig(
+                CopyBackupEncryptionConfig.newBuilder()
+                    .setEncryptionType(EncryptionType.CUSTOMER_MANAGED_ENCRYPTION)
+                    .addAllKmsKeyNames(ImmutableList.copyOf(kmsKeyNames))
+                    .build())
+            .build();
+    Backup destinationBackup;
+    try {
+      // Creates a copy of an existing backup.
+      // Wait for the backup operation to complete.
+      destinationBackup = databaseAdminClient.copyBackupAsync(request).get();
+      System.out.println("Copied backup [" + destinationBackup.getName() + "]");
+    } catch (ExecutionException e) {
+      throw (SpannerException) e.getCause();
+    } catch (InterruptedException e) {
+      throw SpannerExceptionFactory.propagateInterrupt(e);
+    }
+    // Load the metadata of the new backup from the server.
+    destinationBackup = databaseAdminClient.getBackup(destinationBackup.getName());
+    System.out.println(
+        String.format(
+            "Backup %s of size %d bytes was copied at %s for version of database at %s",
+            destinationBackup.getName(),
+            destinationBackup.getSizeBytes(),
+            OffsetDateTime.ofInstant(
+                Instant.ofEpochSecond(
+                    destinationBackup.getCreateTime().getSeconds(),
+                    destinationBackup.getCreateTime().getNanos()),
+                ZoneId.systemDefault()),
+            OffsetDateTime.ofInstant(
+                Instant.ofEpochSecond(
+                    destinationBackup.getVersionTime().getSeconds(),
+                    destinationBackup.getVersionTime().getNanos()),
+                ZoneId.systemDefault())));
+  }
+}
+// [END spanner_copy_backup_with_MR_CMEK]

samples/snippets/src/main/java/com/example/spanner/CreateBackupWithMultiRegionEncryptionKey.java

@@ -0,0 +1,123 @@
+/*
+ * 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;
+
+// [START spanner_create_backup_with_MR_CMEK]
+
+import com.google.cloud.spanner.Spanner;
+import com.google.cloud.spanner.SpannerExceptionFactory;
+import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
+import com.google.common.collect.ImmutableList;
+import com.google.protobuf.Timestamp;
+import com.google.spanner.admin.database.v1.Backup;
+import com.google.spanner.admin.database.v1.BackupName;
+import com.google.spanner.admin.database.v1.CreateBackupEncryptionConfig;
+import com.google.spanner.admin.database.v1.CreateBackupEncryptionConfig.EncryptionType;
+import com.google.spanner.admin.database.v1.CreateBackupRequest;
+import com.google.spanner.admin.database.v1.DatabaseName;
+import com.google.spanner.admin.database.v1.InstanceName;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import org.threeten.bp.LocalDateTime;
+import org.threeten.bp.OffsetDateTime;
+
+public class CreateBackupWithMultiRegionEncryptionKey {
+
+  static void createBackupWithMultiRegionEncryptionKey() {
+    // TODO(developer): Replace these variables before running the sample.
+    String projectId = "my-project";
+    String instanceId = "my-instance";
+    String databaseId = "my-database";
+    String backupId = "my-backup";
+    String[] kmsKeyNames =
+        new String[] {
+          "projects/" + projectId + "/locations/<location1>/keyRings/<keyRing>/cryptoKeys/<keyId>",
+          "projects/" + projectId + "/locations/<location2>/keyRings/<keyRing>/cryptoKeys/<keyId>",
+          "projects/" + projectId + "/locations/<location3>/keyRings/<keyRing>/cryptoKeys/<keyId>"
+        };
+
+    try (Spanner spanner =
+            SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
+        DatabaseAdminClient adminClient = spanner.createDatabaseAdminClient()) {
+      createBackupWithMultiRegionEncryptionKey(
+          adminClient, projectId, instanceId, databaseId, backupId, kmsKeyNames);
+    }
+  }
+
+  static Void createBackupWithMultiRegionEncryptionKey(
+      DatabaseAdminClient adminClient,
+      String projectId,
+      String instanceId,
+      String databaseId,
+      String backupId,
+      String[] kmsKeyNames) {
+    // Set expire time to 14 days from now.
+    final Timestamp expireTime =
+        Timestamp.newBuilder()
+            .setSeconds(
+                TimeUnit.MILLISECONDS.toSeconds(
+                    (System.currentTimeMillis() + TimeUnit.DAYS.toMillis(14))))
+            .build();
+    final BackupName backupName = BackupName.of(projectId, instanceId, backupId);
+    Backup backup =
+        Backup.newBuilder()
+            .setName(backupName.toString())
+            .setDatabase(DatabaseName.of(projectId, instanceId, databaseId).toString())
+            .setExpireTime(expireTime)
+            .build();
+
+    final CreateBackupRequest request =
+        CreateBackupRequest.newBuilder()
+            .setParent(InstanceName.of(projectId, instanceId).toString())
+            .setBackupId(backupId)
+            .setBackup(backup)
+            .setEncryptionConfig(
+                CreateBackupEncryptionConfig.newBuilder()
+                    .setEncryptionType(EncryptionType.CUSTOMER_MANAGED_ENCRYPTION)
+                    .addAllKmsKeyNames(ImmutableList.copyOf(kmsKeyNames))
+                    .build())
+            .build();
+    try {
+      System.out.println("Waiting for operation to complete...");
+      backup = adminClient.createBackupAsync(request).get(1200, TimeUnit.SECONDS);
+    } catch (ExecutionException e) {
+      // If the operation failed during execution, expose the cause.
+      throw SpannerExceptionFactory.asSpannerException(e.getCause());
+    } 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);
+    } catch (TimeoutException e) {
+      // If the operation timed out propagates the timeout
+      throw SpannerExceptionFactory.propagateTimeout(e);
+    }
+    System.out.printf(
+        "Backup %s of size %d bytes was created at %s using encryption keys %s%n",
+        backup.getName(),
+        backup.getSizeBytes(),
+        LocalDateTime.ofEpochSecond(
+            backup.getCreateTime().getSeconds(),
+            backup.getCreateTime().getNanos(),
+            OffsetDateTime.now().getOffset()),
+        ImmutableList.copyOf(kmsKeyNames));
+
+    return null;
+  }
+}
+// [END spanner_create_backup_with_MR_CMEK]