Fixups

Author: tom-andersen

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/testutil/IntegrationTestUtil.java

@@ -568,7 +568,8 @@ public static void checkOnlineAndOfflineResultsMatch(Query query, String... expe
    */
   public static void checkQueryAndPipelineResultsMatch(Query query, String... expectedDocs) {
     QuerySnapshot docsFromQuery = waitFor(query.get(Source.SERVER));
-    PipelineSnapshot docsFromPipeline = waitFor(query.pipeline().execute());
+    PipelineSnapshot docsFromPipeline =
+        waitFor(query.getFirestore().pipeline().createFrom(query).execute());
 
     assertEquals(querySnapshotToIds(docsFromQuery), pipelineSnapshotToIds(docsFromPipeline));
     List<String> expected = asList(expectedDocs);

firebase-firestore/src/main/java/com/google/firebase/firestore/FirebaseFirestore.java

@@ -884,6 +884,11 @@ static void setClientLanguage(@NonNull String languageToken) {
     FirestoreChannel.setClientLanguage(languageToken);
   }
 
+  /**
+   * Build a new Pipeline
+   *
+   * @return {@code PipelineSource} for this Firestore instance.
+   */
   @NonNull
   public PipelineSource pipeline() {
     clientProvider.ensureConfigured();

firebase-firestore/src/main/java/com/google/firebase/firestore/Pipeline.kt

@@ -18,8 +18,8 @@ import com.google.android.gms.tasks.Task
 import com.google.android.gms.tasks.TaskCompletionSource
 import com.google.common.collect.FluentIterable
 import com.google.common.collect.ImmutableList
+import com.google.firebase.Timestamp
 import com.google.firebase.firestore.model.DocumentKey
-import com.google.firebase.firestore.model.SnapshotVersion
 import com.google.firebase.firestore.model.Values
 import com.google.firebase.firestore.pipeline.AddFieldsStage
 import com.google.firebase.firestore.pipeline.AggregateStage
@@ -32,7 +32,6 @@ import com.google.firebase.firestore.pipeline.DistinctStage
 import com.google.firebase.firestore.pipeline.DocumentsSource
 import com.google.firebase.firestore.pipeline.Expr
 import com.google.firebase.firestore.pipeline.Field
-import com.google.firebase.firestore.pipeline.FindNearestOptions
 import com.google.firebase.firestore.pipeline.FindNearestStage
 import com.google.firebase.firestore.pipeline.GenericArg
 import com.google.firebase.firestore.pipeline.GenericStage
@@ -47,7 +46,6 @@ import com.google.firebase.firestore.pipeline.Selectable
 import com.google.firebase.firestore.pipeline.SortStage
 import com.google.firebase.firestore.pipeline.Stage
 import com.google.firebase.firestore.pipeline.UnionStage
-import com.google.firebase.firestore.pipeline.UnnestOptions
 import com.google.firebase.firestore.pipeline.UnnestStage
 import com.google.firebase.firestore.pipeline.WhereStage
 import com.google.firebase.firestore.util.Preconditions
@@ -59,15 +57,15 @@ class Pipeline
 internal constructor(
   internal val firestore: FirebaseFirestore,
   internal val userDataReader: UserDataReader,
-  private val stages: FluentIterable<Stage>
+  private val stages: FluentIterable<Stage<*>>
 ) {
   internal constructor(
     firestore: FirebaseFirestore,
     userDataReader: UserDataReader,
-    stage: Stage
+    stage: Stage<*>
   ) : this(firestore, userDataReader, FluentIterable.of(stage))
 
-  private fun append(stage: Stage): Pipeline {
+  private fun append(stage: Stage<*>): Pipeline {
     return Pipeline(firestore, userDataReader, stages.append(stage))
   }
 
@@ -144,15 +142,28 @@ internal constructor(
   fun findNearest(
     property: Expr,
     vector: DoubleArray,
-    distanceMeasure: FindNearestStage.DistanceMeasure
-  ) = append(FindNearestStage(property, vector, distanceMeasure, FindNearestOptions.DEFAULT))
+    distanceMeasure: FindNearestStage.DistanceMeasure,
+  ) = append(FindNearestStage.of(property, vector, distanceMeasure))
 
   fun findNearest(
-    property: Expr,
+    propertyField: String,
     vector: DoubleArray,
     distanceMeasure: FindNearestStage.DistanceMeasure,
-    options: FindNearestOptions
-  ) = append(FindNearestStage(property, vector, distanceMeasure, options))
+  ) = append(FindNearestStage.of(propertyField, vector, distanceMeasure))
+
+  fun findNearest(
+    property: Expr,
+    vector: Expr,
+    distanceMeasure: FindNearestStage.DistanceMeasure,
+  ) = append(FindNearestStage.of(property, vector, distanceMeasure))
+
+  fun findNearest(
+    propertyField: String,
+    vector: Expr,
+    distanceMeasure: FindNearestStage.DistanceMeasure,
+  ) = append(FindNearestStage.of(propertyField, vector, distanceMeasure))
+
+  fun findNearest(stage: FindNearestStage) = append(stage)
 
   fun replace(field: String): Pipeline = replace(Field.of(field))
 
@@ -165,34 +176,36 @@ internal constructor(
 
   fun union(other: Pipeline): Pipeline = append(UnionStage(other))
 
-  fun unnest(field: String, alias: String): Pipeline = unnest(Field.of(field).alias(alias))
-
-  fun unnest(field: String, alias: String, options: UnnestOptions): Pipeline =
-    unnest(Field.of(field).alias(alias), options)
+  fun unnest(field: String, alias: String): Pipeline = unnest(UnnestStage.withField(field, alias))
 
   fun unnest(selectable: Selectable): Pipeline = append(UnnestStage(selectable))
 
-  fun unnest(selectable: Selectable, options: UnnestOptions): Pipeline =
-    append(UnnestStage(selectable))
+  fun unnest(stage: UnnestStage): Pipeline = append(stage)
 
   private inner class ObserverSnapshotTask : PipelineResultObserver {
     private val userDataWriter =
       UserDataWriter(firestore, DocumentSnapshot.ServerTimestampBehavior.DEFAULT)
     private val taskCompletionSource = TaskCompletionSource<PipelineSnapshot>()
     private val results: ImmutableList.Builder<PipelineResult> = ImmutableList.builder()
-    override fun onDocument(key: DocumentKey?, data: Map<String, Value>, version: SnapshotVersion) {
+    override fun onDocument(
+      key: DocumentKey?,
+      data: Map<String, Value>,
+      createTime: Timestamp?,
+      updateTime: Timestamp?
+    ) {
       results.add(
         PipelineResult(
           firestore,
           userDataWriter,
           if (key == null) null else DocumentReference(key, firestore),
           data,
-          version
+          createTime,
+          updateTime
         )
       )
     }
 
-    override fun onComplete(executionTime: SnapshotVersion) {
+    override fun onComplete(executionTime: Timestamp) {
       taskCompletionSource.setResult(PipelineSnapshot(executionTime, results.build()))
     }
 
@@ -205,24 +218,58 @@ internal constructor(
   }
 }
 
+/** Start of a Firestore Pipeline */
 class PipelineSource internal constructor(private val firestore: FirebaseFirestore) {
+
+  /**
+   * Convert the given Query into an equivalent Pipeline.
+   *
+   * @param query A Query to be converted into a Pipeline.
+   * @return Pipeline that is equivalent to [query]
+   * @throws [IllegalArgumentException] Thrown if the [query] provided targets a different project
+   * or database than the pipeline.
+   */
   fun createFrom(query: Query): Pipeline {
     if (query.firestore.databaseId != firestore.databaseId) {
       throw IllegalArgumentException("Provided query is from a different Firestore instance.")
     }
     return query.query.toPipeline(firestore, firestore.userDataReader)
   }
 
-  fun createFrom(query: AggregateQuery): Pipeline =
-    createFrom(query.query)
+  /**
+   * Convert the given Aggregate Query into an equivalent Pipeline.
+   *
+   * @param aggregateQuery An Aggregate Query to be converted into a Pipeline.
+   * @return Pipeline that is equivalent to [aggregateQuery]
+   * @throws [IllegalArgumentException] Thrown if the [aggregateQuery] provided targets a different
+   * project or database than the pipeline.
+   */
+  fun createFrom(aggregateQuery: AggregateQuery): Pipeline =
+    createFrom(aggregateQuery.query)
       .aggregate(
-        *query.aggregateFields.map(AggregateField::toPipeline).toTypedArray<AggregateWithAlias>()
+        *aggregateQuery.aggregateFields
+          .map(AggregateField::toPipeline)
+          .toTypedArray<AggregateWithAlias>()
       )
 
+  /**
+   * Set the pipeline's source to the collection specified by the given path.
+   *
+   * @param path A path to a collection that will be the source of this pipeline.
+   * @return Pipeline with documents from target collection.
+   */
   fun collection(path: String): Pipeline =
     // Validate path by converting to CollectionReference
     collection(firestore.collection(path))
 
+  /**
+   * Set the pipeline's source to the collection specified by the given CollectionReference.
+   *
+   * @param ref A CollectionReference for a collection that will be the source of this pipeline.
+   * @return Pipeline with documents from target collection.
+   * @throws [IllegalArgumentException] Thrown if the [ref] provided targets a different project or
+   * database than the pipeline.
+   */
   fun collection(ref: CollectionReference): Pipeline {
     if (ref.firestore.databaseId != firestore.databaseId) {
       throw IllegalArgumentException(
@@ -232,6 +279,11 @@ class PipelineSource internal constructor(private val firestore: FirebaseFiresto
     return Pipeline(firestore, firestore.userDataReader, CollectionSource(ref.path))
   }
 
+  /**
+   * Set the pipeline's source to the collection group with the given id.
+   *
+   * @param collectionid The id of a collection group that will be the source of this pipeline.
+   */
   fun collectionGroup(collectionId: String): Pipeline {
     Preconditions.checkNotNull(collectionId, "Provided collection ID must not be null.")
     require(!collectionId.contains("/")) {
@@ -240,12 +292,33 @@ class PipelineSource internal constructor(private val firestore: FirebaseFiresto
     return Pipeline(firestore, firestore.userDataReader, CollectionGroupSource(collectionId))
   }
 
+  /**
+   * Set the pipeline's source to be all documents in this database.
+   *
+   * @return Pipeline with all documents in this database.
+   */
   fun database(): Pipeline = Pipeline(firestore, firestore.userDataReader, DatabaseSource())
 
+  /**
+   * Set the pipeline's source to the documents specified by the given paths.
+   *
+   * @param documents Paths specifying the individual documents that will be the source of this
+   * pipeline.
+   * @return Pipeline with [documents].
+   */
   fun documents(vararg documents: String): Pipeline =
     // Validate document path by converting to DocumentReference
     documents(*documents.map(firestore::document).toTypedArray())
 
+  /**
+   * Set the pipeline's source to the documents specified by the given DocumentReferences.
+   *
+   * @param documents DocumentReferences specifying the individual documents that will be the source
+   * of this pipeline.
+   * @return Pipeline with [documents].
+   * @throws [IllegalArgumentException] Thrown if the [documents] provided targets a different
+   * project or database than the pipeline.
+   */
   fun documents(vararg documents: DocumentReference): Pipeline {
     val databaseId = firestore.databaseId
     for (document in documents) {
@@ -263,29 +336,70 @@ class PipelineSource internal constructor(private val firestore: FirebaseFiresto
   }
 }
 
+/**
+ */
 class PipelineSnapshot
-internal constructor(
-  private val executionTime: SnapshotVersion,
-  val results: List<PipelineResult>
-) : Iterable<PipelineResult> {
+internal constructor(executionTime: Timestamp, results: List<PipelineResult>) :
+  Iterable<PipelineResult> {
+
+  /** The time at which the pipeline producing this result is executed. */
+  val executionTime: Timestamp = executionTime
+
+  /** List of all the results */
+  val results: List<PipelineResult> = results
+
   override fun iterator() = results.iterator()
 }
 
 class PipelineResult
 internal constructor(
   private val firestore: FirebaseFirestore,
   private val userDataWriter: UserDataWriter,
-  val ref: DocumentReference?,
+  ref: DocumentReference?,
   private val fields: Map<String, Value>,
-  private val version: SnapshotVersion,
+  createTime: Timestamp?,
+  updateTime: Timestamp?,
 ) {
 
+  /** The time the document was created. Null if this result is not a document. */
+  val createTime: Timestamp? = createTime
+
+  /**
+   * The time the document was last updated (at the time the snapshot was generated). Null if this
+   * result is not a document.
+   */
+  val updateTime: Timestamp? = updateTime
+
+  /**
+   * The reference to the document, if the query returns the `__name__` field for a document. The
+   * name field will be returned by default if querying a document.
+   *
+   * The `__name__` field will not be returned if the query projects away this field. For example:
+   * ```
+   *   // this query does not select the `__name__` field as part of the select stage,
+   *   // so the __name__ field will not be in the output docs from this stage
+   *   db.pipeline().collection("books").select("title", "desc")
+   * ```
+   *
+   * The `__name__` field will not be returned from queries with aggregate or distinct stages.
+   *
+   * @return [DocumentReference] Reference to the document, if applicable.
+   */
+  val ref: DocumentReference? = ref
+
   /**
    * Returns the ID of the document represented by this result. Returns null if this result is not
    * corresponding to a Firestore document.
+   *
+   * @return ID of document, if applicable.
    */
   fun getId(): String? = ref?.id
 
+  /**
+   * Retrieves all fields in the result as an object map.
+   *
+   * @return Map of field names to objects.
+   */
   fun getData(): Map<String, Any?> = userDataWriter.convertObject(fields)
 
   private fun extractNestedValue(fieldPath: FieldPath): Value? {
@@ -307,15 +421,32 @@ internal constructor(
     return value
   }
 
+  /**
+   * Retrieves the field specified by [field].
+   *
+   * @param field The field path (e.g. "foo" or "foo.bar") to a specific field.
+   * @return The data at the specified field location or null if no such field exists.
+   */
   fun get(field: String): Any? = get(FieldPath.fromDotSeparatedPath(field))
 
+  /**
+   * Retrieves the field specified by [fieldPath].
+   *
+   * @param fieldPath The field path to a specific field.
+   * @return The data at the specified field location or null if no such field exists.
+   */
   fun get(fieldPath: FieldPath): Any? = userDataWriter.convertValue(extractNestedValue(fieldPath))
 
-  override fun toString() = "PipelineResult{ref=$ref, version=$version}, data=${getData()}"
+  override fun toString() = "PipelineResult{ref=$ref, updateTime=$updateTime}, data=${getData()}"
 }
 
 internal interface PipelineResultObserver {
-  fun onDocument(key: DocumentKey?, data: Map<String, Value>, version: SnapshotVersion)
-  fun onComplete(executionTime: SnapshotVersion)
+  fun onDocument(
+    key: DocumentKey?,
+    data: Map<String, Value>,
+    createTime: Timestamp?,
+    updateTime: Timestamp?
+  )
+  fun onComplete(executionTime: Timestamp)
   fun onError(exception: FirebaseFirestoreException)
 }