[Firestore] Snippets for document snapshots and paginated queries. (GoogleCloudPlatform#1243)

kurtisvg · web-flow · commit fd030d19605b · 2018-11-02T15:35:35.000-07:00
* Add firestore document snapshot and paginate cursor snippets.

* Add test annotation.

* Fix SnapshotQueryCursor test.

* Correct Checkstyle violations.

* Add comment clarifing futures wait time.

* Update pagination test to check queries.

* Fixed test order.
diff --git a/firestore/pom.xml b/firestore/pom.xml
@@ -32,7 +32,7 @@
   <parent>
     <groupId>com.google.cloud.samples</groupId>
     <artifactId>shared-configuration</artifactId>
-    <version>1.0.9</version>
+    <version>1.0.10</version>
   </parent>
   <properties>
     <maven.compiler.target>1.8</maven.compiler.target>
@@ -45,7 +45,7 @@
     <dependency>
       <groupId>com.google.cloud</groupId>
       <artifactId>google-cloud-firestore</artifactId>
-      <version>0.60.0-beta</version>
+      <version>0.68.0-beta</version>
     </dependency>
     <!-- [END fs-maven] -->
 
diff --git a/firestore/src/main/java/com/example/firestore/snippets/QueryDataSnippets.java b/firestore/src/main/java/com/example/firestore/snippets/QueryDataSnippets.java
@@ -21,16 +21,23 @@
 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.WriteResult;
 
+import com.google.firestore.v1beta1.Document;
+import com.google.protobuf.Api;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 
 /** Snippets to support firestore querying data documentation. */
 class QueryDataSnippets {
@@ -328,4 +335,52 @@ void createMultipleCursorConditionsQuery() {
         .startAt("Springfield", "Missouri");
     // [END fs_multiple_cursor_conditions]
   }
+
+  /**
+   * Create a query using a snapshot as a start point.
+   *
+   * @return query
+   */
+  Query createStartAtSnapshotQueryCursor()
+      throws InterruptedException, ExecutionException, TimeoutException {
+    // [START fs_document_snapshot_cursor]
+    // Fetch the snapshot with an API call, waiting for a maximum of 30 seconds for a result.
+    ApiFuture<DocumentSnapshot> future = db.collection("cities").document("SF").get();
+    DocumentSnapshot snapshot = future.get(30, TimeUnit.SECONDS);
+
+    // Construct the query
+    Query query = db.collection("cities")
+        .orderBy("population")
+        .startAt(snapshot);
+    // [END fs_document_snapshot_cursor]
+    return query;
+  }
+
+  /**
+   * Example of a paginated query.
+   */
+  List<Query> paginateCursor() throws InterruptedException, ExecutionException, TimeoutException {
+    // [START fs_paginate_cursor]
+    // Construct query for first 25 cities, ordered by population.
+    CollectionReference cities = db.collection("cities");
+    Query firstPage = cities
+        .orderBy("population")
+        .limit(25);
+
+    // Wait for the results of the API call, waiting for a maximum of 30 seconds for a result.
+    ApiFuture<QuerySnapshot> future = firstPage.get();
+    List<QueryDocumentSnapshot> docs = future.get(30, TimeUnit.SECONDS).getDocuments();
+
+    // Construct query for the next 25 cities.
+    QueryDocumentSnapshot lastDoc = docs.get(docs.size() - 1);
+    Query secondPage = cities
+        .orderBy("population")
+        .startAfter(lastDoc)
+        .limit(25);
+
+    future = secondPage.get();
+    docs = future.get(30, TimeUnit.SECONDS).getDocuments();
+    // [END fs_paginate_cursor]
+    return Arrays.asList(firstPage, secondPage);
+  }
 }
diff --git a/firestore/src/test/java/com/example/firestore/snippets/QueryDataSnippetsIT.java b/firestore/src/test/java/com/example/firestore/snippets/QueryDataSnippetsIT.java
@@ -197,6 +197,24 @@ public void testMultipleCursorConditions() throws Exception {
     assertTrue(Objects.equals(result, expectedResults));
   }
 
+  @Test
+  public void testCreateStartAtSnapshotQueryCursor() throws Exception {
+    Query q = queryDataSnippets.createStartAtSnapshotQueryCursor();
+    List<String> results = getResults(q);
+    List<String> expectedResults = Arrays.asList("SF", "LA", "TOK", "BJ");
+    assertEquals(expectedResults, results);
+  }
+
+  @Test
+  public void testPaginateCursor() throws Exception {
+    // Snippet executes it's own query. Failures result in thrown Exceptions
+    List<Query> pages = queryDataSnippets.paginateCursor();
+    List<String> firstPage = getResults(pages.get(0));
+    List<String> secondPage = getResults(pages.get(1));
+    assertEquals(Arrays.asList("DC", "SF", "LA", "TOK", "BJ"), firstPage);
+    assertEquals(new ArrayList<String>(), secondPage);
+  }
+
   private Set<String> getResultsAsSet(Query query) throws Exception {
     List<String> docIds = getResults(query);
     return new HashSet<>(docIds);
