add named options to CollectionSource and CollectionGroupSource

Author: tom-andersen

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

@@ -21,7 +21,6 @@ import com.google.common.collect.ImmutableList
 import com.google.firebase.Timestamp
 import com.google.firebase.firestore.model.DocumentKey
 import com.google.firebase.firestore.model.Values
-import com.google.firebase.firestore.pipeline.AbstractOptions
 import com.google.firebase.firestore.pipeline.AddFieldsStage
 import com.google.firebase.firestore.pipeline.AggregateFunction
 import com.google.firebase.firestore.pipeline.AggregateStage
@@ -39,7 +38,6 @@ import com.google.firebase.firestore.pipeline.FindNearestStage
 import com.google.firebase.firestore.pipeline.FunctionExpr
 import com.google.firebase.firestore.pipeline.GenericArg
 import com.google.firebase.firestore.pipeline.GenericStage
-import com.google.firebase.firestore.pipeline.InternalOptions
 import com.google.firebase.firestore.pipeline.LimitStage
 import com.google.firebase.firestore.pipeline.OffsetStage
 import com.google.firebase.firestore.pipeline.Ordering
@@ -54,7 +52,6 @@ import com.google.firebase.firestore.pipeline.Stage
 import com.google.firebase.firestore.pipeline.UnionStage
 import com.google.firebase.firestore.pipeline.UnnestStage
 import com.google.firebase.firestore.pipeline.WhereStage
-import com.google.firebase.firestore.util.Preconditions
 import com.google.firestore.v1.ExecutePipelineRequest
 import com.google.firestore.v1.StructuredPipeline
 import com.google.firestore.v1.Value
@@ -614,7 +611,7 @@ class PipelineSource internal constructor(private val firestore: FirebaseFiresto
    * 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]
+   * @return A new [Pipeline] object that is equivalent to [query]
    * @throws [IllegalArgumentException] Thrown if the [query] provided targets a different project
    * or database than the pipeline.
    */
@@ -629,7 +626,7 @@ class PipelineSource internal constructor(private val firestore: FirebaseFiresto
    * 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]
+   * @return A new [Pipeline] object that is equivalent to [aggregateQuery]
    * @throws [IllegalArgumentException] Thrown if the [aggregateQuery] provided targets a different
    * project or database than the pipeline.
    */
@@ -646,46 +643,50 @@ class PipelineSource internal constructor(private val firestore: FirebaseFiresto
    * 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.
+   * @return A new [Pipeline] object with documents from target collection.
    */
-  fun collection(path: String): Pipeline =
-    // Validate path by converting to CollectionReference
-    collection(firestore.collection(path))
+  fun collection(path: String): Pipeline = collection(CollectionSource.of(path))
 
   /**
-   * Set the pipeline's source to the collection specified by the given CollectionReference.
+   * 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.
+   * @param ref A [CollectionReference] for a collection that will be the source of this pipeline.
+   * @return A new [Pipeline] object 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(
-        "Provided collection reference is from a different Firestore instance."
-      )
+  fun collection(ref: CollectionReference): Pipeline = collection(CollectionSource.of(ref))
+
+  /**
+   * Set the pipeline's source to the collection specified by CollectionSource.
+   *
+   * @param stage A [CollectionSource] that will be the source of this pipeline.
+   * @return Pipeline with documents from target collection.
+   * @throws [IllegalArgumentException] Thrown if the [stage] provided targets a different project
+   * or database than the pipeline.
+   */
+  fun collection(stage: CollectionSource): Pipeline {
+    if (stage.firestore != null && stage.firestore.databaseId != firestore.databaseId) {
+      throw IllegalArgumentException("Provided collection is from a different Firestore instance.")
     }
-    return Pipeline(firestore, firestore.userDataReader, CollectionSource(ref.path))
+    return Pipeline(firestore, firestore.userDataReader, stage)
   }
 
   /**
    * 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.
+   * @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("/")) {
-      "Invalid collectionId '$collectionId'. Collection IDs must not contain '/'."
-    }
-    return Pipeline(firestore, firestore.userDataReader, CollectionGroupSource(collectionId))
-  }
+  fun collectionGroup(collectionId: String): Pipeline =
+    pipeline(CollectionGroupSource.of((collectionId)))
+
+  fun pipeline(stage: CollectionGroupSource): Pipeline =
+    Pipeline(firestore, firestore.userDataReader, stage)
 
   /**
    * Set the pipeline's source to be all documents in this database.
    *
-   * @return Pipeline with all documents in this database.
+   * @return A new [Pipeline] object with all documents in this database.
    */
   fun database(): Pipeline = Pipeline(firestore, firestore.userDataReader, DatabaseSource())
 
@@ -694,7 +695,7 @@ class PipelineSource internal constructor(private val firestore: FirebaseFiresto
    *
    * @param documents Paths specifying the individual documents that will be the source of this
    * pipeline.
-   * @return Pipeline with [documents].
+   * @return A new [Pipeline] object with [documents].
    */
   fun documents(vararg documents: String): Pipeline =
     // Validate document path by converting to DocumentReference

firebase-firestore/src/main/java/com/google/firebase/firestore/core/Query.java

@@ -35,6 +35,7 @@
 import com.google.firebase.firestore.pipeline.Expr;
 import com.google.firebase.firestore.pipeline.Field;
 import com.google.firebase.firestore.pipeline.FunctionExpr;
+import com.google.firebase.firestore.pipeline.InternalOptions;
 import com.google.firebase.firestore.pipeline.Ordering;
 import com.google.firebase.firestore.pipeline.Stage;
 import com.google.firestore.v1.Value;
@@ -521,7 +522,7 @@ private synchronized Target toTarget(List<OrderBy> orderBys) {
 
   @NonNull
   public Pipeline toPipeline(FirebaseFirestore firestore, UserDataReader userDataReader) {
-    Pipeline p = new Pipeline(firestore, userDataReader, pipelineSource());
+    Pipeline p = new Pipeline(firestore, userDataReader, pipelineSource(firestore));
 
     // Filters
     for (Filter filter : filters) {
@@ -598,13 +599,13 @@ private static BooleanExpr whereConditionsFromCursor(
   }
 
   @NonNull
-  private Stage pipelineSource() {
+  private Stage<?> pipelineSource(FirebaseFirestore firestore) {
     if (isDocumentQuery()) {
       return new DocumentsSource(path.canonicalString());
     } else if (isCollectionGroupQuery()) {
-      return new CollectionGroupSource(collectionGroup);
+      return CollectionGroupSource.of(collectionGroup);
     } else {
-      return new CollectionSource(path.canonicalString());
+      return new CollectionSource(path.canonicalString(), firestore, InternalOptions.EMPTY);
     }
   }
 

firebase-firestore/src/main/java/com/google/firebase/firestore/pipeline/stage.kt

@@ -14,12 +14,16 @@
 
 package com.google.firebase.firestore.pipeline
 
+import com.google.firebase.firestore.CollectionReference
+import com.google.firebase.firestore.FirebaseFirestore
 import com.google.firebase.firestore.UserDataReader
 import com.google.firebase.firestore.VectorValue
+import com.google.firebase.firestore.model.ResourcePath
 import com.google.firebase.firestore.model.Values
 import com.google.firebase.firestore.model.Values.encodeValue
 import com.google.firebase.firestore.pipeline.Expr.Companion.constant
 import com.google.firebase.firestore.pipeline.Expr.Companion.field
+import com.google.firebase.firestore.util.Preconditions
 import com.google.firestore.v1.Pipeline
 import com.google.firestore.v1.Value
 
@@ -93,7 +97,7 @@ internal constructor(protected val name: String, internal val options: InternalO
  * not implemented in the SDK version being used.
  */
 class GenericStage
-internal constructor(
+private constructor(
   name: String,
   private val arguments: List<GenericArg>,
   options: InternalOptions = InternalOptions.EMPTY
@@ -168,24 +172,72 @@ internal constructor(options: InternalOptions = InternalOptions.EMPTY) :
   override fun args(userDataReader: UserDataReader): Sequence<Value> = emptySequence()
 }
 
-internal class CollectionSource
-@JvmOverloads
-internal constructor(val path: String, options: InternalOptions = InternalOptions.EMPTY) :
+class CollectionSource
+internal constructor(
+  private val path: String,
+  // We validate [firestore.databaseId] when adding to pipeline.
+  internal val firestore: FirebaseFirestore?,
+  options: InternalOptions) :
   Stage<CollectionSource>("collection", options) {
-  override fun self(options: InternalOptions): CollectionSource = CollectionSource(path, options)
+  override fun self(options: InternalOptions): CollectionSource = CollectionSource(path, firestore, options)
   override fun args(userDataReader: UserDataReader): Sequence<Value> =
     sequenceOf(
       Value.newBuilder().setReferenceValue(if (path.startsWith("/")) path else "/" + path).build()
     )
+  companion object {
+    /**
+     * 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.
+     */
+    @JvmStatic
+    fun of(path: String): CollectionSource {
+      // Validate path by converting to ResourcePath
+      val resourcePath = ResourcePath.fromString(path)
+      return CollectionSource(resourcePath.canonicalString(), null, InternalOptions.EMPTY)
+    }
+
+    /**
+     * 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.
+     */
+    @JvmStatic
+    fun of(ref: CollectionReference): CollectionSource {
+      return CollectionSource(ref.path, ref.firestore, InternalOptions.EMPTY)
+    }
+  }
+
+  fun withForceIndex(value: String) = with("force_index", value)
 }
 
-internal class CollectionGroupSource
-@JvmOverloads
-internal constructor(val collectionId: String, options: InternalOptions = InternalOptions.EMPTY) :
+class CollectionGroupSource
+private constructor(private val collectionId: String, options: InternalOptions) :
   Stage<CollectionGroupSource>("collection_group", options) {
   override fun self(options: InternalOptions) = CollectionGroupSource(collectionId, options)
   override fun args(userDataReader: UserDataReader): Sequence<Value> =
     sequenceOf(Value.newBuilder().setReferenceValue("").build(), encodeValue(collectionId))
+
+  companion object {
+
+    /**
+     * 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.
+     */
+    @JvmStatic
+    fun of(collectionId: String): CollectionGroupSource {
+      Preconditions.checkNotNull(collectionId, "Provided collection ID must not be null.")
+      require(!collectionId.contains("/")) {
+        "Invalid collectionId '$collectionId'. Collection IDs must not contain '/'."
+      }
+      return CollectionGroupSource(collectionId, InternalOptions.EMPTY)
+    }
+  }
+
+  fun withForceIndex(value: String) = with("force_index", value)
 }
 
 internal class DocumentsSource