Prepare shutdown to be a public api.

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/FirestoreTest.java

@@ -20,6 +20,7 @@
 import static com.google.firebase.firestore.testutil.IntegrationTestUtil.testCollection;
 import static com.google.firebase.firestore.testutil.IntegrationTestUtil.testCollectionWithDocs;
 import static com.google.firebase.firestore.testutil.IntegrationTestUtil.testDocument;
+import static com.google.firebase.firestore.testutil.IntegrationTestUtil.testFirebaseApp;
 import static com.google.firebase.firestore.testutil.IntegrationTestUtil.testFirestore;
 import static com.google.firebase.firestore.testutil.IntegrationTestUtil.waitFor;
 import static com.google.firebase.firestore.testutil.IntegrationTestUtil.waitForException;
@@ -30,6 +31,7 @@
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotEquals;
 import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNotSame;
 import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertSame;
 import static org.junit.Assert.assertTrue;
@@ -38,6 +40,7 @@
 import androidx.test.ext.junit.runners.AndroidJUnit4;
 import com.google.android.gms.tasks.Task;
 import com.google.android.gms.tasks.TaskCompletionSource;
+import com.google.firebase.FirebaseApp;
 import com.google.firebase.Timestamp;
 import com.google.firebase.firestore.FirebaseFirestoreException.Code;
 import com.google.firebase.firestore.Query.Direction;
@@ -1023,4 +1026,58 @@ public void testClearPersistenceWhileRunningFails() {
     FirebaseFirestoreException firestoreException = (FirebaseFirestoreException) e;
     assertEquals(Code.FAILED_PRECONDITION, firestoreException.getCode());
   }
+
+  @Test
+  public void testRestartFirestoreLeadsToNewInstance() {
+    FirebaseApp app = testFirebaseApp();
+    FirebaseFirestore instance = FirebaseFirestore.getInstance(app);
+    FirebaseFirestore sameInstance = FirebaseFirestore.getInstance(app);
+
+    assertSame(instance, sameInstance);
+    waitFor(instance.document("abc/123").set(Collections.singletonMap("field", 100L)));
+
+    instance.shutdown();
+    FirebaseFirestore newInstance = FirebaseFirestore.getInstance(app);
+
+    // Verify new instance works.
+    DocumentSnapshot doc = waitFor(newInstance.document("abc/123").get());
+    assertEquals(doc.get("field"), 100L);
+    waitFor(newInstance.document("abc/123").delete());
+
+    // Verify it is different instance.
+    assertNotSame(instance, newInstance);
+  }
+
+  @Test
+  public void testAppDeleteLeadsToFirestoreShutdown() {
+    FirebaseApp app = testFirebaseApp();
+    FirebaseFirestore instance = FirebaseFirestore.getInstance(app);
+    waitFor(instance.document("abc/123").set(Collections.singletonMap("Field", 100)));
+
+    app.delete();
+
+    assertTrue(instance.getClient().isShutdown());
+  }
+
+  @Test
+  public void testNewOperationThrowsAfterFirestoreShutdown() {
+    FirebaseFirestore instance = testFirestore();
+    final DocumentReference reference = instance.document("abc/123");
+    DocumentReference ref = reference;
+    waitFor(reference.set(Collections.singletonMap("Field", 100)));
+
+    instance.shutdown();
+
+    final String expectedMessage = "The client has already been shutdown";
+    expectError(() -> waitFor(reference.get()), expectedMessage);
+    expectError(() -> waitFor(reference.update("Field", 1)), expectedMessage);
+    expectError(
+        () -> waitFor(reference.set(Collections.singletonMap("Field", 1))), expectedMessage);
+    expectError(
+        () -> waitFor(instance.runBatch((batch) -> batch.update(reference, "Field", 1))),
+        expectedMessage);
+    expectError(
+        () -> waitFor(instance.runTransaction(transaction -> transaction.get(reference))),
+        expectedMessage);
+  }
 }

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/testutil/IntegrationTestUtil.java

@@ -25,6 +25,7 @@
 import com.google.android.gms.tasks.Task;
 import com.google.android.gms.tasks.TaskCompletionSource;
 import com.google.android.gms.tasks.Tasks;
+import com.google.firebase.FirebaseApp;
 import com.google.firebase.firestore.AccessHelper;
 import com.google.firebase.firestore.BuildConfig;
 import com.google.firebase.firestore.CollectionReference;
@@ -145,6 +146,10 @@ protected String checkAuthority(String authority) {
     return settings.build();
   }
 
+  public static FirebaseApp testFirebaseApp() {
+    return FirebaseApp.initializeApp(ApplicationProvider.getApplicationContext());
+  }
+
   /** Initializes a new Firestore instance that uses the default project. */
   public static FirebaseFirestore testFirestore() {
     return testFirestore(newTestSettings());

firebase-firestore/src/main/java/com/google/firebase/firestore/FirebaseFirestore.java

@@ -117,7 +117,13 @@ static FirebaseFirestore newInstance(
     // so there is no need to include it in the persistence key.
     String persistenceKey = app.getName();
 
-    return new FirebaseFirestore(context, databaseId, persistenceKey, provider, queue, app);
+    FirebaseFirestore firestore =
+        new FirebaseFirestore(context, databaseId, persistenceKey, provider, queue, app);
+    app.addLifecycleEventListener(
+        /* onDeleted */ (firebaseAppName, options) -> {
+          firestore.shutdown(/* fromAppDeletion */ true);
+        });
+    return firestore;
   }
 
   @VisibleForTesting
@@ -329,13 +335,43 @@ public Task<Void> runBatch(@NonNull WriteBatch.Function batchFunction) {
     return batch.commit();
   }
 
-  @VisibleForTesting
-  Task<Void> shutdown() {
+  Task<Void> shutdown(boolean fromAppDeletion) {
+    if (!fromAppDeletion && this.getApp() != null) {
+      FirestoreMultiDbComponent component = this.getApp().get(FirestoreMultiDbComponent.class);
+      component.remove(this.databaseId.getDatabaseId());
+    }
     // The client must be initialized to ensure that all subsequent API usage throws an exception.
     this.ensureClientConfigured();
     return client.shutdown();
   }
 
+  /**
+   * Shuts down this Firestore SDK instance.
+   *
+   * <p>IMPORTANT: If your application is designed to run with Firestore the entire life cycle, it
+   * is not recommended to call `shutdown` explicitly, the shutting down happens naturally when the
+   * application itself is shut down.
+   *
+   * <p>For applications designed to run without Firestore from some point on (typically to save
+   * resources as much as possible), you may call this method.
+   *
+   * <p>Once `shutdown` is called, trying to issue new reads/writes through this instance will
+   * result in {@link IllegalStateException}. Already requested reads/writes might stop resolving.
+   * Be sure to handle this well in your application if proceeding with Firestore shutting down is
+   * desired in your case.
+   *
+   * <p>Note that {@link #clearPersistence()} is an exception, it is designed to run when the
+   * Firestore SDK instance is shutdown.
+   *
+   * <p>To re-start a Firestore SDK instance, simply create a new instance via {@link
+   * #getInstance()} or {@link #getInstance(FirebaseApp)}.
+   */
+  @VisibleForTesting
+  // TODO: Make this public and remove @VisibleForTesting
+  Task<Void> shutdown() {
+    return shutdown(/* fromAppDeletion */ false);
+  }
+
   @VisibleForTesting
   AsyncQueue getAsyncQueue() {
     return asyncQueue;
@@ -396,7 +432,7 @@ public static void setLoggingEnabled(boolean loggingEnabled) {
   @PublicApi
   public Task<Void> clearPersistence() {
     final TaskCompletionSource<Void> source = new TaskCompletionSource<>();
-    asyncQueue.enqueueAndForget(
+    asyncQueue.enqueueAndForgetEvenAfterShutdown(
         () -> {
           try {
             if (client != null && !client.isShutdown()) {

firebase-firestore/src/main/java/com/google/firebase/firestore/FirestoreMultiDbComponent.java

@@ -45,12 +45,23 @@ class FirestoreMultiDbComponent {
 
   /** Provides instances of Firestore for given database names. */
   @NonNull
-  synchronized FirebaseFirestore get(@NonNull String databaseName) {
-    FirebaseFirestore firestore = instances.get(databaseName);
+  synchronized FirebaseFirestore get(@NonNull String databaseId) {
+    FirebaseFirestore firestore = instances.get(databaseId);
     if (firestore == null) {
-      firestore = FirebaseFirestore.newInstance(context, app, authProvider, databaseName);
-      instances.put(databaseName, firestore);
+      firestore = FirebaseFirestore.newInstance(context, app, authProvider, databaseId);
+      instances.put(databaseId, firestore);
     }
     return firestore;
   }
+
+  /**
+   * Remove the instance of a given database name from this component, such that if {@link
+   * FirestoreMultiDbComponent#get(String)} is called again with the same name, a new instance of
+   * {@link FirebaseFirestore} is created.
+   *
+   * <p>It is a no-op if there is no instance associated with the given database name.
+   */
+  synchronized void remove(@NonNull String databaseId) {
+    instances.remove(databaseId);
+  }
 }

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

@@ -75,7 +75,6 @@ public final class FirestoreClient implements RemoteStore.RemoteStoreCallback {
   private RemoteStore remoteStore;
   private SyncEngine syncEngine;
   private EventManager eventManager;
-  private volatile boolean clientShutdown = false;
 
   // LRU-related
   @Nullable private LruGarbageCollector.Scheduler lruScheduler;
@@ -138,21 +137,21 @@ public Task<Void> enableNetwork() {
   /** Shuts down this client, cancels all writes / listeners, and releases all resources. */
   public Task<Void> shutdown() {
     credentialsProvider.removeChangeListener();
-    return asyncQueue.enqueue(
+    return asyncQueue.enqueueAndInitiateShutdown(
         () -> {
-          if (!this.clientShutdown) {
-            remoteStore.shutdown();
-            persistence.shutdown();
-            if (lruScheduler != null) {
-              lruScheduler.stop();
-            }
-            this.clientShutdown = true;
+          remoteStore.shutdown();
+          persistence.shutdown();
+          if (lruScheduler != null) {
+            lruScheduler.stop();
           }
         });
   }
 
+  /** Has this client been shutdown. */
   public boolean isShutdown() {
-    return this.clientShutdown;
+    // Technically, the asyncQueue is still running, but only accepting tasks related to shutdown
+    // or supposed to be run after shutdown. It is effectively shut down to the eyes of users.
+    return this.asyncQueue.isShuttingDown();
   }
 
   /** Starts listening to a query. */
@@ -272,8 +271,8 @@ private void initialize(Context context, User user, boolean usePersistence, long
   }
 
   private void verifyNotShutdown() {
-    if (this.clientShutdown) {
-      throw new IllegalArgumentException("The client has already been shutdown");
+    if (this.isShutdown()) {
+      throw new IllegalStateException("The client has already been shutdown");
     }
   }
 

firebase-firestore/src/main/java/com/google/firebase/firestore/remote/GrpcCallProvider.java

@@ -138,7 +138,7 @@ <ReqT, RespT> Task<ClientCall<ReqT, RespT>> createClientCall(
   /** Shuts down the gRPC channel and the internal worker queue. */
   void shutdown() {
     channelTask.addOnCompleteListener(
-        asyncQueue.getExecutor(),
+        asyncQueue.getExecutorForShutdown(),
         task -> {
           ManagedChannel channel = task.getResult();
           channel.shutdown();