Add detailed comment for allowNestedTransaction(), make test names cl…

…earer

google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/TransactionRunner.java

@@ -74,5 +74,22 @@ interface TransactionCallable<T> {
    */
   Timestamp getCommitTimestamp();
 
+  /**
+   * Allows overriding the default behaviour of blocking nested transactions.
+   *
+   * Note that the client library does not maintain any information regarding the nesting structure.
+   * If an outer transaction fails and an inner transaction succeeds, upon retry of the outer
+   * transaction, the inner transaction will be re-executed.
+   *
+   * Use with care when certain that the inner transaction is idempotent. Avoid doing this when
+   * accessing the same db. There might be legitimate uses where access need to be made across DBs
+   * for instance.
+   *
+   * E.g. of nesting that is discouraged, see {@code nestedReadWriteTxnThrows}
+   * {@code nestedReadOnlyTxnThrows}, {@code nestedBatchTxnThrows},
+   * {@code nestedSingleUseReadTxnThrows}
+   *
+   * @return this object
+   */
   TransactionRunner allowNestedTransaction();
 }

google-cloud-clients/google-cloud-spanner/src/test/java/com/google/cloud/spanner/it/ITTransactionTest.java

@@ -377,7 +377,7 @@ public Void run(TransactionContext transaction) throws Exception {
   }
 
   @Test
-  public void nestedRwRwTransactionShouldThrowException() {
+  public void nestedReadWriteTxnThrows() {
     try {
       doNestedRwTransaction();
       fail("Expected exception");
@@ -388,7 +388,7 @@ public void nestedRwRwTransactionShouldThrowException() {
   }
 
   @Test
-  public void nestedRwRdTransactionShouldThrowException() {
+  public void nestedReadOnlyTxnThrows() {
     try {
       client
           .readWriteTransaction()
@@ -411,7 +411,7 @@ public Void run(TransactionContext transaction) throws SpannerException {
   }
 
   @Test
-  public void nestedRwBatchTransactionShouldThrowException() {
+  public void nestedBatchTxnThrows() {
     try {
       client
           .readWriteTransaction()
@@ -440,7 +440,7 @@ public Void run(TransactionContext transaction) throws SpannerException {
   }
 
   @Test
-  public void nestedRwSingleUseReadTransactionShouldThrowException() {
+  public void nestedSingleUseReadTxnThrows() {
     try {
       client
           .readWriteTransaction()
@@ -461,7 +461,7 @@ public Void run(TransactionContext transaction) throws SpannerException {
   }
 
   @Test
-  public void nestedTxnShouldSucceedWhenAllowed() {
+  public void nestedTxnSucceedsWhenAllowed() {
     client
         .readWriteTransaction()
         .allowNestedTransaction()