docs(samples): add samples and tests for change streams txn exclusion

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

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2021 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;
+
+import com.google.cloud.spanner.DatabaseClient;
+import com.google.cloud.spanner.DatabaseId;
+import com.google.cloud.spanner.Options;
+import com.google.cloud.spanner.Spanner;
+import com.google.cloud.spanner.SpannerOptions;
+import com.google.cloud.spanner.Statement;
+
+/**
+ * Sample showing how to set exclude transaction from change streams in different write requests.
+ */
+public class ChangeStreamsTxnExclusionSample {
+
+  static void setExcludeTxnFromChangeStreams() {
+    // TODO(developer): Replace these variables before running the sample.
+    final String projectId = "my-instance";
+    final String instanceId = "my-project";
+    final String databaseId = "my-database";
+
+    try (Spanner spanner =
+        SpannerOptions.newBuilder().setProjectId(projectId).build().getService()) {
+      final DatabaseClient databaseClient =
+          spanner.getDatabaseClient(DatabaseId.of(projectId, instanceId, databaseId));
+      rwTxnExcludedFromChangeStreams(databaseClient);
+    }
+  }
+
+  // [START spanner_set_exclude_txn_from_change_streams]
+  static void rwTxnExcludedFromChangeStreams(DatabaseClient client) {
+    // Exclude the transaction from allowed tracking change streams with alloww_txn_exclusion=true.
+    // This exclusion will be applied to all the individual operations inside this transaction.
+    client
+        .readWriteTransaction(Options.excludeTxnFromChangeStreams())
+        .run(
+            transaction -> {
+              transaction.executeUpdate(
+                  Statement.of(
+                      "INSERT Singers (SingerId, FirstName, LastName)\n"
+                          + "VALUES (1341, 'Virginia', 'Watson')"));
+              System.out.println("New singer inserted.");
+
+              transaction.executeUpdate(
+                  Statement.of("UPDATE Singers SET FirstName = 'Hi' WHERE SingerId = 111"));
+              System.out.println("Singer first name updated.");
+
+              return null;
+            });
+  }
+  // [END spanner_set_exclude_txn_from_change_streams]
+
+}

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

@@ -0,0 +1,97 @@
+/*
+ * 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;
+
+import static com.example.spanner.SampleRunner.runSample;
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.cloud.spanner.DatabaseClient;
+import com.google.cloud.spanner.DatabaseId;
+import com.google.cloud.spanner.KeySet;
+import com.google.cloud.spanner.Mutation;
+import com.google.common.collect.ImmutableList;
+import java.util.Arrays;
+import java.util.Collections;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Integration tests for {@link ChangeStreamsTxnExclusionSample} */
+@RunWith(JUnit4.class)
+public class ChangeStreamsTxnExclusionSampleIT extends SampleTestBase {
+
+  private static DatabaseId databaseId;
+
+  @BeforeClass
+  public static void createTestDatabase() throws Exception {
+    final String database = idGenerator.generateDatabaseId();
+    databaseAdminClient
+        .createDatabase(
+            instanceId,
+            database,
+            ImmutableList.of(
+                "CREATE TABLE Singers ("
+                    + "  SingerId   INT64 NOT NULL,"
+                    + "  FirstName  STRING(1024),"
+                    + "  LastName   STRING(1024),"
+                    + "  SingerInfo BYTES(MAX)"
+                    + ") PRIMARY KEY (SingerId)"))
+        .get();
+    databaseId = DatabaseId.of(projectId, instanceId, database);
+  }
+
+  @Before
+  public void insertTestData() {
+    final DatabaseClient client = spanner.getDatabaseClient(databaseId);
+    client.write(
+        Arrays.asList(
+            Mutation.newInsertBuilder("Singers")
+                .set("SingerId")
+                .to(1L)
+                .set("FirstName")
+                .to("first name 1")
+                .set("LastName")
+                .to("last name 1")
+                .build(),
+            Mutation.newInsertBuilder("Singers")
+                .set("SingerId")
+                .to(2L)
+                .set("FirstName")
+                .to("first name 2")
+                .set("LastName")
+                .to("last name 2")
+                .build()));
+  }
+
+  @After
+  public void removeTestData() {
+    final DatabaseClient client = spanner.getDatabaseClient(databaseId);
+    client.write(Collections.singletonList(Mutation.delete("Singers", KeySet.all())));
+  }
+
+  @Test
+  public void testSetExcludeTxnFromChangeStreamsSampleSample() throws Exception {
+    final DatabaseClient client = spanner.getDatabaseClient(databaseId);
+    String out =
+        runSample(() -> ChangeStreamsTxnExclusionSample.rwTxnExcludedFromChangeStreams(client));
+    assertThat(out).contains("New singer inserted.");
+    assertThat(out).contains("Singer first name updated.");
+  }
+}