Firestore Bundles (#2398)

Author: schmidt-sebastian

firebase-firestore/CHANGELOG.md

@@ -1,13 +1,22 @@
-# Unreleased
-- [fixed] Removed excess validation of null and NaN values in query filters.
-  This more closely aligns the SDK with the Firestore backend, which has always
-  accepted null and NaN for all operators, even though this isn't necessarily
-  useful.
+# Unreleased (22.1.0)
+- [feature] Added support for Firestore Bundles via
+  `FirebaseFirestore.loadBundle()` and `FirebaseFirestore.getNamedQuery()`.
+  Bundles contain pre-packaged data produced with the NodeJS Server SDK and
+  can be used to populate Firestore's cache without reading documents from
+  the backend.
+
+# (22.0.2)
 - [changed] A write to a document that contains FieldValue transforms is no
   longer split up into two separate operations. This reduces the number of
   writes the backend performs and allows each WriteBatch to hold 500 writes
   regardless of how many FieldValue transformations are attached.
 
+# (22.0.1)
+- [fixed] Removed excess validation of null and NaN values in query filters.
+  This more closely aligns the SDK with the Firestore backend, which has always
+  accepted null and NaN for all operators, even though this isn't necessarily
+  useful.
+
 # (22.0.0)
 - [changed] Removed the deprecated `timestampsInSnapshotsEnabled` setting.
   Any timestamps in Firestore documents are now returned as `Timestamps`. To

firebase-firestore/api.txt

@@ -146,6 +146,10 @@ package com.google.firebase.firestore {
     method @NonNull public com.google.firebase.firestore.FirebaseFirestoreSettings getFirestoreSettings();
     method @NonNull public static com.google.firebase.firestore.FirebaseFirestore getInstance();
     method @NonNull public static com.google.firebase.firestore.FirebaseFirestore getInstance(@NonNull com.google.firebase.FirebaseApp);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.Query> getNamedQuery(@NonNull String);
+    method @NonNull public com.google.firebase.firestore.LoadBundleTask loadBundle(@NonNull java.io.InputStream);
+    method @NonNull public com.google.firebase.firestore.LoadBundleTask loadBundle(@NonNull byte[]);
+    method @NonNull public com.google.firebase.firestore.LoadBundleTask loadBundle(@NonNull java.nio.ByteBuffer);
     method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> runBatch(@NonNull com.google.firebase.firestore.WriteBatch.Function);
     method @NonNull public <TResult> com.google.android.gms.tasks.Task<TResult> runTransaction(@NonNull com.google.firebase.firestore.Transaction.Function<TResult>);
     method public void setFirestoreSettings(@NonNull com.google.firebase.firestore.FirebaseFirestoreSettings);
@@ -219,11 +223,60 @@ package com.google.firebase.firestore {
     method public void remove();
   }
 
+  public class LoadBundleTask extends com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> {
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnCanceledListener(@NonNull com.google.android.gms.tasks.OnCanceledListener);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnCanceledListener(@NonNull java.util.concurrent.Executor, @NonNull com.google.android.gms.tasks.OnCanceledListener);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnCanceledListener(@NonNull android.app.Activity, @NonNull com.google.android.gms.tasks.OnCanceledListener);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnCompleteListener(@NonNull com.google.android.gms.tasks.OnCompleteListener<com.google.firebase.firestore.LoadBundleTaskProgress>);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnCompleteListener(@NonNull java.util.concurrent.Executor, @NonNull com.google.android.gms.tasks.OnCompleteListener<com.google.firebase.firestore.LoadBundleTaskProgress>);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnCompleteListener(@NonNull android.app.Activity, @NonNull com.google.android.gms.tasks.OnCompleteListener<com.google.firebase.firestore.LoadBundleTaskProgress>);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnFailureListener(@NonNull com.google.android.gms.tasks.OnFailureListener);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnFailureListener(@NonNull java.util.concurrent.Executor, @NonNull com.google.android.gms.tasks.OnFailureListener);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnFailureListener(@NonNull android.app.Activity, @NonNull com.google.android.gms.tasks.OnFailureListener);
+    method @NonNull public com.google.firebase.firestore.LoadBundleTask addOnProgressListener(@NonNull com.google.firebase.firestore.OnProgressListener<com.google.firebase.firestore.LoadBundleTaskProgress>);
+    method @NonNull public com.google.firebase.firestore.LoadBundleTask addOnProgressListener(@NonNull java.util.concurrent.Executor, @NonNull com.google.firebase.firestore.OnProgressListener<com.google.firebase.firestore.LoadBundleTaskProgress>);
+    method @NonNull public com.google.firebase.firestore.LoadBundleTask addOnProgressListener(@NonNull android.app.Activity, @NonNull com.google.firebase.firestore.OnProgressListener<com.google.firebase.firestore.LoadBundleTaskProgress>);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnSuccessListener(@NonNull com.google.android.gms.tasks.OnSuccessListener<? super com.google.firebase.firestore.LoadBundleTaskProgress>);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnSuccessListener(@NonNull java.util.concurrent.Executor, @NonNull com.google.android.gms.tasks.OnSuccessListener<? super com.google.firebase.firestore.LoadBundleTaskProgress>);
+    method @NonNull public com.google.android.gms.tasks.Task<com.google.firebase.firestore.LoadBundleTaskProgress> addOnSuccessListener(@NonNull android.app.Activity, @NonNull com.google.android.gms.tasks.OnSuccessListener<? super com.google.firebase.firestore.LoadBundleTaskProgress>);
+    method @NonNull public <TContinuationResult> com.google.android.gms.tasks.Task<TContinuationResult> continueWith(@NonNull com.google.android.gms.tasks.Continuation<com.google.firebase.firestore.LoadBundleTaskProgress,TContinuationResult>);
+    method @NonNull public <TContinuationResult> com.google.android.gms.tasks.Task<TContinuationResult> continueWith(@NonNull java.util.concurrent.Executor, @NonNull com.google.android.gms.tasks.Continuation<com.google.firebase.firestore.LoadBundleTaskProgress,TContinuationResult>);
+    method @NonNull public <TContinuationResult> com.google.android.gms.tasks.Task<TContinuationResult> continueWithTask(@NonNull com.google.android.gms.tasks.Continuation<com.google.firebase.firestore.LoadBundleTaskProgress,com.google.android.gms.tasks.Task<TContinuationResult>>);
+    method @NonNull public <TContinuationResult> com.google.android.gms.tasks.Task<TContinuationResult> continueWithTask(@NonNull java.util.concurrent.Executor, @NonNull com.google.android.gms.tasks.Continuation<com.google.firebase.firestore.LoadBundleTaskProgress,com.google.android.gms.tasks.Task<TContinuationResult>>);
+    method @Nullable public Exception getException();
+    method @NonNull public com.google.firebase.firestore.LoadBundleTaskProgress getResult();
+    method @NonNull public <X extends java.lang.Throwable> com.google.firebase.firestore.LoadBundleTaskProgress getResult(@NonNull Class<X>) throws X;
+    method public boolean isCanceled();
+    method public boolean isComplete();
+    method public boolean isSuccessful();
+    method @NonNull public <TContinuationResult> com.google.android.gms.tasks.Task<TContinuationResult> onSuccessTask(@NonNull com.google.android.gms.tasks.SuccessContinuation<com.google.firebase.firestore.LoadBundleTaskProgress,TContinuationResult>);
+    method @NonNull public <TContinuationResult> com.google.android.gms.tasks.Task<TContinuationResult> onSuccessTask(@NonNull java.util.concurrent.Executor, @NonNull com.google.android.gms.tasks.SuccessContinuation<com.google.firebase.firestore.LoadBundleTaskProgress,TContinuationResult>);
+  }
+
+  public final class LoadBundleTaskProgress {
+    method public long getBytesLoaded();
+    method public int getDocumentsLoaded();
+    method @Nullable public Exception getException();
+    method @NonNull public com.google.firebase.firestore.LoadBundleTaskProgress.TaskState getTaskState();
+    method public long getTotalBytes();
+    method public int getTotalDocuments();
+  }
+
+  public enum LoadBundleTaskProgress.TaskState {
+    enum_constant public static final com.google.firebase.firestore.LoadBundleTaskProgress.TaskState ERROR;
+    enum_constant public static final com.google.firebase.firestore.LoadBundleTaskProgress.TaskState RUNNING;
+    enum_constant public static final com.google.firebase.firestore.LoadBundleTaskProgress.TaskState SUCCESS;
+  }
+
   public enum MetadataChanges {
     enum_constant public static final com.google.firebase.firestore.MetadataChanges EXCLUDE;
     enum_constant public static final com.google.firebase.firestore.MetadataChanges INCLUDE;
   }
 
+  public interface OnProgressListener<ProgressT> {
+    method public void onProgress(@NonNull ProgressT);
+  }
+
   @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.RUNTIME) @java.lang.annotation.Target({java.lang.annotation.ElementType.METHOD, java.lang.annotation.ElementType.FIELD}) public @interface PropertyName {
     method public abstract String value();
   }