From 78ff5f2fd8111d485c404cb62b45ac98effc5200 Mon Sep 17 00:00:00 2001
From: Olav Loite <koloite@gmail.com>
Date: Fri, 22 Mar 2019 09:51:59 +0100
Subject: [PATCH 1/2] added extra documentation to the singleUse methods #4212

---
 .../google/cloud/spanner/DatabaseClient.java  | 45 +++++++++++--------
 1 file changed, 27 insertions(+), 18 deletions(-)

diff --git a/google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java b/google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
index cf2eabec9e3c..ef6ffc9330e6 100644
--- a/google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
+++ b/google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
@@ -85,34 +85,43 @@ public interface DatabaseClient {
 
   /**
    * Returns a context in which a single read can be performed using {@link TimestampBound#strong()}
-   * concurrency.
+   * concurrency. This method will return a {@link ReadContext} that will not return the read
+   * timestamp that was used by Cloud Spanner. If you want to be able to access the read timestamp,
+   * you should use the method {@link #singleUseReadOnlyTransaction()}.
    *
    * <p>Example of single use.
    *
-   * <pre>{@code
-   * long singerId = my_singer_id;
-   * String column = "FirstName";
-   * Struct row =
-   *     dbClient.singleUse().readRow("Singers", Key.of(singerId), Collections.singleton(column));
-   * String firstName = row.getString(column);
-   * }</pre>
+   * <pre>
+   * {
+   *   &#64;code
+   *   long singerId = my_singer_id;
+   *   String column = "FirstName";
+   *   Struct row =
+   *       dbClient.singleUse().readRow("Singers", Key.of(singerId), Collections.singleton(column));
+   *   String firstName = row.getString(column);
+   * }
+   * </pre>
    */
   ReadContext singleUse();
 
   /**
-   * Returns a context in which a single read can be performed at the given timestamp bound.
+   * Returns a context in which a single read can be performed at the given timestamp bound. This
+   * method will return a {@link ReadContext} that will not return the read timestamp that was used
+   * by Cloud Spanner. If you want to be able to access the read timestamp, you should use the
+   * method {@link #singleUseReadOnlyTransaction()}.
    *
    * <p>Example of single use with timestamp bound.
    *
-   * <pre>{@code
-   * long singerId = my_singer_id;
-   * String column = "FirstName";
-   * Struct row =
-   *     dbClient
-   *         .singleUse(TimestampBound.ofMaxStaleness(10, TimeUnit.SECONDS))
-   *         .readRow("Singers", Key.of(singerId), Collections.singleton(column));
-   * String firstName = row.getString(column);
-   * }</pre>
+   * <pre>
+   * {
+   *   &#64;code
+   *   long singerId = my_singer_id;
+   *   String column = "FirstName";
+   *   Struct row = dbClient.singleUse(TimestampBound.ofMaxStaleness(10, TimeUnit.SECONDS))
+   *       .readRow("Singers", Key.of(singerId), Collections.singleton(column));
+   *   String firstName = row.getString(column);
+   * }
+   * </pre>
    *
    * @param bound the timestamp bound at which to perform the read
    */

From 2e985171041632f92dafa3821588880399a359e9 Mon Sep 17 00:00:00 2001
From: Olav Loite <koloite@gmail.com>
Date: Sat, 23 Mar 2019 08:53:48 +0100
Subject: [PATCH 2/2] changed formatting manually and re-run mvn formatter

---
 .../google/cloud/spanner/DatabaseClient.java  | 34 ++++++++-----------
 1 file changed, 14 insertions(+), 20 deletions(-)

diff --git a/google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java b/google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
index ef6ffc9330e6..ac29ba2b374a 100644
--- a/google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
+++ b/google-cloud-clients/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java
@@ -91,16 +91,13 @@ public interface DatabaseClient {
    *
    * <p>Example of single use.
    *
-   * <pre>
-   * {
-   *   &#64;code
-   *   long singerId = my_singer_id;
-   *   String column = "FirstName";
-   *   Struct row =
-   *       dbClient.singleUse().readRow("Singers", Key.of(singerId), Collections.singleton(column));
-   *   String firstName = row.getString(column);
-   * }
-   * </pre>
+   * <pre>{@code
+   * long singerId = my_singer_id;
+   * String column = "FirstName";
+   * Struct row =
+   *     dbClient.singleUse().readRow("Singers", Key.of(singerId), Collections.singleton(column));
+   * String firstName = row.getString(column);
+   * }</pre>
    */
   ReadContext singleUse();
 
@@ -112,16 +109,13 @@ public interface DatabaseClient {
    *
    * <p>Example of single use with timestamp bound.
    *
-   * <pre>
-   * {
-   *   &#64;code
-   *   long singerId = my_singer_id;
-   *   String column = "FirstName";
-   *   Struct row = dbClient.singleUse(TimestampBound.ofMaxStaleness(10, TimeUnit.SECONDS))
-   *       .readRow("Singers", Key.of(singerId), Collections.singleton(column));
-   *   String firstName = row.getString(column);
-   * }
-   * </pre>
+   * <pre>{@code
+   * long singerId = my_singer_id;
+   * String column = "FirstName";
+   * Struct row = dbClient.singleUse(TimestampBound.ofMaxStaleness(10, TimeUnit.SECONDS))
+   *     .readRow("Singers", Key.of(singerId), Collections.singleton(column));
+   * String firstName = row.getString(column);
+   * }</pre>
    *
    * @param bound the timestamp bound at which to perform the read
    */