feat: support DML auto-batching in Connection API

README.md

@@ -19,7 +19,7 @@ If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file:
     <dependency>
       <groupId>com.google.cloud</groupId>
       <artifactId>libraries-bom</artifactId>
-      <version>26.47.0</version>
+      <version>26.48.0</version>
       <type>pom</type>
       <scope>import</scope>
     </dependency>

google-cloud-spanner/clirr-ignored-differences.xml

@@ -758,4 +758,37 @@
     <className>com/google/cloud/spanner/connection/Connection</className>
     <method>boolean isKeepTransactionAlive()</method>
   </difference>
+
+  <!-- Automatic DML batching -->
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>void setAutoBatchDml(boolean)</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>boolean isAutoBatchDml()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>void setAutoBatchDmlUpdateCount(long)</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>long getAutoBatchDmlUpdateCount()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>void setAutoBatchDmlUpdateCountVerification(boolean)</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>boolean isAutoBatchDmlUpdateCountVerification()</method>
+  </difference>
+
 </differences>

google-cloud-spanner/src/main/java/com/google/cloud/spanner/DmlBatchUpdateCountVerificationFailedException.java

@@ -0,0 +1,45 @@
+/*
+ * 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.google.cloud.spanner;
+
+import com.google.cloud.spanner.connection.Connection;
+import java.util.Arrays;
+import java.util.stream.Collectors;
+
+/**
+ * Exception thrown by a {@link Connection} when an automatic DML batch detects that one or more of
+ * the update counts that it returned during the buffering of DML statements does not match with the
+ * actual update counts that were returned after execution.
+ */
+public class DmlBatchUpdateCountVerificationFailedException extends AbortedException {
+  private static final long serialVersionUID = 1L;
+
+  /** Private constructor. Use {@link SpannerExceptionFactory} to create instances. */
+  DmlBatchUpdateCountVerificationFailedException(
+      DoNotConstructDirectly token, long[] expected, long[] actual) {
+    super(
+        token,
+        String.format(
+            "Actual update counts that were returned during execution do not match the previously returned update counts.\n"
+                + "Expected: %s\n"
+                + "Actual: %s\n"
+                + "Set auto_batch_dml_update_count_verification to false to skip this verification.",
+            Arrays.stream(expected).mapToObj(Long::toString).collect(Collectors.joining()),
+            Arrays.stream(actual).mapToObj(Long::toString).collect(Collectors.joining())),
+        /* cause = */ null);
+  }
+}

google-cloud-spanner/src/main/java/com/google/cloud/spanner/SpannerExceptionFactory.java

@@ -116,6 +116,12 @@ public static SpannerBatchUpdateException newSpannerBatchUpdateException(
     return new SpannerBatchUpdateException(token, code, message, updateCounts);
   }
 
+  public static DmlBatchUpdateCountVerificationFailedException
+      newDmlBatchUpdateCountVerificationFailedException(long[] expected, long[] actual) {
+    return new DmlBatchUpdateCountVerificationFailedException(
+        DoNotConstructDirectly.ALLOWED, expected, actual);
+  }
+
   /**
    * Constructs a specific aborted exception that should only be thrown by a connection after an
    * internal retry aborted due to concurrent modifications.

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/Connection.java

@@ -1165,6 +1165,18 @@ default StatementResult execute(Statement statement, Set<ResultType> allowedResu
    */
   ResultSet analyzeQuery(Statement query, QueryAnalyzeMode queryMode);
 
+  void setAutoBatchDml(boolean autoBatchDml);
+
+  boolean isAutoBatchDml();
+
+  void setAutoBatchDmlUpdateCount(long updateCount);
+
+  long getAutoBatchDmlUpdateCount();
+
+  void setAutoBatchDmlUpdateCountVerification(boolean verification);
+
+  boolean isAutoBatchDmlUpdateCountVerification();
+
   /**
    * Enable data boost for partitioned queries. See also {@link #partitionQuery(Statement,
    * PartitionOptions, QueryOption...)}