add public docs

Author: wu-hui

google-cloud-firestore/src/main/java/com/google/cloud/firestore/Pipeline.java

@@ -32,12 +32,11 @@
 import javax.annotation.Nullable;
 
 /**
- * A DocumentSnapshot contains data read from a document in a Firestore database. The data can be
- * extracted with the {@link #getData()} or {@link #get(String)} methods.
+ * A PipelineResult contains data read from a Firestore Pipeline. The data can be extracted with the
+ * {@link #getData()} or {@link #get(String)} methods.
  *
- * <p>If the DocumentSnapshot points to a non-existing document, getData() and its corresponding
- * methods will return null. You can always explicitly check for a document's existence by calling
- * {@link #exists()}.
+ * <p>If the PipelineResult represents a non-document result, getReference() will return a null
+ * value.
  *
  * <p><b>Subclassing Note</b>: Firestore classes are not meant to be subclassed except for use in
  * test mocks. Subclassing is not supported in production code and new SDK releases may break code
@@ -50,31 +49,30 @@ public final class PipelineResult {
   private final FirestoreRpcContext<?> rpcContext;
   @Nullable private final DocumentReference docRef;
   @Nullable private final Map<String, Value> fields;
-  @Nullable private final Timestamp readTime;
+  @Nonnull private final Timestamp executionTime;
   @Nullable private final Timestamp updateTime;
   @Nullable private final Timestamp createTime;
 
   PipelineResult(
       FirestoreRpcContext<?> rpcContext,
       @Nullable DocumentReference docRef,
       @Nullable Map<String, Value> fields,
-      @Nullable Timestamp readTime,
+      @Nonnull Timestamp executionTime,
       @Nullable Timestamp updateTime,
       @Nullable Timestamp createTime) { // Elevated access level for mocking.
     this.rpcContext = rpcContext;
     this.docRef = docRef;
     this.fields = fields;
-    this.readTime = readTime;
+    this.executionTime = executionTime;
     this.updateTime = updateTime;
     this.createTime = createTime;
   }
 
   /**
-   * Returns the ID of the document contained in this snapshot.
-   *
-   * @return The id of the document.
+   * Returns the ID of the document represented by this result. Returns null if this result is not
+   * corresponding to a Firestore document.
    */
-  @Nonnull
+  @Nullable
   @BetaApi
   public String getId() {
     return docRef.getId();
@@ -93,23 +91,16 @@ static PipelineResult fromDocument(
         Timestamp.fromProto(document.getCreateTime()));
   }
 
-  /**
-   * Returns the time at which this snapshot was read.
-   *
-   * @return The read time of this snapshot.
-   */
+  /** Returns the time at which the pipeline producing this result is executed. */
   @Nullable
   @BetaApi
-  public Timestamp getReadTime() {
-    return readTime;
+  public Timestamp getExecutionTime() {
+    return executionTime;
   }
 
   /**
-   * Returns the time at which this document was last updated. Returns null for non-existing
-   * documents.
-   *
-   * @return The last time the document in the snapshot was updated. Null if the document doesn't
-   *     exist.
+   * Returns the time at which this document was last updated. Returns null if this result is not
+   * corresponding to a Firestore document.
    */
   @Nullable
   @BetaApi
@@ -118,10 +109,8 @@ public Timestamp getUpdateTime() {
   }
 
   /**
-   * Returns the time at which this document was created. Returns null for non-existing documents.
-   *
-   * @return The last time the document in the snapshot was created. Null if the document doesn't
-   *     exist.
+   * Returns the time at which this document was created. Returns null if this result is not
+   * corresponding to a Firestore document.
    */
   @Nullable
   @BetaApi
@@ -141,12 +130,12 @@ public boolean exists() {
   }
 
   /**
-   * Returns the fields of the document as a Map or null if the document doesn't exist. Field values
+   * Returns the fields of the result as a Map or null if the result doesn't exist. Field values
    * will be converted to their native Java representation.
    *
-   * @return The fields of the document as a Map or null if the document doesn't exist.
+   * @return The fields of the document as a Map or null if the result doesn't exist.
    */
-  @Nullable
+  @Nonnull
   @BetaApi
   public Map<String, Object> getData() {
     if (fields == null) {
@@ -162,10 +151,10 @@ public Map<String, Object> getData() {
   }
 
   /**
-   * Returns the contents of the document converted to a POJO or null if the document doesn't exist.
+   * Returns the contents of the document converted to a POJO or null if the result doesn't exist.
    *
    * @param valueType The Java class to create
-   * @return The contents of the document in an object of type T or null if the document doesn't
+   * @return The contents of the document in an object of type T or null if the result doesn't
    *     exist.
    */
   @Nullable
@@ -176,7 +165,7 @@ public <T> T toObject(@Nonnull Class<T> valueType) {
   }
 
   /**
-   * Returns whether or not the field exists in the document. Returns false if the document does not
+   * Returns whether or not the field exists in the document. Returns false if the result does not
    * exist.
    *
    * @param field the path to the field.
@@ -188,7 +177,7 @@ public boolean contains(@Nonnull String field) {
   }
 
   /**
-   * Returns whether or not the field exists in the document. Returns false if the document does not
+   * Returns whether or not the field exists in the document. Returns false if the result does not
    * exist.
    *
    * @param fieldPath the path to the field.
@@ -212,7 +201,7 @@ public Object get(@Nonnull String field) {
   }
 
   /**
-   * Returns the value at the field, converted to a POJO, or null if the field or document doesn't
+   * Returns the value at the field, converted to a POJO, or null if the field or result doesn't
    * exist.
    *
    * @param field The path to the field
@@ -244,7 +233,7 @@ public Object get(@Nonnull FieldPath fieldPath) {
   }
 
   /**
-   * Returns the value at the field, converted to a POJO, or null if the field or document doesn't
+   * Returns the value at the field, converted to a POJO, or null if the field or result doesn't
    * exist.
    *
    * @param fieldPath The path to the field
@@ -390,7 +379,6 @@ public GeoPoint getGeoPoint(@Nonnull String field) {
    *
    * @return The reference to the document.
    */
-  @Nonnull
   @BetaApi
   public DocumentReference getReference() {
     return docRef;
@@ -455,6 +443,6 @@ public int hashCode() {
   public String toString() {
     return String.format(
         "%s{doc=%s, fields=%s, readTime=%s, updateTime=%s, createTime=%s}",
-        getClass().getSimpleName(), docRef, fields, readTime, updateTime, createTime);
+        getClass().getSimpleName(), docRef, fields, executionTime, updateTime, createTime);
   }
 }

google-cloud-firestore/src/main/java/com/google/cloud/firestore/PipelineResult.java

@@ -9,6 +9,25 @@
 import com.google.common.base.Preconditions;
 import javax.annotation.Nonnull;
 
+/**
+ * A factory for creating {@link Pipeline} instances, which provide a framework for building data
+ * transformation and query pipelines for Firestore.
+ *
+ * <p>Start by calling {@link Firestore#pipeline()} to obtain an instance of {@code PipelineSource}.
+ * From there, you can use the provided methods (like {@link #collection(String)}) to specify the
+ * data source for your pipeline.
+ *
+ * <p>This class is typically used to start building Firestore pipelines. It allows you to define
+ * the initial data source for a pipeline.
+ *
+ * <p>Example Usage:
+ *
+ * <pre>{@code
+ * firestore.pipeline() // Get a PipelineSource instance
+ *   .collection("users") // Create a pipeline that operates on a collection
+ *   .select("name"); // Add stages to the pipeline
+ * }</pre>
+ */
 @BetaApi
 public class PipelineSource {
   private final Firestore db;
@@ -18,12 +37,28 @@ public class PipelineSource {
     this.db = db;
   }
 
+  /**
+   * Creates a new {@link Pipeline} that operates on the specified Firestore collection.
+   *
+   * @param path The path to the Firestore collection (e.g., "users").
+   * @return A new {@code Pipeline} instance targeting the specified collection.
+   */
   @Nonnull
   @BetaApi
   public Pipeline collection(@Nonnull String path) {
     return new Pipeline(this.db, new Collection(path));
   }
 
+  /**
+   * Creates a new {@link Pipeline} that operates on all documents in a collection group.
+   *
+   * <p>A collection group consists of all collections with the same ID. For example, if you have
+   * collections named "users" under different documents, you can query them together using a
+   * collection group query.
+   *
+   * @param collectionId The ID of the collection group.
+   * @return A new {@code Pipeline} instance targeting the specified collection group.
+   */
   @Nonnull
   @BetaApi
   public Pipeline collectionGroup(@Nonnull String collectionId) {
@@ -34,12 +69,27 @@ public Pipeline collectionGroup(@Nonnull String collectionId) {
     return new Pipeline(this.db, new CollectionGroup(collectionId));
   }
 
+  /**
+   * Creates a new {@link Pipeline} that operates on all documents in the Firestore database.
+   *
+   * <p>Use this method with caution as it can lead to very large result sets. It is usually only
+   * useful at development stage.
+   *
+   * @return A new {@code Pipeline} instance targeting all documents in the database.
+   */
   @Nonnull
   @BetaApi
   public Pipeline database() {
     return new Pipeline(this.db, new Database());
   }
 
+  /**
+   * Creates a new {@link Pipeline} that operates on a specific set of Firestore documents.
+   *
+   * @param docs The {@link DocumentReference} instances representing the documents to include in
+   *     the pipeline.
+   * @return A new {@code Pipeline} instance targeting the specified documents.
+   */
   @Nonnull
   @BetaApi
   public Pipeline documents(DocumentReference... docs) {

google-cloud-firestore/src/main/java/com/google/cloud/firestore/PipelineSource.java

@@ -13,7 +13,6 @@
 import com.google.cloud.firestore.Query.FilterInternal;
 import com.google.cloud.firestore.Query.LimitType;
 import com.google.cloud.firestore.Query.UnaryFilterInternal;
-import com.google.cloud.firestore.pipeline.PaginatingPipeline;
 import com.google.cloud.firestore.pipeline.expressions.Accumulator;
 import com.google.cloud.firestore.pipeline.expressions.AccumulatorTarget;
 import com.google.cloud.firestore.pipeline.expressions.Expr;
@@ -125,37 +124,8 @@ static Pipeline toPaginatedPipeline(
       Integer limit,
       LimitType limitType,
       Integer offset) {
-
-    // Handle null limit, setting a default maximum
-    int effectiveLimit = (limit != null) ? limit : Integer.MAX_VALUE;
-
-    PaginatingPipeline paginate = pipeline.paginate(effectiveLimit);
-
-    // Apply start and end cursors if present
-    if (start != null) {
-      paginate = paginate.withStartCursor(start);
-    }
-    if (end != null) {
-      paginate = paginate.withEndCursor(end);
-    }
-    if (offset != null) {
-      paginate = paginate.offset(offset);
-    }
-
-    // Handle limitType, defaulting to firstPage
-    if (limitType != null) {
-      switch (limitType) {
-        case First:
-          return paginate.firstPage();
-        case Last:
-          return paginate.lastPage();
-        default:
-          // Handle other LimitType cases as needed, or throw an exception
-          throw new IllegalArgumentException("Unsupported limit type: " + limitType);
-      }
-    } else {
-      return paginate.firstPage();
-    }
+    throw new UnsupportedOperationException(
+        "Converting to pagination pipeline is not support yet.");
   }
 
   @InternalApi

google-cloud-firestore/src/main/java/com/google/cloud/firestore/PipelineUtils.java

@@ -2170,11 +2170,9 @@ public Pipeline pipeline() {
           normalizedOrderbys.stream()
               .map(
                   fieldOrder ->
-                      Ordering.of(
-                          Field.of(fieldOrder.fieldReference.getFieldPath()),
-                          fieldOrder.direction == Direction.ASCENDING
-                              ? Ordering.Direction.ASCENDING
-                              : Ordering.Direction.DESCENDING))
+                      fieldOrder.direction == Direction.ASCENDING
+                          ? Field.of(fieldOrder.fieldReference.getFieldPath()).ascending()
+                          : Field.of(fieldOrder.fieldReference.getFieldPath()).descending())
               .collect(Collectors.toList());
       ppl = ppl.sort(orders, Density.REQUIRED, Truncation.UNSPECIFIED);
     }