change: New error handling APIs (merging v7 branch into master)

pom.xml

@@ -477,12 +477,6 @@
             <version>0.6</version>
             <scope>test</scope>
         </dependency>
-        <dependency>
-            <groupId>com.cedarsoftware</groupId>
-            <artifactId>java-util</artifactId>
-            <version>1.26.0</version>
-            <scope>test</scope>
-        </dependency>
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>

src/main/java/com/google/firebase/ErrorCode.java

@@ -0,0 +1,109 @@
+/*
+ * Copyright 2020 Google Inc.
+ *
+ * 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;
+
+/**
+ * Platform-wide error codes that can be raised by Admin SDK APIs.
+ */
+public enum ErrorCode {
+
+  /**
+   * Client specified an invalid argument.
+   */
+  INVALID_ARGUMENT,
+
+  /**
+   * Request cannot be executed in the current system state, such as deleting a non-empty
+   * directory.
+   */
+  FAILED_PRECONDITION,
+
+  /**
+   * Client specified an invalid range.
+   */
+  OUT_OF_RANGE,
+
+  /**
+   * Request not authenticated due to missing, invalid, or expired OAuth token.
+   */
+  UNAUTHENTICATED,
+
+  /**
+   * Client does not have sufficient permission. This can happen because the OAuth token does
+   * not have the right scopes, the client doesn't have permission, or the API has not been
+   * enabled for the client project.
+   */
+  PERMISSION_DENIED,
+
+  /**
+   * A specified resource is not found, or the request is rejected for unknown reasons,
+   * such as a blocked network address.
+   */
+  NOT_FOUND,
+
+  /**
+   * Concurrency conflict, such as read-modify-write conflict.
+   */
+  CONFLICT,
+
+  /**
+   * Concurrency conflict, such as read-modify-write conflict.
+   */
+  ABORTED,
+
+  /**
+   * The resource that a client tried to create already exists.
+   */
+  ALREADY_EXISTS,
+
+  /**
+   * Either out of resource quota or rate limited.
+   */
+  RESOURCE_EXHAUSTED,
+
+  /**
+   * Request cancelled by the client.
+   */
+  CANCELLED,
+
+  /**
+   * Unrecoverable data loss or data corruption. The client should report the error to the user.
+   */
+  DATA_LOSS,
+
+  /**
+   * Unknown server error. Typically a server bug.
+   */
+  UNKNOWN,
+
+  /**
+   * Internal server error. Typically a server bug.
+   */
+  INTERNAL,
+
+  /**
+   * Service unavailable. Typically the server is down.
+   */
+  UNAVAILABLE,
+
+  /**
+   * Request deadline exceeded. This happens only if the caller sets a deadline that is
+   * shorter than the method's default deadline (i.e. requested deadline is not enough for the
+   * server to process the request) and the request did not finish within the deadline.
+   */
+  DEADLINE_EXCEEDED,
+}

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

@@ -34,9 +34,7 @@
 import com.google.common.base.Joiner;
 import com.google.common.base.MoreObjects;
 import com.google.common.base.Strings;
-import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableList;
-import com.google.firebase.internal.FirebaseAppStore;
 import com.google.firebase.internal.FirebaseScheduledExecutor;
 import com.google.firebase.internal.FirebaseService;
 import com.google.firebase.internal.ListenableFuture2ApiFuture;
@@ -48,10 +46,8 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
-import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
-import java.util.Set;
 import java.util.concurrent.Callable;
 import java.util.concurrent.Future;
 import java.util.concurrent.ScheduledExecutorService;
@@ -121,7 +117,6 @@ private FirebaseApp(String name, FirebaseOptions options, TokenRefresher.Factory
 
   /** Returns a list of all FirebaseApps. */
   public static List<FirebaseApp> getApps() {
-    // TODO: reenable persistence. See b/28158809.
     synchronized (appsLock) {
       return ImmutableList.copyOf(instances.values());
     }
@@ -221,21 +216,16 @@ public static FirebaseApp initializeApp(FirebaseOptions options, String name) {
 
   static FirebaseApp initializeApp(FirebaseOptions options, String name,
       TokenRefresher.Factory tokenRefresherFactory) {
-    FirebaseAppStore appStore = FirebaseAppStore.initialize();
     String normalizedName = normalize(name);
-    final FirebaseApp firebaseApp;
     synchronized (appsLock) {
       checkState(
           !instances.containsKey(normalizedName),
           "FirebaseApp name " + normalizedName + " already exists!");
 
-      firebaseApp = new FirebaseApp(normalizedName, options, tokenRefresherFactory);
+      FirebaseApp firebaseApp = new FirebaseApp(normalizedName, options, tokenRefresherFactory);
       instances.put(normalizedName, firebaseApp);
+      return firebaseApp;
     }
-
-    appStore.persistApp(firebaseApp);
-
-    return firebaseApp;
   }
 
   @VisibleForTesting
@@ -251,19 +241,13 @@ static void clearInstancesForTest() {
   }
 
   private static List<String> getAllAppNames() {
-    Set<String> allAppNames = new HashSet<>();
+    List<String> allAppNames;
     synchronized (appsLock) {
-      for (FirebaseApp app : instances.values()) {
-        allAppNames.add(app.getName());
-      }
-      FirebaseAppStore appStore = FirebaseAppStore.getInstance();
-      if (appStore != null) {
-        allAppNames.addAll(appStore.getAllPersistedAppNames());
-      }
+      allAppNames = new ArrayList<>(instances.keySet());
     }
-    List<String> sortedNameList = new ArrayList<>(allAppNames);
-    Collections.sort(sortedNameList);
-    return sortedNameList;
+
+    Collections.sort(allAppNames);
+    return ImmutableList.copyOf(allAppNames);
   }
 
   /** Normalizes the app name. */
@@ -359,11 +343,6 @@ public void delete() {
     synchronized (appsLock) {
       instances.remove(name);
     }
-
-    FirebaseAppStore appStore = FirebaseAppStore.getInstance();
-    if (appStore != null) {
-      appStore.removeApp(name);
-    }
   }
 
   private void checkNotDeleted() {
@@ -582,18 +561,17 @@ enum State {
   private static FirebaseOptions getOptionsFromEnvironment() throws IOException {
     String defaultConfig = System.getenv(FIREBASE_CONFIG_ENV_VAR);
     if (Strings.isNullOrEmpty(defaultConfig)) {
-      return new FirebaseOptions.Builder()
+      return FirebaseOptions.builder()
           .setCredentials(APPLICATION_DEFAULT_CREDENTIALS)
           .build();
     }
     JsonFactory jsonFactory = Utils.getDefaultJsonFactory();
-    FirebaseOptions.Builder builder = new FirebaseOptions.Builder();
+    FirebaseOptions.Builder builder = FirebaseOptions.builder();
     JsonParser parser;
     if (defaultConfig.startsWith("{")) {
       parser = jsonFactory.createJsonParser(defaultConfig);
     } else {
-      FileReader reader;
-      reader = new FileReader(defaultConfig);
+      FileReader reader = new FileReader(defaultConfig);
       parser = jsonFactory.createJsonParser(reader);
     }
     parser.parseAndClose(builder);

src/main/java/com/google/firebase/FirebaseAppLifecycleListener.java

@@ -19,7 +19,7 @@
 /** 
  * A listener which gets notified when {@link com.google.firebase.FirebaseApp} gets deleted. 
  */
-// TODO: consider making it public in a future release.
+@Deprecated
 interface FirebaseAppLifecycleListener {
 
   /**

src/main/java/com/google/firebase/FirebaseException.java

@@ -17,24 +17,55 @@
 package com.google.firebase;
 
 import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
 
 import com.google.common.base.Strings;
 import com.google.firebase.internal.NonNull;
+import com.google.firebase.internal.Nullable;
 
-/** Base class for all Firebase exceptions. */
+/**
+ * Base class for all Firebase exceptions.
+ */
 public class FirebaseException extends Exception {
 
-  // TODO(b/27677218): Exceptions should have non-empty messages.
-  @Deprecated
-  protected FirebaseException() {}
+  private final ErrorCode errorCode;
+  private final IncomingHttpResponse httpResponse;
+
+  public FirebaseException(
+      @NonNull ErrorCode errorCode,
+      @NonNull String message,
+      @Nullable Throwable cause,
+      @Nullable IncomingHttpResponse httpResponse) {
+    super(message, cause);
+    checkArgument(!Strings.isNullOrEmpty(message), "Message must not be null or empty");
+    this.errorCode = checkNotNull(errorCode, "ErrorCode must not be null");
+    this.httpResponse = httpResponse;
+  }
+
+  public FirebaseException(
+      @NonNull ErrorCode errorCode,
+      @NonNull String message,
+      @Nullable Throwable cause) {
+    this(errorCode, message, cause, null);
+  }
 
-  public FirebaseException(@NonNull String detailMessage) {
-    super(detailMessage);
-    checkArgument(!Strings.isNullOrEmpty(detailMessage), "Detail message must not be empty");
+  /**
+   * Returns the platform-wide error code associated with this exception.
+   *
+   * @return A Firebase error code.
+   */
+  public final ErrorCode getErrorCode() {
+    return errorCode;
   }
 
-  public FirebaseException(@NonNull String detailMessage, Throwable cause) {
-    super(detailMessage, cause);
-    checkArgument(!Strings.isNullOrEmpty(detailMessage), "Detail message must not be empty");
+  /**
+   * Returns the HTTP response that resulted in this exception. If the exception was not caused by
+   * an HTTP error response, returns null.
+   *
+   * @return An HTTP response or null.
+   */
+  @Nullable
+  public final IncomingHttpResponse getHttpResponse() {
+    return httpResponse;
   }
 }

src/main/java/com/google/firebase/FirebaseOptions.java

@@ -223,6 +223,16 @@ public static Builder builder() {
     return new Builder();
   }
 
+  /**
+   * Creates a new {@code Builder} from the options object.
+   *
+   * <p>The new builder is not backed by this object's values; that is, changes made to the new
+   * builder don't change the values of the origin object.
+   */
+  public Builder toBuilder() {
+    return new Builder(this);
+  }
+
   /**
    * Builder for constructing {@link FirebaseOptions}. 
    */
@@ -249,15 +259,23 @@ public static final class Builder {
     private int connectTimeout;
     private int readTimeout;
 
-    /** Constructs an empty builder. */
+    /**
+     * Constructs an empty builder.
+     *
+     * @deprecated Use {@link FirebaseOptions#builder()} instead.
+     */
+    @Deprecated
     public Builder() {}
 
     /**
      * Initializes the builder's values from the options object.
      *
      * <p>The new builder is not backed by this object's values, that is changes made to the new
      * builder don't change the values of the origin object.
+     *
+     * @deprecated Use {@link FirebaseOptions#toBuilder()} instead.
      */
+    @Deprecated
     public Builder(FirebaseOptions options) {
       databaseUrl = options.databaseUrl;
       storageBucket = options.storageBucket;