[c++] port addSnapshotsInSyncListener

+mcg@ for java readability approval

TESTED=
linux: http://sponge2/e38ce350-ddeb-4461-9db7-07d20ed34e29
iOS: http://sponge2/f1fa15e4-747d-43f4-b725-f5f38ef9f9d3
Android:http://sponge2/72ec3dd4-cb27-4698-a14a-f365c03ee5f2
PiperOrigin-RevId: 292610511

Author: Googler

firestore/src/android/event_listener_android.cc

@@ -39,6 +39,13 @@ METHOD_LOOKUP_DEFINITION(
     "com/google/firebase/firestore/internal/cpp/QueryEventListener",
     QUERY_EVENT_LISTENER_METHODS)
 
+#define VOID_EVENT_LISTENER_METHODS(X) X(Constructor, "<init>", "(J)V")
+METHOD_LOOKUP_DECLARATION(void_event_listener, VOID_EVENT_LISTENER_METHODS)
+METHOD_LOOKUP_DEFINITION(
+    void_event_listener,
+    "com/google/firebase/firestore/internal/cpp/VoidEventListener",
+    VOID_EVENT_LISTENER_METHODS)
+
 /* static */
 void EventListenerInternal::DocumentEventListenerNativeOnEvent(
     JNIEnv* env, jclass clazz, jlong firestore_ptr, jlong listener_ptr,
@@ -83,6 +90,19 @@ void EventListenerInternal::QueryEventListenerNativeOnEvent(
   listener->OnEvent(snapshot, error_code);
 }
 
+/* static */
+void EventListenerInternal::VoidEventListenerNativeOnEvent(JNIEnv* env,
+                                                           jclass clazz,
+                                                           jlong listener_ptr) {
+  if (listener_ptr == 0) {
+    return;
+  }
+  EventListener<void>* listener =
+      reinterpret_cast<EventListener<void>*>(listener_ptr);
+
+  listener->OnEvent(Error::Ok);
+}
+
 /* static */
 jobject EventListenerInternal::EventListenerToJavaEventListener(
     JNIEnv* env, FirestoreInternal* firestore,
@@ -108,6 +128,17 @@ jobject EventListenerInternal::EventListenerToJavaEventListener(
   return result;
 }
 
+/* static */
+jobject EventListenerInternal::EventListenerToJavaRunnable(
+    JNIEnv* env, EventListener<void>* listener) {
+  jobject result = env->NewObject(
+      void_event_listener::GetClass(),
+      void_event_listener::GetMethodId(void_event_listener::kConstructor),
+      reinterpret_cast<jlong>(listener));
+  CheckAndClearJniExceptions(env);
+  return result;
+}
+
 /* static */
 bool EventListenerInternal::InitializeEmbeddedClasses(
     App* app, const std::vector<internal::EmbeddedFile>* embedded_files) {
@@ -123,6 +154,10 @@ bool EventListenerInternal::InitializeEmbeddedClasses(
        "FirebaseFirestoreException;)V",
        reinterpret_cast<void*>(
            &EventListenerInternal::QueryEventListenerNativeOnEvent)}};
+  static const JNINativeMethod kVoidEventListenerNatives[] = {
+      {"nativeOnEvent", "(J)V",
+       reinterpret_cast<void*>(
+           &EventListenerInternal::VoidEventListenerNativeOnEvent)}};
 
   JNIEnv* env = app->GetJNIEnv();
   jobject activity = app->activity();
@@ -133,17 +168,22 @@ bool EventListenerInternal::InitializeEmbeddedClasses(
                                                    embedded_files) &&
       query_event_listener::CacheClassFromFiles(env, activity,
                                                 embedded_files) &&
+      void_event_listener::CacheClassFromFiles(env, activity, embedded_files) &&
       // Cache method-ids
       cpp_event_listener::CacheMethodIds(env, activity) &&
       document_event_listener::CacheMethodIds(env, activity) &&
       query_event_listener::CacheMethodIds(env, activity) &&
+      void_event_listener::CacheMethodIds(env, activity) &&
       // Register natives
       document_event_listener::RegisterNatives(
           env, kDocumentEventListenerNatives,
           FIREBASE_ARRAYSIZE(kDocumentEventListenerNatives)) &&
       query_event_listener::RegisterNatives(
           env, kQueryEventListenerNatives,
-          FIREBASE_ARRAYSIZE(kQueryEventListenerNatives));
+          FIREBASE_ARRAYSIZE(kQueryEventListenerNatives)) &&
+      void_event_listener::RegisterNatives(
+          env, kVoidEventListenerNatives,
+          FIREBASE_ARRAYSIZE(kVoidEventListenerNatives));
   util::CheckAndClearJniExceptions(env);
   return result;
 }
@@ -155,6 +195,7 @@ void EventListenerInternal::Terminate(App* app) {
   cpp_event_listener::ReleaseClass(env);
   document_event_listener::ReleaseClass(env);
   query_event_listener::ReleaseClass(env);
+  void_event_listener::ReleaseClass(env);
   util::CheckAndClearJniExceptions(env);
 }
 

firestore/src/android/event_listener_android.h

@@ -21,6 +21,8 @@ class EventListenerInternal {
                                               jlong firestore_ptr,
                                               jlong listener_ptr, jobject value,
                                               jobject error);
+  static void VoidEventListenerNativeOnEvent(JNIEnv* env, jclass clazz,
+                                             jlong listener_ptr);
 
   static jobject EventListenerToJavaEventListener(
       JNIEnv* env, FirestoreInternal* firestore,
@@ -30,6 +32,9 @@ class EventListenerInternal {
       JNIEnv* env, FirestoreInternal* firestore,
       EventListener<QuerySnapshot>* listener);
 
+  static jobject EventListenerToJavaRunnable(JNIEnv* env,
+                                             EventListener<void>* listener);
+
  private:
   friend class FirestoreInternal;
 

firestore/src/android/firestore_android.cc

@@ -22,6 +22,7 @@
 #include "firestore/src/android/firebase_firestore_exception_android.h"
 #include "firestore/src/android/firebase_firestore_settings_android.h"
 #include "firestore/src/android/geo_point_android.h"
+#include "firestore/src/android/lambda_event_listener.h"
 #include "firestore/src/android/lambda_transaction_function.h"
 #include "firestore/src/android/metadata_changes_android.h"
 #include "firestore/src/android/promise_android.h"
@@ -78,7 +79,11 @@ const char kApiIdentifier[] = "Firestore";
   X(WaitForPendingWrites, "waitForPendingWrites",                       \
     "()Lcom/google/android/gms/tasks/Task;"),                           \
   X(ClearPersistence, "clearPersistence",                               \
-    "()Lcom/google/android/gms/tasks/Task;")
+    "()Lcom/google/android/gms/tasks/Task;"),                           \
+  X(AddSnapshotsInSyncListener, "addSnapshotsInSyncListener",           \
+    "(Ljava/lang/Runnable;)"                                            \
+    "Lcom/google/firebase/firestore/ListenerRegistration;")
+
 // clang-format on
 
 METHOD_LOOKUP_DECLARATION(firebase_firestore, FIREBASE_FIRESTORE_METHODS)
@@ -463,6 +468,41 @@ Future<void> FirestoreInternal::ClearPersistenceLastResult() {
   return LastResult(FirestoreFn::kClearPersistence);
 }
 
+ListenerRegistration FirestoreInternal::AddSnapshotsInSyncListener(
+    EventListener<void>* listener, bool passing_listener_ownership) {
+  JNIEnv* env = app_->GetJNIEnv();
+
+  // Create listener.
+  jobject java_runnable =
+      EventListenerInternal::EventListenerToJavaRunnable(env, listener);
+
+  // Register listener.
+  jobject java_registration = env->CallObjectMethod(
+      obj_,
+      firebase_firestore::GetMethodId(
+          firebase_firestore::kAddSnapshotsInSyncListener),
+      java_runnable);
+  env->DeleteLocalRef(java_runnable);
+  CheckAndClearJniExceptions(env);
+
+  // Wrapping
+  ListenerRegistrationInternal* registration = new ListenerRegistrationInternal{
+      this, listener, passing_listener_ownership, java_registration};
+  env->DeleteLocalRef(java_registration);
+  return ListenerRegistration{registration};
+}
+
+#if defined(FIREBASE_USE_STD_FUNCTION)
+
+ListenerRegistration FirestoreInternal::AddSnapshotsInSyncListener(
+    std::function<void()> callback) {
+  auto* listener = new LambdaEventListener<void>(firebase::Move(callback));
+  return AddSnapshotsInSyncListener(listener,
+                                    /*passing_listener_ownership=*/true);
+}
+
+#endif  // defined(FIREBASE_USE_STD_FUNCTION)
+
 void FirestoreInternal::RegisterListenerRegistration(
     ListenerRegistrationInternal* registration) {
   MutexLock lock(listener_registration_mutex_);

firestore/src/android/firestore_android.h

@@ -6,6 +6,10 @@
 #include <cstdint>
 #include <unordered_set>
 
+#if defined(FIREBASE_USE_STD_FUNCTION)
+#include <functional>
+#endif
+
 #include "app/src/cleanup_notifier.h"
 #include "app/src/future_manager.h"
 #include "app/src/include/firebase/app.h"
@@ -106,6 +110,14 @@ class FirestoreInternal {
   Future<void> ClearPersistence();
   Future<void> ClearPersistenceLastResult();
 
+  ListenerRegistration AddSnapshotsInSyncListener(
+      EventListener<void>* listener, bool passing_listener_ownership = false);
+
+#if defined(FIREBASE_USE_STD_FUNCTION)
+  ListenerRegistration AddSnapshotsInSyncListener(
+      std::function<void()> callback);
+#endif  // defined(FIREBASE_USE_STD_FUNCTION)
+
   // Manages the ListenerRegistrationInternal objects.
   void RegisterListenerRegistration(ListenerRegistrationInternal* registration);
   void UnregisterListenerRegistration(

firestore/src/android/lambda_event_listener.h

@@ -19,7 +19,9 @@ template <typename T>
 class LambdaEventListener : public EventListener<T> {
  public:
   LambdaEventListener(std::function<void(const T&, Error)> callback)
-      : callback_(firebase::Move(callback)) {}
+      : callback_(firebase::Move(callback)) {
+    FIREBASE_ASSERT(callback);
+  }
 
   void OnEvent(const T& value, Error error) override {
     callback_(value, error);
@@ -29,6 +31,20 @@ class LambdaEventListener : public EventListener<T> {
   std::function<void(const T&, Error)> callback_;
 };
 
+template <>
+class LambdaEventListener<void> : public EventListener<void> {
+ public:
+  LambdaEventListener(std::function<void()> callback)
+      : callback_(firebase::Move(callback)) {
+    FIREBASE_ASSERT(callback);
+  }
+
+  void OnEvent(Error) override { callback_(); }
+
+ private:
+  std::function<void()> callback_;
+};
+
 }  // namespace firestore
 }  // namespace firebase
 

firestore/src/android/listener_registration_android.cc

@@ -45,6 +45,21 @@ ListenerRegistrationInternal::ListenerRegistrationInternal(
   firestore->RegisterListenerRegistration(this);
 }
 
+ListenerRegistrationInternal::ListenerRegistrationInternal(
+    FirestoreInternal* firestore, EventListener<void>* event_listener,
+    bool owning_event_listener, jobject listener_registration)
+    : firestore_(firestore),
+      listener_registration_(
+          firestore->app()->GetJNIEnv()->NewGlobalRef(listener_registration)),
+      void_event_listener_(event_listener),
+      owning_event_listener_(owning_event_listener) {
+  FIREBASE_ASSERT(firestore != nullptr);
+  FIREBASE_ASSERT(event_listener != nullptr);
+  FIREBASE_ASSERT(listener_registration != nullptr);
+
+  firestore->RegisterListenerRegistration(this);
+}
+
 // Destruction only happens when FirestoreInternal de-allocate them.
 // FirestoreInternal will hold the lock and unregister all of them. So we do not
 // call UnregisterListenerRegistration explicitly here.
@@ -66,6 +81,7 @@ ListenerRegistrationInternal::~ListenerRegistrationInternal() {
   if (owning_event_listener_) {
     delete document_event_listener_;
     delete query_event_listener_;
+    delete void_event_listener_;
   }
 }
 

firestore/src/android/listener_registration_android.h

@@ -33,6 +33,10 @@ class ListenerRegistrationInternal {
                                EventListener<QuerySnapshot>* event_listener,
                                bool owning_event_listener,
                                jobject listener_registration);
+  ListenerRegistrationInternal(FirestoreInternal* firestore,
+                               EventListener<void>* event_listener,
+                               bool owning_event_listener,
+                               jobject listener_registration);
 
   // Delete the default one to make the ownership more obvious i.e.
   // FirestoreInternal owns each instance and forbid anyone else to make copy.
@@ -66,6 +70,7 @@ class ListenerRegistrationInternal {
   // then the registration owns the LambdaEventListener that wraps the lambda.
   EventListener<DocumentSnapshot>* document_event_listener_ = nullptr;
   EventListener<QuerySnapshot>* query_event_listener_ = nullptr;
+  EventListener<void>* void_event_listener_ = nullptr;
   bool owning_event_listener_;
 };
 

firestore/src/common/firestore.cc

@@ -286,5 +286,21 @@ Future<void> Firestore::ClearPersistenceLastResult() {
   return internal_->ClearPersistenceLastResult();
 }
 
+#if !defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+ListenerRegistration Firestore::AddSnapshotsInSyncListener(
+    EventListener<void>* listener) {
+  if (!internal_) return {};
+  return internal_->AddSnapshotsInSyncListener(listener);
+}
+#endif  // !defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+
+#if defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+ListenerRegistration Firestore::AddSnapshotsInSyncListener(
+    std::function<void()> callback) {
+  if (!internal_) return {};
+  return internal_->AddSnapshotsInSyncListener(std::move(callback));
+}
+#endif  // defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+
 }  // namespace firestore
 }  // namespace firebase

firestore/src/include/firebase/firestore.h

@@ -337,6 +337,50 @@ class Firestore {
   /** Gets the result of the most recent call to ClearPersistence(). */
   Future<void> ClearPersistenceLastResult();
 
+#if defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+  /**
+   * Attaches a listener for a snapshots-in-sync event. Server-generated
+   * updates and local changes can affect multiple snapshot listeners.
+   * The snapshots-in-sync event indicates that all listeners affected by
+   * a given change have fired.
+   *
+   * NOTE: The snapshots-in-sync event only indicates that listeners are
+   * in sync with each other, but does not relate to whether those
+   * snapshots are in sync with the server. Use `SnapshotMetadata` in the
+   * individual listeners to determine if a snapshot is from the cache or
+   * the server.
+   *
+   * @param callback A callback to be called every time all snapshot
+   * listeners are in sync with each other.
+   * @return A `ListenerRegistration` object that can be used to remove the
+   * listener.
+   */
+  virtual ListenerRegistration AddSnapshotsInSyncListener(
+      std::function<void()> callback);
+#endif  // defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+
+#if !defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+  /**
+   * Attaches a listener for a snapshots-in-sync event. Server-generated
+   * updates and local changes can affect multiple snapshot listeners.
+   * The snapshots-in-sync event indicates that all listeners affected by
+   * a given change have fired.
+   *
+   * NOTE: The snapshots-in-sync event only indicates that listeners are
+   * in sync with each other, but does not relate to whether those
+   * snapshots are in sync with the server. Use `SnapshotMetadata` in the
+   * individual listeners to determine if a snapshot is from the cache or
+   * the server.
+   *
+   * @param listener A callback to be called every time all snapshot
+   * listeners are in sync with each other.
+   * @return A `ListenerRegistration` object that can be used to remove the
+   * listener.
+   */
+  virtual ListenerRegistration AddSnapshotsInSyncListener(
+      EventListener<void>* listener);
+#endif  // !defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+
  protected:
   /**
    * Default constructor, to be used only for mocking `Firestore`.

firestore/src/include/firebase/firestore/event_listener.h

@@ -40,6 +40,13 @@ class EventListener {
   virtual void OnEvent(const T& value, Error error) = 0;
 };
 
+template <>
+class EventListener<void> {
+ public:
+  virtual ~EventListener() = default;
+  virtual void OnEvent(Error error) = 0;
+};
+
 }  // namespace firestore
 }  // namespace firebase