chore: cleanup and add comments

Author: olavloite

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

@@ -28,6 +28,10 @@
 public class DmlBatchUpdateCountVerificationFailedException extends AbortedException {
   private static final long serialVersionUID = 1L;
 
+  private final long[] expected;
+
+  private final long[] actual;
+
   /** Private constructor. Use {@link SpannerExceptionFactory} to create instances. */
   DmlBatchUpdateCountVerificationFailedException(
       DoNotConstructDirectly token, long[] expected, long[] actual) {
@@ -41,5 +45,24 @@ public class DmlBatchUpdateCountVerificationFailedException extends AbortedExcep
             Arrays.stream(expected).mapToObj(Long::toString).collect(Collectors.joining()),
             Arrays.stream(actual).mapToObj(Long::toString).collect(Collectors.joining())),
         /* cause = */ null);
+    this.expected = expected;
+    this.actual = actual;
+  }
+
+  /**
+   * The expected update counts. These were returned to the client application when the DML
+   * statements were buffered.
+   */
+  public long[] getExpected() {
+    return Arrays.copyOf(this.expected, this.expected.length);
+  }
+
+  /**
+   * The actual update counts. These were returned by Spanner to the client when the DML statements
+   * were actually executed, and are the update counts that the client application would have
+   * received if auto-batching had not been enabled.
+   */
+  public long[] getActual() {
+    return Arrays.copyOf(this.actual, this.actual.length);
   }
 }

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

@@ -116,6 +116,7 @@ public static SpannerBatchUpdateException newSpannerBatchUpdateException(
     return new SpannerBatchUpdateException(token, code, message, updateCounts);
   }
 
+  /** Constructs a specific error that */
   public static DmlBatchUpdateCountVerificationFailedException
       newDmlBatchUpdateCountVerificationFailedException(long[] expected, long[] actual) {
     return new DmlBatchUpdateCountVerificationFailedException(

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

@@ -1165,16 +1165,43 @@ default StatementResult execute(Statement statement, Set<ResultType> allowedResu
    */
   ResultSet analyzeQuery(Statement query, QueryAnalyzeMode queryMode);
 
+  /**
+   * Enables or disables automatic batching of DML statements. When enabled, DML statements that are
+   * executed on this connection will be buffered in memory instead of actually being executed. The
+   * buffered DML statements are flushed to Spanner when a statement that cannot be part of a DML
+   * batch is executed on the connection. This can be a query, a DDL statement with a THEN RETURN
+   * clause, or a Commit call. The update count that is returned for DML statements that are
+   * buffered is determined by the value that has been set with {@link
+   * #setAutoBatchDmlUpdateCount(long)}. The default is 1. The connection verifies that the update
+   * counts that were returned while buffering DML statements match the actual update counts that
+   * are returned by Spanner when the batch is executed. This verification can be disabled by
+   * calling {@link #setAutoBatchDmlUpdateCountVerification(boolean)}.
+   */
   void setAutoBatchDml(boolean autoBatchDml);
 
+  /** Returns whether automatic DML batching is enabled on this connection. */
   boolean isAutoBatchDml();
 
+  /**
+   * Sets the update count that is returned for DML statements that are buffered during an automatic
+   * DML batch. This value is only used if {@link #isAutoBatchDml()} is enabled.
+   */
   void setAutoBatchDmlUpdateCount(long updateCount);
 
+  /**
+   * Returns the update count that is returned for DML statements that are buffered during an
+   * automatic DML batch.
+   */
   long getAutoBatchDmlUpdateCount();
 
+  /**
+   * Sets whether the update count that is returned by Spanner after executing an automatic DML
+   * batch should be verified against the update counts that were returned during the buffering of
+   * those statements.
+   */
   void setAutoBatchDmlUpdateCountVerification(boolean verification);
 
+  /** Indicates whether the update counts of automatic DML batches should be verified. */
   boolean isAutoBatchDmlUpdateCountVerification();
 
   /**

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

@@ -118,7 +118,7 @@ class ConnectionImpl implements Connection {
           .parse(Statement.of("START BATCH DDL"));
   private static final ParsedStatement START_BATCH_DML_STATEMENT =
       AbstractStatementParser.getInstance(Dialect.GOOGLE_STANDARD_SQL)
-          .parse(Statement.of("START BATCH DDL"));
+          .parse(Statement.of("START BATCH DML"));
   private static final ParsedStatement RUN_BATCH_STATEMENT =
       AbstractStatementParser.getInstance(Dialect.GOOGLE_STANDARD_SQL)
           .parse(Statement.of("RUN BATCH"));