From 32ae16eb3b9c8838fb25f832b853b830c6f9bffa Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Fri, 23 Sep 2022 21:41:50 -0400 Subject: [PATCH 01/10] Query.java: add javadocs for count() --- .../java/com/google/firebase/firestore/Query.java | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java index 278c7b96139..a94ace4c01b 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java @@ -1224,10 +1224,17 @@ private void validateHasExplicitOrderByForLimitToLast() { } /** - * Creates an {@link AggregateQuery} counting the number of documents matching this query. + * Returns a query that counts the documents in the result set of this query. * - * @return An {@link AggregateQuery} object that can be used to count the number of documents in - * the result set of this query. + *

The returned query, when executed, counts the documents in the result set of this query + * without actually downloading the documents. The count is performed on the server and + * only the resulting count is downloaded from the server.

+ * + *

Using the returned query to count the documents is efficient because only the final count, + * not the documents' data, is downloaded. The returned query can even count the documents if the + * result set would be prohibitively large to download entirely (e.g. thousands of documents).

+ * + * @return a query that counts the documents in the result set of this query. */ @NonNull public AggregateQuery count() { From 429d710faaf84997908668ff40a22de88a24aeea Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Fri, 23 Sep 2022 21:41:50 -0400 Subject: [PATCH 02/10] AggregateQuery.java: re-write javadocs --- .../firebase/firestore/AggregateQuery.java | 41 +++++++++++++------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java index e21eee3f39a..38129bd4cec 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java @@ -21,32 +21,33 @@ import com.google.firebase.firestore.util.Preconditions; /** - * A {@code AggregateQuery} computes some aggregation statistics from the result set of a base - * {@link Query}. + * A query that calculates aggregations over an underlying query. * *

Subclassing Note: Cloud 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 that does so. */ public class AggregateQuery { - // The base query. + private final Query query; AggregateQuery(@NonNull Query query) { this.query = query; } - /** Returns the base {@link Query} for this aggregate query. */ + /** + * Returns the query whose aggregations will be calculated by this object. + */ @NonNull public Query getQuery() { return query; } /** - * Executes the aggregate query and returns the results as a {@code AggregateQuerySnapshot}. + * Executes this query. * - * @param source A value to configure the get behavior. - * @return A Task that will be resolved with the results of the {@code AggregateQuery}. + * @param source The source from which to acquire the aggregate results. + * @return A {@link Task} that will be resolved with the results of the query. */ @NonNull public Task get(@NonNull AggregateSource source) { @@ -70,12 +71,28 @@ public Task get(@NonNull AggregateSource source) { return tcs.getTask(); } + /** + * Compares this object with the given object for equality. + * + *

This object is considered "equal" to the other object if and only if all of the following + * conditions are satisfied: + * + *

    + *
  1. {@code object} is a non-null instance of {@link AggregateQuery}.
    2. + *
  2. {@code object} performs the same aggregations as this {@link AggregateQuery}.
    3. + *
  3. {@code object} has the same underlying {@link Query} as this {@link AggregateQuery}.
    4. + *
+ * + * @param object The object to compare to this object for equality. + * @return {@code true} if this object is "equal" to the given object, as defined above, or + * {@code false} otherwise. + */ @Override - public boolean equals(Object o) { - if (this == o) return true; - if (!(o instanceof AggregateQuery)) return false; - AggregateQuery that = (AggregateQuery) o; - return query.equals(that.query); + public boolean equals(Object object) { + if (this == object) return true; + if (!(object instanceof AggregateQuery)) return false; + AggregateQuery other = (AggregateQuery) object; + return query.equals(other.query); } @Override From f302b09966373cd8650c0ee18ddceabfadafcf51 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Fri, 23 Sep 2022 21:55:55 -0400 Subject: [PATCH 03/10] Query.java: minor tweaks to javadocs for count() --- .../src/main/java/com/google/firebase/firestore/Query.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java index a94ace4c01b..b8a30dc0092 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java @@ -1228,11 +1228,11 @@ private void validateHasExplicitOrderByForLimitToLast() { * *

The returned query, when executed, counts the documents in the result set of this query * without actually downloading the documents. The count is performed on the server and - * only the resulting count is downloaded from the server.

+ * only the resulting count is downloaded. * *

Using the returned query to count the documents is efficient because only the final count, * not the documents' data, is downloaded. The returned query can even count the documents if the - * result set would be prohibitively large to download entirely (e.g. thousands of documents).

+ * result set would be prohibitively large to download entirely (e.g. thousands of documents). * * @return a query that counts the documents in the result set of this query. */ From 1c8e6e1ba25a14decf91d19af8c5a05d17e4503c Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Fri, 23 Sep 2022 21:55:55 -0400 Subject: [PATCH 04/10] AggregateSource.java: re-write the javadocs --- .../firebase/firestore/AggregateSource.java | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateSource.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateSource.java index abb67c58518..45dd48119eb 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateSource.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateSource.java @@ -14,13 +14,23 @@ package com.google.firebase.firestore; -/** Configures the behavior of {@link AggregateQuery#get}. */ +/** + * The sources from which an {@link AggregateQuery} can retrieve its results. + * + * @see AggregateQuery#get + */ public enum AggregateSource { /** - * Reach to the Firestore backend and surface the result verbatim, that is no local documents or - * mutations in the SDK cache will be included in the surfaced result. + * Perform the aggregation on the server and download the result. * - *

Requires client to be online. + *

The result received from the server is presented, unaltered, without considering any local + * state. That is, any documents in the local cache are ignored and any documents that have been + * locally modified but not yet synchronized with the server are not taken into account. The + * result received from the server is not cached for later use: every request using this source + * necessarily involves a round trip to the server and back. + * + *

The {@link AggregateQuery} will fail if the server cannot be reached, such as if the client + * is offline. */ SERVER, } From d995ce0c63bfab8878a8082be2497fc76b4881fa Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Fri, 23 Sep 2022 21:55:55 -0400 Subject: [PATCH 05/10] AggregateQuerySnapshot.java: re-write the javadocs --- .../firebase/firestore/AggregateQuery.java | 4 +++ .../firestore/AggregateQuerySnapshot.java | 36 ++++++++++++++----- 2 files changed, 32 insertions(+), 8 deletions(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java index 38129bd4cec..986d8cfa6ba 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java @@ -95,6 +95,10 @@ public boolean equals(Object object) { return query.equals(other.query); } + /** + * Calculates and returns the hash code for this object. + * @return the hash code for this object. + */ @Override public int hashCode() { return query.hashCode(); diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java index 6c8cd82d1fc..5e515c43f4a 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java @@ -20,7 +20,7 @@ import java.util.Objects; /** - * A {@code AggregateQuerySnapshot} contains results of a {@link AggregateQuery}. + * The results of executing an {@link AggregateQuery}. * *

Subclassing Note: Cloud 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 @@ -37,25 +37,45 @@ public class AggregateQuerySnapshot { this.count = count; } - /** @return The original {@link AggregateQuery} this snapshot is a result of. */ + /** Returns the query that was executed to produce this result. */ @NonNull public AggregateQuery getQuery() { return query; } - /** @return The result of a document count aggregation. */ + /** Returns the number of documents in the result set of the query. */ public long getCount() { return count; } + /** + * Compares this object with the given object for equality. + * + *

This object is considered "equal" to the other object if and only if all of the following + * conditions are satisfied: + * + *

    + *
  1. {@code object} is a non-null instance of {@link AggregateQuerySnapshot}.
    2. + *
  2. {@code object} has the same {@link AggregateQuery} as this object.
    3. + *
  3. {@code object} has the same results as this object.
    4. + *
+ * + * @param object The object to compare to this object for equality. + * @return {@code true} if this object is "equal" to the given object, as defined above, or + * {@code false} otherwise. + */ @Override - public boolean equals(Object o) { - if (this == o) return true; - if (!(o instanceof AggregateQuerySnapshot)) return false; - AggregateQuerySnapshot snapshot = (AggregateQuerySnapshot) o; - return count == snapshot.count && query.equals(snapshot.query); + public boolean equals(Object object) { + if (this == object) return true; + if (!(object instanceof AggregateQuerySnapshot)) return false; + AggregateQuerySnapshot other = (AggregateQuerySnapshot) object; + return count == other.count && query.equals(other.query); } + /** + * Calculates and returns the hash code for this object. + * @return the hash code for this object. + */ @Override public int hashCode() { return Objects.hash(count, query); From 1580215e787468583cfbcbf09f60a29eeff65edf Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Fri, 23 Sep 2022 22:14:40 -0400 Subject: [PATCH 06/10] format code with `./gradlew :firebase-firestore:googleJavaFormat` --- .../google/firebase/firestore/AggregateQuery.java | 15 +++++++-------- .../firestore/AggregateQuerySnapshot.java | 11 ++++++----- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java index 986d8cfa6ba..085762f6c65 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java @@ -35,9 +35,7 @@ public class AggregateQuery { this.query = query; } - /** - * Returns the query whose aggregations will be calculated by this object. - */ + /** Returns the query whose aggregations will be calculated by this object. */ @NonNull public Query getQuery() { return query; @@ -78,14 +76,14 @@ public Task get(@NonNull AggregateSource source) { * conditions are satisfied: * *
    - *
  1. {@code object} is a non-null instance of {@link AggregateQuery}.
    2. - *
  2. {@code object} performs the same aggregations as this {@link AggregateQuery}.
    3. - *
  3. {@code object} has the same underlying {@link Query} as this {@link AggregateQuery}.
    4. + *
  4. {@code object} is a non-null instance of {@link AggregateQuery}. + *
  5. {@code object} performs the same aggregations as this {@link AggregateQuery}. + *
  6. {@code object} has the same underlying {@link Query} as this {@link AggregateQuery}. *
* * @param object The object to compare to this object for equality. - * @return {@code true} if this object is "equal" to the given object, as defined above, or - * {@code false} otherwise. + * @return {@code true} if this object is "equal" to the given object, as defined above, or {@code + * false} otherwise. */ @Override public boolean equals(Object object) { @@ -97,6 +95,7 @@ public boolean equals(Object object) { /** * Calculates and returns the hash code for this object. + * * @return the hash code for this object. */ @Override diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java index 5e515c43f4a..fc784d56b3d 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java @@ -55,14 +55,14 @@ public long getCount() { * conditions are satisfied: * *
    - *
  1. {@code object} is a non-null instance of {@link AggregateQuerySnapshot}.
    2. - *
  2. {@code object} has the same {@link AggregateQuery} as this object.
    3. - *
  3. {@code object} has the same results as this object.
    4. + *
  4. {@code object} is a non-null instance of {@link AggregateQuerySnapshot}. + *
  5. {@code object} has the same {@link AggregateQuery} as this object. + *
  6. {@code object} has the same results as this object. *
* * @param object The object to compare to this object for equality. - * @return {@code true} if this object is "equal" to the given object, as defined above, or - * {@code false} otherwise. + * @return {@code true} if this object is "equal" to the given object, as defined above, or {@code + * false} otherwise. */ @Override public boolean equals(Object object) { @@ -74,6 +74,7 @@ public boolean equals(Object object) { /** * Calculates and returns the hash code for this object. + * * @return the hash code for this object. */ @Override From b9265f1d86a87805981add314945c952822ddac7 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Mon, 26 Sep 2022 10:10:43 -0400 Subject: [PATCH 07/10] minor clarification to javadocs for equals() --- .../main/java/com/google/firebase/firestore/AggregateQuery.java | 2 +- .../com/google/firebase/firestore/AggregateQuerySnapshot.java | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java index 085762f6c65..cb7f1684759 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuery.java @@ -78,7 +78,7 @@ public Task get(@NonNull AggregateSource source) { *
    *
  1. {@code object} is a non-null instance of {@link AggregateQuery}. *
  2. {@code object} performs the same aggregations as this {@link AggregateQuery}. - *
  3. {@code object} has the same underlying {@link Query} as this {@link AggregateQuery}. + *
  4. The underlying {@link Query} of {@code object} compares equal to that of this object. *
* * @param object The object to compare to this object for equality. diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java index fc784d56b3d..5d8410bf07b 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java @@ -56,7 +56,7 @@ public long getCount() { * *
    *
  1. {@code object} is a non-null instance of {@link AggregateQuerySnapshot}. - *
  2. {@code object} has the same {@link AggregateQuery} as this object. + *
  3. The {@link AggregateQuery} of {@code object} compares equal to that of this object. *
  4. {@code object} has the same results as this object. *
* From dcf5ec3b9893b1b736fa0c1230334162fad269bb Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Mon, 26 Sep 2022 10:18:50 -0400 Subject: [PATCH 08/10] AggregateSource.java: re-word docs for SERVER --- .../com/google/firebase/firestore/AggregateSource.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateSource.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateSource.java index 45dd48119eb..31402ba99e4 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateSource.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateSource.java @@ -24,10 +24,10 @@ public enum AggregateSource { * Perform the aggregation on the server and download the result. * *

The result received from the server is presented, unaltered, without considering any local - * state. That is, any documents in the local cache are ignored and any documents that have been - * locally modified but not yet synchronized with the server are not taken into account. The - * result received from the server is not cached for later use: every request using this source - * necessarily involves a round trip to the server and back. + * state. That is, documents in the local cache are not taken into consideration, neither are + * local modifications not yet synchronized with the server. Previously-downloaded results, if + * any, are not used: every request using this source necessarily involves a round trip to the + * server. * *

The {@link AggregateQuery} will fail if the server cannot be reached, such as if the client * is offline. From e7ed96c16fe8c1a921fbf928d4e7d2cb850b6c68 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Mon, 26 Sep 2022 10:20:21 -0400 Subject: [PATCH 09/10] AggregateQuerySnapshot.java: minor change to javadocs for getCount() --- .../com/google/firebase/firestore/AggregateQuerySnapshot.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java index 5d8410bf07b..2d8ee7be8f0 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/AggregateQuerySnapshot.java @@ -43,7 +43,7 @@ public AggregateQuery getQuery() { return query; } - /** Returns the number of documents in the result set of the query. */ + /** Returns the number of documents in the result set of the underlying query. */ public long getCount() { return count; } From df265cd9b9492c917f7b04e6990c3231885c882a Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Mon, 26 Sep 2022 17:22:32 -0400 Subject: [PATCH 10/10] Remove extra docs from Query.count() --- .../src/main/java/com/google/firebase/firestore/Query.java | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java b/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java index b8a30dc0092..8db1e9ff8db 100644 --- a/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java +++ b/firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java @@ -1227,8 +1227,7 @@ private void validateHasExplicitOrderByForLimitToLast() { * Returns a query that counts the documents in the result set of this query. * *

The returned query, when executed, counts the documents in the result set of this query - * without actually downloading the documents. The count is performed on the server and - * only the resulting count is downloaded. + * without actually downloading the documents. * *

Using the returned query to count the documents is efficient because only the final count, * not the documents' data, is downloaded. The returned query can even count the documents if the