Make indexing public (#3476)

Author: schmidt-sebastian

firebase-annotations/src/main/java/com/google/firebase/annotations/PreviewApi.java

@@ -0,0 +1,26 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.firebase.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates that this object (class, method, etc) is experimental and that both its signature and
+ * implementation are subject to change. An API marked with this annotation provides no guarantee of
+ * API stability or backward-compatibility.
+ */
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
+public @interface PreviewApi {}

firebase-firestore/CHANGELOG.md

@@ -2,13 +2,20 @@ Android changes are not released automatically. Ensure that changes are released
 by opting into a release at 
 [go/firebase-android-release](http:go/firebase-android-release) (Googlers only).
 
+# Unreleased
+- [feature] Added experimental support for indexed query execution. Indexes can
+  be enabled by invoking `FirebaseFirestore.setIndexConfiguration()` with the
+  JSON index definition exported by the Firestore CLI. Queries against the
+  cache are executed using an index once the asynchronous operation to generate
+  the index entries completes.
+
 # 24.0.2
 - [fixed] Fixed an issue of long grpc reconnection period, when App moves to
   foreground after staying in background for a while.
 - [fixed] Fixed an AppCheck issue that caused Firestore listeners to stop
   working and receive a "Permission Denied" error. This issue only occurred for
   AppCheck users that set their expiration time to under an hour.
-- [fixed] Fixed a potential problem during Firestore's shutdown that prevented 
+- [fixed] Fixed a potential problem during Firestore's shutdown that prevented
   the shutdown from proceeding if a network connection was opened right before.
 - [changed] Queries are now send to the backend before the SDK starts local 
   processing, which reduces overall Query latency.

firebase-firestore/api.txt

@@ -153,6 +153,7 @@ package com.google.firebase.firestore {
     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);
+    method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> setIndexConfiguration(@NonNull String);
     method public static void setLoggingEnabled(boolean);
     method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> terminate();
     method public void useEmulator(@NonNull String, int);

firebase-firestore/firebase-firestore.gradle

@@ -123,6 +123,7 @@ googleJavaFormat {
 }
 
 dependencies {
+    implementation project(':firebase-annotations')
     implementation project(':firebase-common')
     implementation project(':protolite-well-known-types')
     implementation project(':firebase-database-collection')

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

@@ -27,6 +27,7 @@
 import com.google.android.gms.tasks.TaskCompletionSource;
 import com.google.android.gms.tasks.Tasks;
 import com.google.firebase.FirebaseApp;
+import com.google.firebase.annotations.PreviewApi;
 import com.google.firebase.appcheck.interop.InternalAppCheckTokenProvider;
 import com.google.firebase.auth.internal.InternalAuthProvider;
 import com.google.firebase.emulators.EmulatedServiceSettings;
@@ -304,8 +305,9 @@ public FirebaseApp getApp() {
    * @return A task that resolves once all indices are successfully configured.
    * @throws IllegalArgumentException if the JSON format is invalid
    */
-  @VisibleForTesting
-  Task<Void> setIndexConfiguration(String json) {
+  @PreviewApi
+  @NonNull
+  public Task<Void> setIndexConfiguration(@NonNull String json) {
     ensureClientConfigured();
     Preconditions.checkState(
         settings.isPersistenceEnabled(), "Cannot enable indexes when persistence is disabled");