feat!: add support for CommitStats

.kokoro/release/publish_javadoc.sh

@@ -62,7 +62,7 @@ popd
 # V2
 mvn clean site -B -q -Ddevsite.template="${KOKORO_GFILE_DIR}/java/"
 
-pushd target/devsite
+pushd target/devsite/reference
 
 # create metadata
 python3 -m docuploader create-metadata \

CODE_OF_CONDUCT.md

@@ -1,3 +1,4 @@
+<!-- # Generated by synthtool. DO NOT EDIT! !-->
 # Code of Conduct
 
 ## Our Pledge
@@ -69,12 +70,12 @@ dispute. If you are unable to resolve the matter for any reason, or if the
 behavior is threatening or harassing, report it. We are dedicated to providing
 an environment where participants feel welcome and safe.
 
-Reports should be directed to *[PROJECT STEWARD NAME(s) AND EMAIL(s)]*, the
-Project Steward(s) for *[PROJECT NAME]*. It is the Project Steward’s duty to
+Reports should be directed to *googleapis-stewards@google.com*, the
+Project Steward(s) for *Google Cloud Client Libraries*. It is the Project Steward’s duty to
 receive and address reported violations of the code of conduct. They will then
 work with a committee consisting of representatives from the Open Source
 Programs Office and the Google Open Source Strategy team. If for any reason you
-are uncomfortable reaching out the Project Steward, please email
+are uncomfortable reaching out to the Project Steward, please email
 opensource@google.com.
 
 We will investigate every complaint, but you may not receive a direct response.

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

@@ -406,4 +406,51 @@
     <className>com/google/cloud/spanner/AbstractLazyInitializer</className>
     <method>java.lang.Object initialize()</method>
   </difference>
+
+  <!-- Support for CommitStats added -->
+  <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>
+
 </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
@@ -80,7 +83,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);
     }
@@ -126,28 +129,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
@@ -184,6 +195,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,31 @@
 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());
+  }
+
+  /**
+   * 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 +53,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;
+  }
+}