Un-hide EmulatorSettings API (#1712)

Author: samtstern

firebase-common/api.txt

@@ -2,8 +2,10 @@
 package com.google.firebase {
 
   public class FirebaseApp {
+    method public void enableEmulators(@NonNull com.google.firebase.emulators.EmulatorSettings);
     method @NonNull public android.content.Context getApplicationContext();
     method @NonNull public static java.util.List<com.google.firebase.FirebaseApp> getApps(@NonNull android.content.Context);
+    method @NonNull public com.google.firebase.emulators.EmulatorSettings getEmulatorSettings();
     method @NonNull public static com.google.firebase.FirebaseApp getInstance();
     method @NonNull public static com.google.firebase.FirebaseApp getInstance(@NonNull String);
     method @NonNull public String getName();
@@ -47,6 +49,30 @@ package com.google.firebase {
 
 }
 
+package com.google.firebase.emulators {
+
+  public final class EmulatedServiceSettings {
+    ctor public EmulatedServiceSettings(@NonNull String, int);
+    method @NonNull public String getHost();
+    method public int getPort();
+  }
+
+  public final class EmulatorSettings {
+    field public static final com.google.firebase.emulators.EmulatorSettings DEFAULT;
+  }
+
+  public static final class EmulatorSettings.Builder {
+    ctor public EmulatorSettings.Builder();
+    method @NonNull public com.google.firebase.emulators.EmulatorSettings.Builder addEmulatedService(@NonNull com.google.firebase.emulators.FirebaseEmulator, @NonNull com.google.firebase.emulators.EmulatedServiceSettings);
+    method @NonNull public com.google.firebase.emulators.EmulatorSettings build();
+  }
+
+  public final class FirebaseEmulator {
+    method @NonNull public String getName();
+  }
+
+}
+
 package com.google.firebase.provider {
 
   public class FirebaseInitProvider extends android.content.ContentProvider {

firebase-common/gradle.properties

@@ -1,3 +1,3 @@
-version=19.3.1
+version=19.4.0
 latestReleasedVersion=19.3.0
 android.enableUnitTestBinaryResources=true

firebase-common/src/main/java/com/google/firebase/FirebaseApp.java

@@ -149,9 +149,8 @@ public FirebaseOptions getOptions() {
   /**
    * Returns the specified {@link EmulatorSettings} or a default.
    *
-   * <p>TODO(samstern): Un-hide this once Firestore, Database, and Functions are implemented
-   *
-   * @hide
+   * <p>Calling this method "freezes" the emulator settings and future calls to enableEmulators on
+   * the same FirebaseApp instance will fail.
    */
   @NonNull
   public EmulatorSettings getEmulatorSettings() {
@@ -330,10 +329,7 @@ public static FirebaseApp initializeApp(
    * com.google.firebase.emulators.EmulatedServiceSettings} for {@link FirebaseDatabase#EMULATOR},
    * then calls to Cloud Firestore will communicate with the emulator rather than production.
    *
-   * <p>TODO(samstern): Un-hide this once Firestore, Database, and Functions are implemented
-   *
    * @param emulatorSettings the emulator settings for all services.
-   * @hide
    */
   public void enableEmulators(@NonNull EmulatorSettings emulatorSettings) {
     checkNotDeleted();

firebase-common/src/main/java/com/google/firebase/emulators/EmulatedServiceSettings.java

@@ -19,10 +19,7 @@
 /**
  * Settings to connect a single Firebase service to a local emulator.
  *
- * <p>TODO(samstern): Un-hide this once Firestore, Database, and Functions are implemented
- *
  * @see EmulatorSettings
- * @hide
  */
 public final class EmulatedServiceSettings {
 
@@ -34,6 +31,7 @@ public EmulatedServiceSettings(@NonNull String host, int port) {
     this.port = port;
   }
 
+  @NonNull
   public String getHost() {
     return host;
   }

firebase-common/src/main/java/com/google/firebase/emulators/EmulatorSettings.java

@@ -25,10 +25,7 @@
  * Settings that control which Firebase services should access a local emulator, rather than
  * production.
  *
- * <p>TODO(samstern): Un-hide this once Firestore, Database, and Functions are implemented
- *
  * @see com.google.firebase.FirebaseApp#enableEmulators(EmulatorSettings)
- * @hide
  */
 public final class EmulatorSettings {
 

firebase-common/src/main/java/com/google/firebase/emulators/FirebaseEmulator.java

@@ -19,12 +19,9 @@
 /**
  * Identifier Firebase services that can be emulated using the Firebase Emulator Suite.
  *
- * <p>TODO(samstern): Un-hide this once Firestore, Database, and Functions are implemented
- *
  * @see com.google.firebase.FirebaseApp#enableEmulators(EmulatorSettings)
  * @see EmulatorSettings
  * @see EmulatedServiceSettings
- * @hide
  */
 public final class FirebaseEmulator {
 
@@ -36,14 +33,15 @@ public final class FirebaseEmulator {
    * @hide
    */
   @NonNull
-  public static FirebaseEmulator forName(String name) {
+  public static FirebaseEmulator forName(@NonNull String name) {
     return new FirebaseEmulator(name);
   }
 
-  private FirebaseEmulator(String name) {
+  private FirebaseEmulator(@NonNull String name) {
     this.name = name;
   }
 
+  @NonNull
   public String getName() {
     return name;
   }

firebase-database/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Unreleased
 
 - [changed] Added internal HTTP header to the WebChannel connection.
+- [feature] Realtime Database now supports connecting to a local emulator via
+  `FirebaseApp.enableEmulators()`
 
 # 19.3.0
 - [feature] Added ServerValue.increment() to support atomic field value increments

firebase-database/api.txt

@@ -96,6 +96,7 @@ package com.google.firebase.database {
     method public void setLogLevel(@NonNull com.google.firebase.database.Logger.Level);
     method public void setPersistenceCacheSizeBytes(long);
     method public void setPersistenceEnabled(boolean);
+    field @NonNull public static final com.google.firebase.emulators.FirebaseEmulator EMULATOR;
   }
 
   public abstract class GenericTypeIndicator<T> {

firebase-database/gradle.properties

@@ -12,6 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-version=19.3.1
+version=19.4.0
 latestReleasedVersion=19.3.0
 android.enableUnitTestBinaryResources=true

firebase-database/src/main/java/com/google/firebase/database/FirebaseDatabase.java

@@ -40,14 +40,8 @@
  */
 public class FirebaseDatabase {
 
-  /**
-   * Emulator identifier. See {@link FirebaseApp#enableEmulators(EmulatorSettings)}
-   *
-   * <p>TODO(samstern): Un-hide this once Firestore, Database, and Functions are implemented
-   *
-   * @hide
-   */
-  public static final FirebaseEmulator EMULATOR = FirebaseEmulator.forName("database");
+  /** Emulator identifier. See {@link FirebaseApp#enableEmulators(EmulatorSettings)} */
+  @NonNull public static final FirebaseEmulator EMULATOR = FirebaseEmulator.forName("database");
 
   private static final String SDK_VERSION = BuildConfig.VERSION_NAME;
 

firebase-firestore/CHANGELOG.md

@@ -4,6 +4,8 @@
   the app was in the background.
 - [fixed] Fixed an issue that may have prevented the client from connecting
   to the backend immediately after a user signed in.
+- [feature] Firestore now supports connecting to a local emulator via
+  `FirebaseApp.enableEmulators()`.
 
 # 21.4.3
 - [changed] Firestore now limits the number of concurrent document lookups it

firebase-firestore/api.txt

@@ -152,6 +152,7 @@ package com.google.firebase.firestore {
     method public static void setLoggingEnabled(boolean);
     method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> terminate();
     method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> waitForPendingWrites();
+    field @NonNull public static final com.google.firebase.emulators.FirebaseEmulator EMULATOR;
   }
 
   public class FirebaseFirestoreException extends com.google.firebase.FirebaseException {

firebase-firestore/gradle.properties

@@ -1,2 +1,2 @@
-version=21.4.4
+version=21.5.0
 latestReleasedVersion=21.4.3

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

@@ -58,14 +58,8 @@
  */
 public class FirebaseFirestore {
 
-  /**
-   * Emulator identifier. See {@link FirebaseApp#enableEmulators(EmulatorSettings)}
-   *
-   * <p>TODO(samstern): Un-hide this once Firestore, Database, and Functions are implemented
-   *
-   * @hide
-   */
-  public static FirebaseEmulator EMULATOR = FirebaseEmulator.forName("firestore");
+  /** Emulator identifier. See {@link FirebaseApp#enableEmulators(EmulatorSettings)} */
+  @NonNull public static final FirebaseEmulator EMULATOR = FirebaseEmulator.forName("firestore");
 
   /**
    * Provides a registry management interface for {@code FirebaseFirestore} instances.

firebase-functions/api.txt

@@ -7,7 +7,8 @@ package com.google.firebase.functions {
     method @NonNull public static com.google.firebase.functions.FirebaseFunctions getInstance(@NonNull com.google.firebase.FirebaseApp);
     method @NonNull public static com.google.firebase.functions.FirebaseFunctions getInstance(@NonNull String);
     method @NonNull public static com.google.firebase.functions.FirebaseFunctions getInstance();
-    method public void useFunctionsEmulator(@NonNull String);
+    method @Deprecated public void useFunctionsEmulator(@NonNull String);
+    field @NonNull public static final com.google.firebase.emulators.FirebaseEmulator EMULATOR;
   }
 
   public class FirebaseFunctionsException extends com.google.firebase.FirebaseException {

firebase-functions/gradle.properties

@@ -1,3 +1,3 @@
-version=19.0.3
+version=19.1.0
 latestReleasedVersion=19.0.2
 android.enableUnitTestBinaryResources=true

firebase-functions/src/main/java/com/google/firebase/functions/FirebaseFunctions.java

@@ -28,6 +28,7 @@
 import com.google.android.gms.tasks.Tasks;
 import com.google.firebase.FirebaseApp;
 import com.google.firebase.emulators.EmulatedServiceSettings;
+import com.google.firebase.emulators.EmulatorSettings;
 import com.google.firebase.emulators.FirebaseEmulator;
 import com.google.firebase.functions.FirebaseFunctionsException.Code;
 import java.io.IOException;
@@ -49,16 +50,8 @@
 /** FirebaseFunctions lets you call Cloud Functions for Firebase. */
 public class FirebaseFunctions {
 
-  /**
-   * Emulator identifier, see {@link
-   * com.google.firebase.emulators.EmulatorSettings.Builder#addEmulatedService(FirebaseEmulator,
-   * EmulatedServiceSettings)}
-   *
-   * <p>TODO(samstern): Un-hide this once Firestore, Database, and Functions are implemented
-   *
-   * @hide
-   */
-  public static final FirebaseEmulator EMULATOR = FirebaseEmulator.forName("functions");
+  /** Emulator identifier. See {@link FirebaseApp#enableEmulators(EmulatorSettings)} */
+  @NonNull public static final FirebaseEmulator EMULATOR = FirebaseEmulator.forName("functions");
 
   /** A task that will be resolved once ProviderInstaller has installed what it needs to. */
   private static final TaskCompletionSource<Void> providerInstalled = new TaskCompletionSource<>();
@@ -218,7 +211,9 @@ URL getURL(String function) {
    * https://firebase.google.com/docs/functions/local-emulator
    *
    * @param origin The origin of the local emulator, such as "http://10.0.2.2:5005".
+   * @deprecated use {@link FirebaseApp#enableEmulators(EmulatorSettings)}.
    */
+  @Deprecated
   public void useFunctionsEmulator(@NonNull String origin) {
     Preconditions.checkNotNull(origin, "origin cannot be null");
     urlFormat = origin + "/%2$s/%1$s/%3$s";