feat!: add CommitStats to Connection API

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

@@ -406,4 +406,79 @@
     <className>com/google/cloud/spanner/AbstractLazyInitializer</className>
     <method>java.lang.Object initialize()</method>
   </difference>
+
+  <!-- Support for CommitStats added -->
+  <difference>
+    <differenceType>7005</differenceType>
+    <className>com/google/cloud/spanner/CommitResponse</className>
+    <method>CommitResponse(com.google.cloud.Timestamp)</method>
+    <to>CommitResponse(com.google.spanner.v1.CommitResponse)</to>
+  </difference>
+  <difference>
+    <differenceType>7009</differenceType>
+    <className>com/google/cloud/spanner/CommitResponse</className>
+    <method>CommitResponse(com.google.cloud.Timestamp)</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/AsyncTransactionManager</className>
+    <method>com.google.api.core.ApiFuture getCommitResponse()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/AsyncRunner</className>
+    <method>com.google.api.core.ApiFuture getCommitResponse()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/TransactionManager</className>
+    <method>com.google.cloud.spanner.CommitResponse getCommitResponse()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/TransactionRunner</className>
+    <method>com.google.cloud.spanner.CommitResponse getCommitResponse()</method>
+  </difference>
+  <difference>
+    <differenceType>7004</differenceType>
+    <className>com/google/cloud/spanner/DatabaseClient</className>
+    <method>com.google.cloud.spanner.TransactionRunner readWriteTransaction()</method>
+    <to>com.google.cloud.spanner.TransactionRunner readWriteTransaction(com.google.cloud.spanner.TransactionOption[])</to>
+  </difference>
+  <difference>
+    <differenceType>7004</differenceType>
+    <className>com/google/cloud/spanner/DatabaseClient</className>
+    <method>com.google.cloud.spanner.TransactionManager transactionManager()</method>
+    <to>com.google.cloud.spanner.TransactionManager transactionManager(com.google.cloud.spanner.TransactionOption[])</to>
+  </difference>
+  <difference>
+    <differenceType>7004</differenceType>
+    <className>com/google/cloud/spanner/DatabaseClient</className>
+    <method>com.google.cloud.spanner.AsyncRunner runAsync()</method>
+    <to>com.google.cloud.spanner.AsyncRunner runAsync(com.google.cloud.spanner.TransactionOption[])</to>
+  </difference>
+  <difference>
+    <differenceType>7004</differenceType>
+    <className>com/google/cloud/spanner/DatabaseClient</className>
+    <method>com.google.cloud.spanner.AsyncTransactionManager transactionManagerAsync()</method>
+    <to>com.google.cloud.spanner.AsyncTransactionManager transactionManagerAsync(com.google.cloud.spanner.TransactionOption[])</to>
+  </difference>
+
+  <!-- Support for Commit Stats in Connection API -->
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>com.google.cloud.spanner.CommitResponse getCommitResponse()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>boolean isReturnCommitStats()</method>
+  </difference>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/cloud/spanner/connection/Connection</className>
+    <method>void setReturnCommitStats(boolean)</method>
+  </difference>
+
 </differences>

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

@@ -52,8 +52,14 @@ interface AsyncWork<R> {
   <R> ApiFuture<R> runAsync(AsyncWork<R> work, Executor executor);
 
   /**
-   * Returns the timestamp at which the transaction committed. {@link ApiFuture#get()} will throw an
-   * {@link ExecutionException} if the transaction did not commit.
+   * Returns the timestamp at which the transaction committed. The {@link ApiFuture#get()} will
+   * throw an {@link ExecutionException} if the transaction did not commit.
    */
   ApiFuture<Timestamp> getCommitTimestamp();
+
+  /**
+   * Returns the {@link CommitResponse} of this transaction. The {@link ApiFuture#get()} will throw
+   * an {@link ExecutionException} if the transaction did not commit.
+   */
+  ApiFuture<CommitResponse> getCommitResponse();
 }

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

@@ -16,19 +16,23 @@
 
 package com.google.cloud.spanner;
 
+import com.google.api.core.ApiFunction;
 import com.google.api.core.ApiFuture;
+import com.google.api.core.ApiFutures;
 import com.google.api.core.SettableApiFuture;
 import com.google.cloud.Timestamp;
 import com.google.cloud.spanner.TransactionRunner.TransactionCallable;
+import com.google.common.base.Preconditions;
+import com.google.common.util.concurrent.MoreExecutors;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.Executor;
 
 class AsyncRunnerImpl implements AsyncRunner {
   private final TransactionRunnerImpl delegate;
-  private final SettableApiFuture<Timestamp> commitTimestamp = SettableApiFuture.create();
+  private final SettableApiFuture<CommitResponse> commitResponse = SettableApiFuture.create();
 
   AsyncRunnerImpl(TransactionRunnerImpl delegate) {
-    this.delegate = delegate;
+    this.delegate = Preconditions.checkNotNull(delegate);
   }
 
   @Override
@@ -43,7 +47,7 @@ public void run() {
             } catch (Throwable t) {
               res.setException(t);
             } finally {
-              setCommitTimestamp();
+              setCommitResponse();
             }
           }
         });
@@ -66,16 +70,28 @@ public R run(TransactionContext transaction) throws Exception {
         });
   }
 
-  private void setCommitTimestamp() {
+  private void setCommitResponse() {
     try {
-      commitTimestamp.set(delegate.getCommitTimestamp());
+      commitResponse.set(delegate.getCommitResponse());
     } catch (Throwable t) {
-      commitTimestamp.setException(t);
+      commitResponse.setException(t);
     }
   }
 
   @Override
   public ApiFuture<Timestamp> getCommitTimestamp() {
-    return commitTimestamp;
+    return ApiFutures.transform(
+        commitResponse,
+        new ApiFunction<CommitResponse, Timestamp>() {
+          @Override
+          public Timestamp apply(CommitResponse input) {
+            return input.getCommitTimestamp();
+          }
+        },
+        MoreExecutors.directExecutor());
+  }
+
+  public ApiFuture<CommitResponse> getCommitResponse() {
+    return commitResponse;
   }
 }

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

@@ -191,6 +191,9 @@ public interface AsyncTransactionFunction<I, O> {
   /** Returns the state of the transaction. */
   TransactionState getState();
 
+  /** Returns the {@link CommitResponse} of this transaction. */
+  ApiFuture<CommitResponse> getCommitResponse();
+
   /**
    * Closes the manager. If there is an active transaction, it will be rolled back. Underlying
    * session will be released back to the session pool.

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

@@ -17,6 +17,7 @@
 package com.google.cloud.spanner;
 
 import com.google.api.core.ApiAsyncFunction;
+import com.google.api.core.ApiFunction;
 import com.google.api.core.ApiFuture;
 import com.google.api.core.ApiFutureCallback;
 import com.google.api.core.ApiFutures;
@@ -40,14 +41,16 @@ final class AsyncTransactionManagerImpl
 
   private final SessionImpl session;
   private Span span;
+  private final Options options;
 
   private TransactionRunnerImpl.TransactionContextImpl txn;
   private TransactionState txnState;
-  private final SettableApiFuture<Timestamp> commitTimestamp = SettableApiFuture.create();
+  private final SettableApiFuture<CommitResponse> commitResponse = SettableApiFuture.create();
 
-  AsyncTransactionManagerImpl(SessionImpl session, Span span) {
+  AsyncTransactionManagerImpl(SessionImpl session, Span span, Options options) {
     this.session = session;
     this.span = span;
+    this.options = options;
   }
 
   @Override
@@ -82,7 +85,7 @@ public TransactionContextFutureImpl beginAsync() {
 
   private ApiFuture<TransactionContext> internalBeginAsync(boolean firstAttempt) {
     txnState = TransactionState.STARTED;
-    txn = session.newTransaction();
+    txn = session.newTransaction(options);
     if (firstAttempt) {
       session.setActive(this);
     }
@@ -128,28 +131,36 @@ public ApiFuture<Timestamp> commitAsync() {
           SpannerExceptionFactory.newSpannerException(
               ErrorCode.ABORTED, "Transaction already aborted"));
     }
-    ApiFuture<Timestamp> res = txn.commitAsync();
+    ApiFuture<CommitResponse> res = txn.commitAsync();
     txnState = TransactionState.COMMITTED;
     ApiFutures.addCallback(
         res,
-        new ApiFutureCallback<Timestamp>() {
+        new ApiFutureCallback<CommitResponse>() {
           @Override
           public void onFailure(Throwable t) {
             if (t instanceof AbortedException) {
               txnState = TransactionState.ABORTED;
             } else {
               txnState = TransactionState.COMMIT_FAILED;
-              commitTimestamp.setException(t);
+              commitResponse.setException(t);
             }
           }
 
           @Override
-          public void onSuccess(Timestamp result) {
-            commitTimestamp.set(result);
+          public void onSuccess(CommitResponse result) {
+            commitResponse.set(result);
+          }
+        },
+        MoreExecutors.directExecutor());
+    return ApiFutures.transform(
+        res,
+        new ApiFunction<CommitResponse, Timestamp>() {
+          @Override
+          public Timestamp apply(CommitResponse input) {
+            return input.getCommitTimestamp();
           }
         },
         MoreExecutors.directExecutor());
-    return res;
   }
 
   @Override
@@ -186,6 +197,11 @@ public TransactionState getState() {
     return txnState;
   }
 
+  @Override
+  public ApiFuture<CommitResponse> getCommitResponse() {
+    return commitResponse;
+  }
+
   @Override
   public void invalidate() {
     if (txnState == TransactionState.STARTED || txnState == null) {

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

@@ -17,20 +17,36 @@
 package com.google.cloud.spanner;
 
 import com.google.cloud.Timestamp;
+import com.google.common.base.Preconditions;
 import java.util.Objects;
 
 /** Represents a response from a commit operation. */
 public class CommitResponse {
 
-  private final Timestamp commitTimestamp;
+  private final com.google.spanner.v1.CommitResponse proto;
 
-  public CommitResponse(Timestamp commitTimestamp) {
-    this.commitTimestamp = commitTimestamp;
+  CommitResponse(com.google.spanner.v1.CommitResponse proto) {
+    this.proto = proto;
   }
 
-  /** Returns a {@link Timestamp} representing the commit time of the write operation. */
+  /** Returns a {@link Timestamp} representing the commit time of the transaction. */
   public Timestamp getCommitTimestamp() {
-    return commitTimestamp;
+    return Timestamp.fromProto(proto.getCommitTimestamp());
+  }
+
+  /** @return true if the {@link CommitResponse} includes {@link CommitStats}. */
+  public boolean hasCommitStats() {
+    return proto.hasCommitStats();
+  }
+
+  /**
+   * Commit statistics are returned by a read/write transaction if specifically requested by passing
+   * in {@link Options#commitStats()} to the transaction.
+   */
+  public CommitStats getCommitStats() {
+    Preconditions.checkState(
+        proto.hasCommitStats(), "The CommitResponse does not contain any commit statistics.");
+    return CommitStats.fromProto(proto.getCommitStats());
   }
 
   @Override
@@ -42,11 +58,11 @@ public boolean equals(Object o) {
       return false;
     }
     CommitResponse that = (CommitResponse) o;
-    return Objects.equals(commitTimestamp, that.commitTimestamp);
+    return Objects.equals(proto, that.proto);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(commitTimestamp);
+    return Objects.hash(proto);
   }
 }

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

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2020 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.common.base.Preconditions;
+import org.threeten.bp.Duration;
+import org.threeten.bp.temporal.ChronoUnit;
+
+/**
+ * Commit statistics are returned by a read/write transaction if specifically requested by passing
+ * in {@link Options#commitStats()} to the transaction.
+ */
+public class CommitStats {
+  private final long mutationCount;
+  private final Duration overloadDelay;
+
+  private CommitStats(long mutationCount, Duration overloadDelay) {
+    this.mutationCount = mutationCount;
+    this.overloadDelay = overloadDelay;
+  }
+
+  static CommitStats fromProto(com.google.spanner.v1.CommitResponse.CommitStats proto) {
+    Preconditions.checkNotNull(proto);
+    return new CommitStats(
+        proto.getMutationCount(),
+        Duration.of(proto.getOverloadDelay().getSeconds(), ChronoUnit.SECONDS)
+            .plusNanos(proto.getOverloadDelay().getNanos()));
+  }
+
+  /**
+   * The number of mutations that were executed by the transaction. Insert and update operations
+   * count with the multiplicity of the number of columns they affect. For example, inserting a new
+   * record may count as five mutations, if values are inserted into five columns. Delete and delete
+   * range operations count as one mutation regardless of the number of columns affected. Deleting a
+   * row from a parent table that has the ON DELETE CASCADE annotation is also counted as one
+   * mutation regardless of the number of interleaved child rows present. The exception to this is
+   * if there are secondary indexes defined on rows being deleted, then the changes to the secondary
+   * indexes will be counted individually. For example, if a table has 2 secondary indexes, deleting
+   * a range of rows in the table will count as 1 mutation for the table, plus 2 mutations for each
+   * row that is deleted because the rows in the secondary index might be scattered over the
+   * key-space, making it impossible for Cloud Spanner to call a single delete range operation on
+   * the secondary indexes. Secondary indexes include the foreign keys backing indexes.
+   */
+  public long getMutationCount() {
+    return mutationCount;
+  }
+
+  /** The duration that the commit was delayed due to overloaded servers. */
+  public Duration getOverloadDelay() {
+    return overloadDelay;
+  }
+}