Merge branch 'master' into hkj-firestore-java

hiranya911 · hiranya911 · commit d87f364bc339 · 2017-10-09T14:57:51.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,5 @@ target/
 .project
 .checkstyle
 release.properties
+integration_cert.json
+integration_apikey.txt
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -130,21 +130,20 @@ Integration tests are also written using Junit4. They coexist with the unit test
 subdirectory. Integration tests follow the naming convention `*IT.java` (e.g. `DataTestIT.java`),
 which enables the Maven Surefire and Failsafe plugins to differentiate between the two types of
 tests. Integration tests are executed against a real life Firebase project, and therefore
-requires an Internet connection. Create a new project in the
-[Firebase console](https://console.firebase.google.com/) if you do not already have one. Use a 
-separate, dedicated project for integration tests since the test suite makes a large number of
-writes to the Firebase realtime database. Download the service account private key from the 
-"Settings > Service Accounts" page of the project. Also obtain the web API key of the project
-from the "Settings > General" page. Now run the following command to invoke the integration
-test suite:
+requires an Internet connection.
+
+Create a new project in the [Firebase console](https://console.firebase.google.com/) if you do
+not already have one. Use a separate, dedicated project for integration tests since the test suite
+makes a large number of writes to the Firebase realtime database. Download the service account
+private key from the "Settings > Service Accounts" page of the project, and save it as
+`integration_cert.json` at the root of the codebase. Also obtain the web API key of the project
+from the "Settings > General" page, and save it as `integration_apikey.txt` at the root of the
+codebase. Now run the following command to invoke the integration test suite:
 
 ```
-mvn verify -Dfirebase.it.certificate=path/to/serviceAccount.json -Dfirebase.it.apikey=API-Key
+mvn verify
 ```
 
-Make sure to specify the correct path to your downloaded service account key file as the
-`firebase.it.certificate` system property. 
-
 The above command invokes both unit and integration test suites. To execute only the integration
 tests, specify the `-DskipUTs` flag.
 
diff --git a/src/main/java/com/google/firebase/ThreadManager.java b/src/main/java/com/google/firebase/ThreadManager.java
@@ -32,8 +32,8 @@
  *
  * <p>Multiple app instances may use the same <code>ThreadManager</code> instance.
  * Methods in this interface may get invoked multiple times by the same
- * app, during its lifetime. Apps may also invoke methods of this interface concurrently, and
- * therefore implementations should provide any synchronization necessary.
+ * app, during its lifetime. Apps may also invoke methods of this interface concurrently and
+ * so implementations should provide any synchronization necessary.
  */
 public abstract class ThreadManager {
 
@@ -76,11 +76,11 @@ protected abstract void releaseExecutor(
    * Returns the <code>ThreadFactory</code> to be used for creating long-lived threads. This is
    * used mainly to create the long-lived worker threads for the Realtime Database client, and
    * other scheduled (periodic) tasks started by the SDK. The SDK guarantees
-   * clean termination of all threads started via this <code>ThreadFactory</code>, upon
-   * calling {@link FirebaseApp#delete()}.
+   * clean termination of all threads started via this <code>ThreadFactory</code>, when the user
+   * calls {@link FirebaseApp#delete()}.
    *
    * <p>If long-lived threads cannot be supported in the current runtime, this method may
-   * throw a RuntimeException.
+   * throw a {@code RuntimeException}.
    *
    * @return A non-null <code>ThreadFactory</code>.
    */
diff --git a/src/main/java/com/google/firebase/auth/FirebaseAuth.java b/src/main/java/com/google/firebase/auth/FirebaseAuth.java
@@ -111,7 +111,7 @@ public static synchronized FirebaseAuth getInstance(FirebaseApp app) {
   }
 
   /**
-   * Similar to {@link #createCustomTokenAsync(String)}, but returns a Task.
+   * Similar to {@link #createCustomTokenAsync(String)}, but returns a {@link Task}.
    *
    * @param uid The UID to store in the token. This identifies the user to other Firebase services
    *     (Firebase Database, Firebase Auth, etc.)
@@ -124,7 +124,7 @@ public Task<String> createCustomToken(String uid) {
   }
 
   /**
-   * Similar to {@link #createCustomTokenAsync(String, Map)}, but returns a Task.
+   * Similar to {@link #createCustomTokenAsync(String, Map)}, but returns a {@link Task}.
    *
    * @param uid The UID to store in the token. This identifies the user to other Firebase services
    *     (Realtime Database, Storage, etc.). Should be less than 128 characters.
@@ -158,12 +158,14 @@ public String call() throws Exception {
 
   /**
    * Creates a Firebase Custom Token associated with the given UID. This token can then be provided
-   * back to a client application for use with the signInWithCustomToken authentication API.
+   * back to a client application for use with the
+   * <a href="/docs/auth/admin/create-custom-tokens#sign_in_using_custom_tokens_on_clients">signInWithCustomToken</a>
+   * authentication API.
    *
    * @param uid The UID to store in the token. This identifies the user to other Firebase services
-   *     (Firebase Database, Firebase Auth, etc.)
-   * @return An ApiFuture which will complete successfully with the created Firebase Custom Token,
-   *     or unsuccessfully with the failure Exception.
+   *     (Firebase Realtime Database, Firebase Auth, etc.)
+   * @return An {@code ApiFuture} which will complete successfully with the created Firebase Custom
+   *     Token, or unsuccessfully with the failure Exception.
    */
   public ApiFuture<String> createCustomTokenAsync(String uid) {
     return new TaskToApiFuture<>(createCustomToken(uid));
@@ -179,16 +181,16 @@ public ApiFuture<String> createCustomTokenAsync(String uid) {
    * @param developerClaims Additional claims to be stored in the token (and made available to
    *     security rules in Database, Storage, etc.). These must be able to be serialized to JSON
    *     (e.g. contain only Maps, Arrays, Strings, Booleans, Numbers, etc.)
-   * @return An ApiFuture which will complete successfully with the created Firebase Custom Token,
-   *     or unsuccessfully with the failure Exception.
+   * @return An {@code ApiFuture} which will complete successfully with the created Firebase Custom
+   *     Token, or unsuccessfully with the failure Exception.
    */
   public ApiFuture<String> createCustomTokenAsync(
       final String uid, final Map<String, Object> developerClaims) {
     return new TaskToApiFuture<>(createCustomToken(uid, developerClaims));
   }
 
   /**
-   * Similar to {@link #verifyIdTokenAsync(String)}, but returns a Task.
+   * Similar to {@link #verifyIdTokenAsync(String)}, but returns a {@link Task}.
    *
    * @param token A Firebase ID Token to verify and parse.
    * @return A {@link Task} which will complete successfully with the parsed token, or
@@ -235,20 +237,20 @@ public FirebaseToken call() throws Exception {
    * If the token is invalid, the future throws an exception indicating the failure.
    *
    * @param token A Firebase ID Token to verify and parse.
-   * @return An ApiFuture which will complete successfully with the parsed token, or
+   * @return An {@code ApiFuture} which will complete successfully with the parsed token, or
    *     unsuccessfully with the failure Exception.
    */
   public ApiFuture<FirebaseToken> verifyIdTokenAsync(final String token) {
     return new TaskToApiFuture<>(verifyIdToken(token));
   }
 
   /**
-   * Similar to {@link #getUserAsync(String)}, but returns a Task.
+   * Similar to {@link #getUserAsync(String)}, but returns a {@link Task}.
    *
    * @param uid A user ID string.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance.
    *     If an error occurs while retrieving user data or if the specified user ID does not exist,
-   *     the task fails with a FirebaseAuthException.
+   *     the task fails with a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the user ID string is null or empty.
    * @deprecated Use {@link #getUserAsync(String)}
    */
@@ -267,22 +269,22 @@ public UserRecord call() throws Exception {
    * Gets the user data corresponding to the specified user ID.
    *
    * @param uid A user ID string.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance.
-   *     If an error occurs while retrieving user data or if the specified user ID does not exist,
-   *     the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance. If an error occurs while retrieving user data or if the specified user ID does
+   *     not exist, the future throws a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the user ID string is null or empty.
    */
   public ApiFuture<UserRecord> getUserAsync(final String uid) {
     return new TaskToApiFuture<>(getUser(uid));
   }
 
   /**
-   * Similar to {@link #getUserByEmailAsync(String)}, but returns a Task.
+   * Similar to {@link #getUserByEmailAsync(String)}, but returns a {@link Task}.
    *
    * @param email A user email address string.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance.
    *     If an error occurs while retrieving user data or if the email address does not correspond
-   *     to a user, the task fails with a FirebaseAuthException.
+   *     to a user, the task fails with a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the email is null or empty.
    * @deprecated Use {@link #getUserByEmailAsync(String)}
    */
@@ -301,22 +303,22 @@ public UserRecord call() throws Exception {
    * Gets the user data corresponding to the specified user email.
    *
    * @param email A user email address string.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance.
-   *     If an error occurs while retrieving user data or if the email address does not correspond
-   *     to a user, the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance. If an error occurs while retrieving user data or if the email address does not
+   *     correspond to a user, the future throws a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the email is null or empty.
    */
   public ApiFuture<UserRecord> getUserByEmailAsync(final String email) {
     return new TaskToApiFuture<>(getUserByEmail(email));
   }
 
   /**
-   * Similar to {@link #getUserByPhoneNumberAsync(String)}, but returns a Task.
+   * Similar to {@link #getUserByPhoneNumberAsync(String)}, but returns a {@link Task}.
    *
    * @param phoneNumber A user phone number string.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance.
    *     If an error occurs while retrieving user data or if the phone number does not
-   *     correspond to a user, the task fails with a FirebaseAuthException.
+   *     correspond to a user, the task fails with a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the phone number is null or empty.
    * @deprecated Use {@link #getUserByPhoneNumberAsync(String)}
    */
@@ -335,22 +337,22 @@ public UserRecord call() throws Exception {
    * Gets the user data corresponding to the specified user phone number.
    *
    * @param phoneNumber A user phone number string.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance.
-   *     If an error occurs while retrieving user data or if the phone number does not
-   *     correspond to a user, the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance. If an error occurs while retrieving user data or if the phone number does not
+   *     correspond to a user, the future throws a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the phone number is null or empty.
    */
   public ApiFuture<UserRecord> getUserByPhoneNumberAsync(final String phoneNumber) {
     return new TaskToApiFuture<>(getUserByPhoneNumber(phoneNumber));
   }
 
   /**
-   * Similar to {@link #createUserAsync(CreateRequest)}, but returns a Task.
+   * Similar to {@link #createUserAsync(CreateRequest)}, but returns a {@link Task}.
    *
    * @param request A non-null {@link CreateRequest} instance.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance
    *     corresponding to the newly created account. If an error occurs while creating the user
-   *     account, the task fails with a FirebaseAuthException.
+   *     account, the task fails with a {@link FirebaseAuthException}.
    * @throws NullPointerException if the provided request is null.
    * @deprecated Use {@link #createUserAsync(CreateRequest)}
    */
@@ -371,22 +373,22 @@ public UserRecord call() throws Exception {
    * {@link CreateRequest}.
    *
    * @param request A non-null {@link CreateRequest} instance.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance
-   *     corresponding to the newly created account. If an error occurs while creating the user
-   *     account, the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance corresponding to the newly created account. If an error occurs while creating the
+   *     user account, the future throws a {@link FirebaseAuthException}.
    * @throws NullPointerException if the provided request is null.
    */
   public ApiFuture<UserRecord> createUserAsync(final CreateRequest request) {
     return new TaskToApiFuture<>(createUser(request));
   }
 
   /**
-   * Similar to {@link #updateUserAsync(UpdateRequest)}, but returns a Task.
+   * Similar to {@link #updateUserAsync(UpdateRequest)}, but returns a {@link Task}.
    *
    * @param request A non-null {@link UpdateRequest} instance.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance
    *     corresponding to the updated user account. If an error occurs while updating the user
-   *     account, the task fails with a FirebaseAuthException.
+   *     account, the task fails with a {@link FirebaseAuthException}.
    * @throws NullPointerException if the provided update request is null.
    * @deprecated Use {@link #updateUserAsync(UpdateRequest)}
    */
@@ -407,22 +409,22 @@ public UserRecord call() throws Exception {
    * {@link UpdateRequest}.
    *
    * @param request A non-null {@link UpdateRequest} instance.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance
-   *     corresponding to the updated user account. If an error occurs while updating the user
-   *     account, the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance corresponding to the updated user account. If an error occurs while updating the
+   *     user account, the future throws a {@link FirebaseAuthException}.
    * @throws NullPointerException if the provided update request is null.
    */
   public ApiFuture<UserRecord> updateUserAsync(final UpdateRequest request) {
     return new TaskToApiFuture<>(updateUser(request));
   }
 
   /**
-   * Similar to {@link #deleteUserAsync(String)}, but returns a Task.
+   * Similar to {@link #deleteUserAsync(String)}, but returns a {@link Task}.
    *
    * @param uid A user ID string.
    * @return A {@link Task} which will complete successfully when the specified user account has
    *     been deleted. If an error occurs while deleting the user account, the task fails with a
-   *     FirebaseAuthException.
+   *     {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the user ID string is null or empty.
    * @deprecated Use {@link #deleteUserAsync(String)}
    */
@@ -455,9 +457,9 @@ private void destroy() {
    * Deletes the user identified by the specified user ID.
    *
    * @param uid A user ID string.
-   * @return An ApiFuture which will complete successfully when the specified user account has
-   *     been deleted. If an error occurs while deleting the user account, the future throws a
-   *     FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully when the specified user account
+   *     has been deleted. If an error occurs while deleting the user account, the future throws a
+   *     {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the user ID string is null or empty.
    */
   public ApiFuture<Void> deleteUserAsync(final String uid) {
diff --git a/src/test/java/com/google/firebase/testing/IntegrationTestUtils.java b/src/test/java/com/google/firebase/testing/IntegrationTestUtils.java
@@ -16,10 +16,10 @@
 
 package com.google.firebase.testing;
 
-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.api.client.googleapis.util.Utils;
+import com.google.api.client.json.GenericJson;
 import com.google.common.collect.ImmutableList;
 import com.google.common.io.CharStreams;
 import com.google.firebase.FirebaseApp;
@@ -40,26 +40,28 @@
 import org.apache.http.entity.StringEntity;
 import org.apache.http.impl.client.DefaultHttpClient;
 import org.apache.http.util.EntityUtils;
-import org.json.JSONObject;
 
 public class IntegrationTestUtils {
 
-  private static JSONObject IT_SERVICE_ACCOUNT;
+  private static final String IT_SERVICE_ACCOUNT_PATH = "integration_cert.json";
+  private static final String IT_API_KEY_PATH = "integration_apikey.txt";
+
+  private static GenericJson serviceAccount;
+  private static String apiKey;
   private static FirebaseApp masterApp;
 
-  private static synchronized JSONObject ensureServiceAccount() {
-    if (IT_SERVICE_ACCOUNT == null) {
-      String certificatePath = System.getProperty("firebase.it.certificate");
-      checkArgument(!Strings.isNullOrEmpty(certificatePath),
-          "Service account certificate path not set. Set the "
-              + "firebase.it.certificate system property and try again.");
-      try (InputStreamReader reader = new InputStreamReader(new FileInputStream(certificatePath))) {
-        IT_SERVICE_ACCOUNT = new JSONObject(CharStreams.toString(reader));
+  private static synchronized GenericJson ensureServiceAccount() {
+    if (serviceAccount == null) {
+      try (InputStream stream = new FileInputStream(IT_SERVICE_ACCOUNT_PATH)) {
+        serviceAccount = Utils.getDefaultJsonFactory().fromInputStream(stream, GenericJson.class);
       } catch (IOException e) {
-        throw new RuntimeException("Failed to read service account certificate", e);
+        String msg = String.format("Failed to read service account certificate from %s. "
+            + "Integration tests require a service account credential obtained from a Firebase "
+            + "project. See CONTRIBUTING.md for more details.", IT_SERVICE_ACCOUNT_PATH);
+        throw new RuntimeException(msg, e);
       }
     }
-    return IT_SERVICE_ACCOUNT;
+    return serviceAccount;
   }
 
   public static InputStream getServiceAccountCertificate() {
@@ -78,10 +80,17 @@ public static String getStorageBucket() {
     return getProjectId() + ".appspot.com";
   }
 
-  public static String getApiKey() {
-    String apiKey = System.getProperty("firebase.it.apikey");
-    checkArgument(!Strings.isNullOrEmpty(apiKey), "API key not specified. Set the "
-        + "firebase.it.apikey system property and try again.");
+  public static synchronized String getApiKey() {
+    if (apiKey == null) {
+      try (InputStream stream = new FileInputStream(IT_API_KEY_PATH)) {
+        apiKey = CharStreams.toString(new InputStreamReader(stream)).trim();
+      } catch (IOException e) {
+        String msg = String.format("Failed to read API key from %s. "
+            + "Integration tests require an API key obtained from a Firebase "
+            + "project. See CONTRIBUTING.md for more details.", IT_API_KEY_PATH);
+        throw new RuntimeException(msg, e);
+      }
+    }
     return apiKey;
   }
 
