Update with latest changes from master (#4091)

* Deflake firebase_common HeartBeat tests. (#4083)

The tests relied on `TestOnCompleteListener` that was not safe to call
more than once since it was based on a count down latch. So reusing it
multiple times would cause await() to return immediately.

This change makes it so that a new latch is created for every await()
call, making all await() calls work.

Fixes: http://b/245956774

* Add Javadoc support to the DackkaPlugin (#4082)

* Add util method for copying directories

* Add javadoc support to our dackka plugin

* Remove the extension check on fromDirectory

* Add a note about cache compliance and the javadoc task

* Add reference to kotlin stdlib package list (#4093)

Co-authored-by: Vladimir Kryachko <[email protected]>
Co-authored-by: Daymon <[email protected]>

Author: 3 people

buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaGenerationTask.kt

@@ -127,7 +127,8 @@ abstract class GenerateDocumentationTask @Inject constructor(
             "android" to "https://developer.android.com/reference/kotlin/",
             "google" to "https://developers.google.com/android/reference/",
             "firebase" to "https://firebase.google.com/docs/reference/kotlin/",
-            "coroutines" to "https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/"
+            "coroutines" to "https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/",
+            "kotlin" to "https://kotlinlang.org/api/latest/jvm/stdlib/"
         )
 
         return packageLists.get().map {

buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt

@@ -90,26 +90,23 @@ tasks above). While we do not currently offer any configuration for the Dackka
 plugin, this could change in the future as needed. Currently, the DackkaPlugin
 provides sensible defaults to output directories, package lists, and so forth.
 
-The DackkaPlugin also provides two extra tasks:
-[cleanDackkaDocumentation][registerCleanDackkaDocumentation] and
-[deleteDackkaGeneratedJavaReferences][registerDeleteDackkaGeneratedJavaReferencesTask].
+The DackkaPlugin also provides three extra tasks:
+[cleanDackkaDocumentation][registerCleanDackkaDocumentation],
+[copyJavaDocToCommonDirectory][registerCopyJavaDocToCommonDirectoryTask] and
+[copyKotlinDocToCommonDirectory][registerCopyKotlinDocToCommonDirectoryTask].
 
 _cleanDackkaDocumentation_ is exactly what it sounds like, a task to clean up (delete)
 the output of Dackka. This is useful when testing Dackka outputs itself- and
 shouldn't be apart of the normal flow. The reasoning is that it would otherwise
 invalidate the gradle cache.
 
-_deleteDackkaGeneratedJavaReferences_ is a temporary addition. Dackka generates
-two separate styles of docs for every source set: Java & Kotlin. Regardless of
-whether the source is in Java or Kotlin. The Java output is how the source looks
-from Java, and the Kotlin output is how the source looks from Kotlin. We publish
-these under two separate categories, which you can see here:
-[Java](https://firebase.google.com/docs/reference/android/packages)
-or
-[Kotlin](https://firebase.google.com/docs/reference/kotlin/packages).
-Although, we do not currently publish Java packages with Dackka- and will wait
-until we are more comfortable with the output of Dackka to do so. So until then,
-this task will remove all generate Java references from the Dackka output.
+_copyJavaDocToCommonDirectory_ copies the JavaDoc variant of the Dackka output for each sdk,
+and pastes it in a common directory under the root project's build directory. This makes it easier
+to zip the doc files for staging.
+
+_copyKotlinDocToCommonDirectory_ copies the KotlinDoc variant of the Dackka output for each sdk,
+and pastes it in a common directory under the root project's build directory. This makes it easier
+to zip the doc files for staging.
 
 Currently, the DackkaPlugin builds Java sources separate from Kotlin Sources. There is an open bug
 for Dackka in which hidden parent classes and annotations do not hide themselves from children classes.
@@ -125,16 +122,16 @@ abstract class DackkaPlugin : Plugin<Project> {
                 val generateDocumentation = registerGenerateDackkaDocumentationTask(project)
                 val outputDirectory = generateDocumentation.flatMap { it.outputDirectory }
                 val firesiteTransform = registerFiresiteTransformTask(project, outputDirectory)
-                val deleteJavaReferences = registerDeleteDackkaGeneratedJavaReferencesTask(project, outputDirectory)
-                val copyOutputToCommonDirectory = registerCopyDackkaOutputToCommonDirectoryTask(project, outputDirectory)
+                val copyJavaDocToCommonDirectory = registerCopyJavaDocToCommonDirectoryTask(project, outputDirectory)
+                val copyKotlinDocToCommonDirectory = registerCopyKotlinDocToCommonDirectoryTask(project, outputDirectory)
 
                 project.tasks.register("kotlindoc") {
                     group = "documentation"
                     dependsOn(
                         generateDocumentation,
                         firesiteTransform,
-                        deleteJavaReferences,
-                        copyOutputToCommonDirectory
+                        copyJavaDocToCommonDirectory,
+                        copyKotlinDocToCommonDirectory
                     )
                 }
             } else {
@@ -234,38 +231,44 @@ abstract class DackkaPlugin : Plugin<Project> {
     // TODO(b/243833009): Make task cacheable
     private fun registerFiresiteTransformTask(project: Project, outputDirectory: Provider<File>) =
         project.tasks.register<FiresiteTransformTask>("firesiteTransform") {
+            mustRunAfter("generateDackkaDocumentation")
+
             dackkaFiles.set(outputDirectory)
         }
 
-    // If we decide to publish java variants, we'll need to address the generated format as well
-    // TODO(b/243833009): Make task cacheable
-    private fun registerDeleteDackkaGeneratedJavaReferencesTask(project: Project, outputDirectory: Provider<File>) =
-        project.tasks.register<Delete>("deleteDackkaGeneratedJavaReferences") {
-            mustRunAfter("generateDackkaDocumentation")
-
-            val filesWeDoNotNeed = listOf(
-                "reference/client",
-                "reference/com"
-            )
-            val filesToDelete = outputDirectory.map { dir ->
-                filesWeDoNotNeed.map {
-                    project.files("${dir.path}/$it")
-                }
+    // TODO(b/246593212): Migrate doc files to single directory
+    private fun registerCopyJavaDocToCommonDirectoryTask(project: Project, outputDirectory: Provider<File>) =
+        project.tasks.register<Copy>("copyJavaDocToCommonDirectory") {
+            /**
+             * This is not currently cache compliant. The need for this property is
+             * temporary while we test it alongside the current javaDoc task. Since it's such a
+             * temporary behavior, losing cache compliance is fine for now.
+             */
+            if (project.rootProject.findProperty("dackkaJavadoc") == "true") {
+                mustRunAfter("firesiteTransform")
+
+                val outputFolder = project.file("${project.rootProject.buildDir}/firebase-kotlindoc/android")
+                val clientFolder = outputDirectory.map { project.file("${it.path}/reference/client") }
+                val comFolder = outputDirectory.map { project.file("${it.path}/reference/com") }
+
+                fromDirectory(clientFolder)
+                fromDirectory(comFolder)
+
+                into(outputFolder)
             }
-
-            delete(filesToDelete)
         }
 
-    private fun registerCopyDackkaOutputToCommonDirectoryTask(project: Project, outputDirectory: Provider<File>) =
-        project.tasks.register<Copy>("copyDackkaOutputToCommonDirectory") {
-            mustRunAfter("deleteDackkaGeneratedJavaReferences")
+    // TODO(b/246593212): Migrate doc files to single directory
+    private fun registerCopyKotlinDocToCommonDirectoryTask(project: Project, outputDirectory: Provider<File>) =
+        project.tasks.register<Copy>("copyKotlinDocToCommonDirectory") {
             mustRunAfter("firesiteTransform")
 
-            val referenceFolder = outputDirectory.map { project.file("${it.path}/reference") }
             val outputFolder = project.file("${project.rootProject.buildDir}/firebase-kotlindoc")
+            val kotlinFolder = outputDirectory.map { project.file("${it.path}/reference/kotlin") }
+
+            fromDirectory(kotlinFolder)
 
-            from(referenceFolder)
-            destinationDir = outputFolder
+            into(outputFolder)
         }
 
     // Useful for local testing, but may not be desired for standard use (that's why it's not depended on)

buildSrc/src/main/java/com/google/firebase/gradle/plugins/GradleUtils.kt

@@ -0,0 +1,10 @@
+package com.google.firebase.gradle.plugins
+
+import java.io.File
+import org.gradle.api.provider.Provider
+import org.gradle.api.tasks.Copy
+
+fun Copy.fromDirectory(directory: Provider<File>) =
+    from(directory) {
+        into(directory.map { it.name })
+    }

firebase-common/src/test/java/com/google/firebase/heartbeatinfo/DefaultHeartBeatControllerTest.java

@@ -15,6 +15,7 @@
 package com.google.firebase.heartbeatinfo;
 
 import static com.google.common.truth.Truth.assertThat;
+import static com.google.firebase.heartbeatinfo.TaskWaiter.await;
 import static java.nio.charset.StandardCharsets.UTF_8;
 import static org.mockito.ArgumentMatchers.anyLong;
 import static org.mockito.ArgumentMatchers.anyString;
@@ -26,7 +27,7 @@
 import android.content.Context;
 import android.content.SharedPreferences;
 import androidx.test.core.app.ApplicationProvider;
-import androidx.test.runner.AndroidJUnit4;
+import androidx.test.ext.junit.runners.AndroidJUnit4;
 import com.google.firebase.platforminfo.UserAgentPublisher;
 import java.io.ByteArrayOutputStream;
 import java.io.IOException;
@@ -35,27 +36,23 @@
 import java.util.Collections;
 import java.util.HashSet;
 import java.util.Set;
-import java.util.concurrent.ExecutionException;
-import java.util.concurrent.ExecutorService;
-import java.util.concurrent.LinkedBlockingQueue;
-import java.util.concurrent.ThreadPoolExecutor;
-import java.util.concurrent.TimeUnit;
+import java.util.concurrent.Executor;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeoutException;
 import java.util.zip.GZIPOutputStream;
-import org.json.JSONException;
 import org.junit.Before;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.robolectric.annotation.Config;
 
 @RunWith(AndroidJUnit4.class)
 public class DefaultHeartBeatControllerTest {
-  private ExecutorService executor;
-  private TestOnCompleteListener<Void> storeOnCompleteListener;
-  private TestOnCompleteListener<String> getOnCompleteListener;
-  private final String DEFAULT_USER_AGENT = "agent1";
-  private HeartBeatInfoStorage storage = mock(HeartBeatInfoStorage.class);
-  private UserAgentPublisher publisher = mock(UserAgentPublisher.class);
-  private static Context applicationContext = ApplicationProvider.getApplicationContext();
+  private static final String DEFAULT_USER_AGENT = "agent1";
+  private final Executor executor = Executors.newSingleThreadExecutor();
+
+  private final HeartBeatInfoStorage storage = mock(HeartBeatInfoStorage.class);
+  private final UserAgentPublisher publisher = mock(UserAgentPublisher.class);
+  private final Context applicationContext = ApplicationProvider.getApplicationContext();
   private final Set<HeartBeatConsumer> logSources =
       new HashSet<HeartBeatConsumer>() {
         {
@@ -66,22 +63,18 @@ public class DefaultHeartBeatControllerTest {
 
   @Before
   public void setUp() {
-    executor = new ThreadPoolExecutor(0, 1, 30L, TimeUnit.SECONDS, new LinkedBlockingQueue<>());
     when(publisher.getUserAgent()).thenReturn(DEFAULT_USER_AGENT);
-    storeOnCompleteListener = new TestOnCompleteListener<>();
-    getOnCompleteListener = new TestOnCompleteListener<>();
     heartBeatController =
         new DefaultHeartBeatController(
             () -> storage, logSources, executor, () -> publisher, applicationContext);
   }
 
   @Test
-  public void whenNoSource_dontStoreHeartBeat() throws ExecutionException, InterruptedException {
+  public void whenNoSource_dontStoreHeartBeat() throws InterruptedException, TimeoutException {
     DefaultHeartBeatController controller =
         new DefaultHeartBeatController(
             () -> storage, new HashSet<>(), executor, () -> publisher, applicationContext);
-    controller.registerHeartBeat().addOnCompleteListener(executor, storeOnCompleteListener);
-    storeOnCompleteListener.await();
+    await(controller.registerHeartBeat());
     verify(storage, times(0)).storeHeartBeat(anyLong(), anyString());
   }
 
@@ -99,31 +92,24 @@ public void getHeartBeatCode_noHeartBeat() {
 
   @Config(sdk = 29)
   @Test
-  public void generateHeartBeat_oneHeartBeat()
-      throws ExecutionException, InterruptedException, JSONException, IOException {
+  public void generateHeartBeat_oneHeartBeat() throws InterruptedException, TimeoutException {
     ArrayList<HeartBeatResult> returnResults = new ArrayList<>();
     returnResults.add(
-        HeartBeatResult.create(
-            "test-agent", new ArrayList<String>(Collections.singleton("2015-02-03"))));
+        HeartBeatResult.create("test-agent", Collections.singletonList("2015-02-03")));
     when(storage.getAllHeartBeats()).thenReturn(returnResults);
-    heartBeatController
-        .registerHeartBeat()
-        .addOnCompleteListener(executor, storeOnCompleteListener);
-    storeOnCompleteListener.await();
+    await(heartBeatController.registerHeartBeat());
     verify(storage, times(1)).storeHeartBeat(anyLong(), anyString());
-    heartBeatController
-        .getHeartBeatsHeader()
-        .addOnCompleteListener(executor, getOnCompleteListener);
     String str =
         "{\"heartbeats\":[{\"agent\":\"test-agent\",\"dates\":[\"2015-02-03\"]}],\"version\":\"2\"}";
     String expected = compress(str);
-    assertThat(getOnCompleteListener.await().replace("\n", "")).isEqualTo(expected);
+    assertThat(await(heartBeatController.getHeartBeatsHeader()).replace("\n", ""))
+        .isEqualTo(expected);
   }
 
   @Config(sdk = 29)
   @Test
   public void firstNewThenOld_synchronizedCorrectly()
-      throws ExecutionException, InterruptedException {
+      throws InterruptedException, TimeoutException {
     Context context = ApplicationProvider.getApplicationContext();
     SharedPreferences heartBeatSharedPreferences =
         context.getSharedPreferences("testHeartBeat", Context.MODE_PRIVATE);
@@ -136,10 +122,8 @@ public void firstNewThenOld_synchronizedCorrectly()
         Base64.getUrlEncoder()
             .withoutPadding()
             .encodeToString("{\"heartbeats\":[],\"version\":\"2\"}".getBytes());
-    controller.registerHeartBeat().addOnCompleteListener(executor, storeOnCompleteListener);
-    storeOnCompleteListener.await();
-    controller.getHeartBeatsHeader().addOnCompleteListener(executor, getOnCompleteListener);
-    String output = getOnCompleteListener.await();
+    await(controller.registerHeartBeat());
+    String output = await(controller.getHeartBeatsHeader());
     assertThat(output.replace("\n", "")).isNotEqualTo(emptyString);
     int heartBeatCode = controller.getHeartBeatCode("test").getCode();
     assertThat(heartBeatCode).isEqualTo(0);
@@ -148,7 +132,7 @@ public void firstNewThenOld_synchronizedCorrectly()
   @Config(sdk = 29)
   @Test
   public void firstOldThenNew_synchronizedCorrectly()
-      throws ExecutionException, InterruptedException, IOException {
+      throws InterruptedException, TimeoutException {
     Context context = ApplicationProvider.getApplicationContext();
     SharedPreferences heartBeatSharedPreferences =
         context.getSharedPreferences("testHeartBeat", Context.MODE_PRIVATE);
@@ -158,46 +142,36 @@ public void firstOldThenNew_synchronizedCorrectly()
         new DefaultHeartBeatController(
             () -> heartBeatInfoStorage, logSources, executor, () -> publisher, context);
     String emptyString = compress("{\"heartbeats\":[],\"version\":\"2\"}");
-    controller.registerHeartBeat().addOnCompleteListener(executor, storeOnCompleteListener);
-    storeOnCompleteListener.await();
+    await(controller.registerHeartBeat());
     int heartBeatCode = controller.getHeartBeatCode("test").getCode();
     assertThat(heartBeatCode).isEqualTo(2);
-    controller.getHeartBeatsHeader().addOnCompleteListener(executor, getOnCompleteListener);
-    String output = getOnCompleteListener.await();
+    String output = await(controller.getHeartBeatsHeader());
     assertThat(output.replace("\n", "")).isEqualTo(emptyString);
-    controller.registerHeartBeat().addOnCompleteListener(executor, storeOnCompleteListener);
-    storeOnCompleteListener.await();
-    controller.getHeartBeatsHeader().addOnCompleteListener(executor, getOnCompleteListener);
-    output = getOnCompleteListener.await();
+
+    await(controller.registerHeartBeat());
+    await(controller.getHeartBeatsHeader());
     assertThat(output.replace("\n", "")).isEqualTo(emptyString);
   }
 
   @Config(sdk = 29)
   @Test
   public void generateHeartBeat_twoHeartBeatsSameUserAgent()
-      throws ExecutionException, InterruptedException, JSONException, IOException {
+      throws InterruptedException, TimeoutException {
     ArrayList<HeartBeatResult> returnResults = new ArrayList<>();
     ArrayList<String> dateList = new ArrayList<>();
     dateList.add("2015-03-02");
     dateList.add("2015-03-01");
     returnResults.add(HeartBeatResult.create("test-agent", dateList));
     when(storage.getAllHeartBeats()).thenReturn(returnResults);
-    heartBeatController
-        .registerHeartBeat()
-        .addOnCompleteListener(executor, storeOnCompleteListener);
-    storeOnCompleteListener.await();
-    heartBeatController
-        .registerHeartBeat()
-        .addOnCompleteListener(executor, storeOnCompleteListener);
-    storeOnCompleteListener.await();
+    await(heartBeatController.registerHeartBeat());
+    await(heartBeatController.registerHeartBeat());
     verify(storage, times(2)).storeHeartBeat(anyLong(), anyString());
-    heartBeatController
-        .getHeartBeatsHeader()
-        .addOnCompleteListener(executor, getOnCompleteListener);
+
     String str =
         "{\"heartbeats\":[{\"agent\":\"test-agent\",\"dates\":[\"2015-03-02\",\"2015-03-01\"]}],\"version\":\"2\"}";
     String expected = compress(str);
-    assertThat(getOnCompleteListener.await().replace("\n", "")).isEqualTo(expected);
+    assertThat(await(heartBeatController.getHeartBeatsHeader()).replace("\n", ""))
+        .isEqualTo(expected);
   }
 
   private static String base64Encode(byte[] input) {
@@ -218,38 +192,28 @@ private static byte[] gzip(String input) {
     }
   }
 
-  private String compress(String str) throws IOException {
+  private String compress(String str) {
     return base64Encode(gzip(str));
   }
 
   @Config(sdk = 29)
   @Test
   public void generateHeartBeat_twoHeartBeatstwoUserAgents()
-      throws ExecutionException, InterruptedException, JSONException, IOException {
+      throws InterruptedException, TimeoutException {
     ArrayList<HeartBeatResult> returnResults = new ArrayList<>();
     returnResults.add(
-        HeartBeatResult.create(
-            "test-agent", new ArrayList<String>(Collections.singleton("2015-03-02"))));
+        HeartBeatResult.create("test-agent", Collections.singletonList("2015-03-02")));
     returnResults.add(
-        HeartBeatResult.create(
-            "test-agent-1", new ArrayList<String>(Collections.singleton("2015-03-03"))));
+        HeartBeatResult.create("test-agent-1", Collections.singletonList("2015-03-03")));
     when(storage.getAllHeartBeats()).thenReturn(returnResults);
-    heartBeatController
-        .registerHeartBeat()
-        .addOnCompleteListener(executor, storeOnCompleteListener);
-    storeOnCompleteListener.await();
-    heartBeatController
-        .registerHeartBeat()
-        .addOnCompleteListener(executor, storeOnCompleteListener);
-    storeOnCompleteListener.await();
-    Thread.sleep(1000);
+    await(heartBeatController.registerHeartBeat());
+    await(heartBeatController.registerHeartBeat());
+
     verify(storage, times(2)).storeHeartBeat(anyLong(), anyString());
-    heartBeatController
-        .getHeartBeatsHeader()
-        .addOnCompleteListener(executor, getOnCompleteListener);
     String str =
         "{\"heartbeats\":[{\"agent\":\"test-agent\",\"dates\":[\"2015-03-02\"]},{\"agent\":\"test-agent-1\",\"dates\":[\"2015-03-03\"]}],\"version\":\"2\"}";
     String expected = compress(str);
-    assertThat(getOnCompleteListener.await().replace("\n", "")).isEqualTo(expected);
+    assertThat(await(heartBeatController.getHeartBeatsHeader()).replace("\n", ""))
+        .isEqualTo(expected);
   }
 }