samples: Add example snippets for stale reads

samples/snippets/src/main/java/com/example/firestore/snippets/QueryDataSnippets.java

@@ -20,13 +20,17 @@
 import com.google.api.core.ApiFuture;
 import com.google.api.core.ApiFutures;
 import com.google.cloud.firestore.CollectionReference;
+import com.google.cloud.firestore.DocumentReference;
 import com.google.cloud.firestore.DocumentSnapshot;
 import com.google.cloud.firestore.Firestore;
 import com.google.cloud.firestore.Query;
 import com.google.cloud.firestore.Query.Direction;
 import com.google.cloud.firestore.QueryDocumentSnapshot;
 import com.google.cloud.firestore.QuerySnapshot;
+import com.google.cloud.firestore.TransactionOptions;
 import com.google.cloud.firestore.WriteResult;
+import com.google.protobuf.Timestamp;
+import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashMap;
@@ -35,7 +39,9 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
-/** Snippets to support firestore querying data documentation. */
+/**
+ * Snippets to support firestore querying data documentation.
+ */
 class QueryDataSnippets {
 
   private final Firestore db;
@@ -390,7 +396,9 @@ Query createStartAtSnapshotQueryCursor()
     return query;
   }
 
-  /** Example of a paginated query. */
+  /**
+   * Example of a paginated query.
+   */
   List<Query> paginateCursor() throws InterruptedException, ExecutionException, TimeoutException {
     // [START firestore_query_cursor_pagination]
     // Construct query for first 25 cities, ordered by population.
@@ -591,7 +599,52 @@ Query filterNotIn() {
     return query;
   }
 
-  /** Closes the gRPC channels associated with this instance and frees up their resources. */
+  /**
+   * Run stale reads. Demonstrate a document lookup and a query.
+   *
+   * @return transaction future
+   */
+  DocumentSnapshot runStaleReads() throws Exception {
+    // [START firestore_stale_read]
+    // Create a read time 15 seconds in the past
+    Instant now = Instant.now();
+    final int fifteenSeconds = 15;
+    final Timestamp readTime = Timestamp.newBuilder()
+        .setSeconds(now.getEpochSecond() - fifteenSeconds)
+        .setNanos(now.getNano()).build();
+
+    // Set transaction options. Use read-only and set read time
+    // Stale reads require a read-only transaction
+    TransactionOptions options = TransactionOptions
+        .createReadOnlyOptionsBuilder()
+        .setReadTime(readTime).build();
+
+    // Create a document reference
+    final DocumentReference documentReference = db
+        .collection("cities")
+        .document("SF");
+    // Create a query against the cities collection.
+    Query query = db.collection("cities").whereEqualTo("capital", true);
+
+    // run a transaction with the specified transaction options
+    ApiFuture<DocumentSnapshot> futureTransaction = db
+        .runTransaction(transaction -> {
+          // Execute a stale read document lookup
+          final DocumentSnapshot documentResult = transaction
+              .get(documentReference).get();
+
+          // Execute a stale read query
+          final QuerySnapshot queryResult = transaction.get(query).get();
+
+          return documentResult;
+        }, options);
+    // [END firestore_stale_read]
+    return futureTransaction.get();
+  }
+
+  /**
+   * Closes the gRPC channels associated with this instance and frees up their resources.
+   */
   void close() throws Exception {
     db.close();
   }

samples/snippets/src/test/java/com/example/firestore/snippets/QueryDataSnippetsIT.java

@@ -271,6 +271,12 @@ public void testFilterNotIn() throws Exception {
     assertEquals(expected, actual);
   }
 
+  @Test
+  public void testSnapshotReads() throws Exception {
+    // Verify that this runs without error
+    DocumentSnapshot doc = queryDataSnippets.runStaleReads();
+  }
+
   private Set<String> getResultsAsSet(Query query) throws Exception {
     List<String> docIds = getResults(query);
     return new HashSet<>(docIds);