Add application scope for fire-and-forget jobs (#926)

* Add application scope for fire-and-forget jobs

* Update app/src/main/java/com/example/android/architecture/blueprints/todoapp/data/DefaultTaskRepository.kt

Co-authored-by: Manuel Vivo <[email protected]>

* Update app/src/main/java/com/example/android/architecture/blueprints/todoapp/data/DefaultTaskRepository.kt

Co-authored-by: Manuel Vivo <[email protected]>

* Fix imports

* Change createTest to return task ID

* Replace provides with binds for simpler Hilt config

* Add dispatcher and scope to test dependencies, improve param names

* Fix failing test, fix spotless

* Catch exceptions and update comments for send tasks job

---------

Co-authored-by: Manuel Vivo <[email protected]>

app/src/main/java/com/example/android/architecture/blueprints/todoapp/data/DefaultTaskRepository.kt

@@ -18,40 +18,48 @@ package com.example.android.architecture.blueprints.todoapp.data
 
 import com.example.android.architecture.blueprints.todoapp.data.source.local.TaskDao
 import com.example.android.architecture.blueprints.todoapp.data.source.network.NetworkDataSource
+import com.example.android.architecture.blueprints.todoapp.di.ApplicationScope
+import com.example.android.architecture.blueprints.todoapp.di.DefaultDispatcher
 import java.util.UUID
+import javax.inject.Inject
+import javax.inject.Singleton
 import kotlinx.coroutines.CoroutineDispatcher
-import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 
 /**
  * Default implementation of [TaskRepository]. Single entry point for managing tasks' data.
  *
- * @param tasksNetworkDataSource - The network data source
- * @param taskDao - The local data source
- * @param coroutineDispatcher - The dispatcher to be used for long running or complex operations,
- * such as network calls or mapping many models. This is important to avoid blocking the calling
- * thread.
+ * @param networkDataSource - The network data source
+ * @param localDataSource - The local data source
+ * @param dispatcher - The dispatcher to be used for long running or complex operations, such as ID
+ * generation or mapping many models.
+ * @param scope - The coroutine scope used for deferred jobs where the result isn't important, such
+ * as sending data to the network.
  */
-class DefaultTaskRepository(
-    private val tasksNetworkDataSource: NetworkDataSource,
-    private val taskDao: TaskDao,
-    private val coroutineDispatcher: CoroutineDispatcher = Dispatchers.Default
+@Singleton
+class DefaultTaskRepository @Inject constructor(
+    private val networkDataSource: NetworkDataSource,
+    private val localDataSource: TaskDao,
+    @DefaultDispatcher private val dispatcher: CoroutineDispatcher,
+    @ApplicationScope private val scope: CoroutineScope,
 ) : TaskRepository {
 
     override suspend fun createTask(title: String, description: String): String {
         // ID creation might be a complex operation so it's executed using the supplied
         // coroutine dispatcher
-        val taskId = withContext(coroutineDispatcher) {
+        val taskId = withContext(dispatcher) {
             UUID.randomUUID().toString()
         }
         val task = Task(
             title = title,
             description = description,
             id = taskId,
         )
-        taskDao.upsert(task.toLocal())
+        localDataSource.upsert(task.toLocal())
         saveTasksToNetwork()
         return taskId
     }
@@ -62,37 +70,33 @@ class DefaultTaskRepository(
             description = description
         ) ?: throw Exception("Task (id $taskId) not found")
 
-        taskDao.upsert(task.toLocal())
+        localDataSource.upsert(task.toLocal())
         saveTasksToNetwork()
     }
 
     override suspend fun getTasks(forceUpdate: Boolean): List<Task> {
         if (forceUpdate) {
-            loadTasksFromNetwork()
+            refresh()
         }
-        return withContext(coroutineDispatcher) {
-            taskDao.getAll().toExternal()
+        return withContext(dispatcher) {
+            localDataSource.getAll().toExternal()
         }
     }
 
-    override suspend fun refreshTasks() {
-        loadTasksFromNetwork()
-    }
-
     override fun getTasksStream(): Flow<List<Task>> {
-        return taskDao.observeAll().map { tasks ->
-            withContext(coroutineDispatcher) {
+        return localDataSource.observeAll().map { tasks ->
+            withContext(dispatcher) {
                 tasks.toExternal()
             }
         }
     }
 
     override suspend fun refreshTask(taskId: String) {
-        loadTasksFromNetwork()
+        refresh()
     }
 
     override fun getTaskStream(taskId: String): Flow<Task?> {
-        return taskDao.observeById(taskId).map { it.toExternal() }
+        return localDataSource.observeById(taskId).map { it.toExternal() }
     }
 
     /**
@@ -103,60 +107,78 @@ class DefaultTaskRepository(
      */
     override suspend fun getTask(taskId: String, forceUpdate: Boolean): Task? {
         if (forceUpdate) {
-            loadTasksFromNetwork()
+            refresh()
         }
-        return taskDao.getById(taskId)?.toExternal()
+        return localDataSource.getById(taskId)?.toExternal()
     }
 
     override suspend fun completeTask(taskId: String) {
-        taskDao.updateCompleted(taskId = taskId, completed = true)
+        localDataSource.updateCompleted(taskId = taskId, completed = true)
         saveTasksToNetwork()
     }
 
     override suspend fun activateTask(taskId: String) {
-        taskDao.updateCompleted(taskId = taskId, completed = false)
+        localDataSource.updateCompleted(taskId = taskId, completed = false)
         saveTasksToNetwork()
     }
 
     override suspend fun clearCompletedTasks() {
-        taskDao.deleteCompleted()
+        localDataSource.deleteCompleted()
         saveTasksToNetwork()
     }
 
     override suspend fun deleteAllTasks() {
-        taskDao.deleteAll()
+        localDataSource.deleteAll()
         saveTasksToNetwork()
     }
 
     override suspend fun deleteTask(taskId: String) {
-        taskDao.deleteById(taskId)
+        localDataSource.deleteById(taskId)
         saveTasksToNetwork()
     }
 
     /**
-     * The following methods load tasks from, and save tasks to, the network.
-     *
-     * Consider these to be long running operations, hence the need for `withContext` which
-     * can change the coroutine dispatcher so that the caller isn't blocked.
+     * The following methods load tasks from (refresh), and save tasks to, the network.
      *
      * Real apps may want to do a proper sync, rather than the "one-way sync everything" approach
      * below. See https://developer.android.com/topic/architecture/data-layer/offline-first
      * for more efficient and robust synchronisation strategies.
      *
-     * Also, in a real app, these operations could be scheduled using WorkManager.
+     * Note that the refresh operation is a suspend function (forces callers to wait) and the save
+     * operation is not. It returns immediately so callers don't have to wait.
      */
-    private suspend fun loadTasksFromNetwork() {
-        withContext(coroutineDispatcher) {
-            val remoteTasks = tasksNetworkDataSource.loadTasks()
-            taskDao.deleteAll()
-            taskDao.upsertAll(remoteTasks.toLocal())
+
+    /**
+     * Delete everything in the local data source and replace it with everything from the network
+     * data source.
+     *
+     * `withContext` is used here in case the bulk `toLocal` mapping operation is complex.
+     */
+    override suspend fun refresh() {
+        withContext(dispatcher) {
+            val remoteTasks = networkDataSource.loadTasks()
+            localDataSource.deleteAll()
+            localDataSource.upsertAll(remoteTasks.toLocal())
         }
     }
 
-    private suspend fun saveTasksToNetwork() {
-        withContext(coroutineDispatcher) {
-            val localTasks = taskDao.getAll()
-            tasksNetworkDataSource.saveTasks(localTasks.toNetwork())
+    /**
+     * Send the tasks from the local data source to the network data source
+     *
+     * Returns immediately after launching the job. Real apps may want to suspend here until the
+     * operation is complete or (better) use WorkManager to schedule this work. Both approaches
+     * should provide a mechanism for failures to be communicated back to the user so that
+     * they are aware that their data isn't being backed up.
+     */
+    private fun saveTasksToNetwork() {
+        scope.launch {
+            try {
+                val localTasks = localDataSource.getAll()
+                networkDataSource.saveTasks(localTasks.toNetwork())
+            } catch (e: Exception) {
+                // In a real app you'd handle the exception e.g. by exposing a `networkStatus` flow
+                // to an app level UI state holder which could then display a Toast message.
+            }
         }
     }
 }

app/src/main/java/com/example/android/architecture/blueprints/todoapp/data/TaskRepository.kt

@@ -27,7 +27,7 @@ interface TaskRepository {
 
     suspend fun getTasks(forceUpdate: Boolean = false): List<Task>
 
-    suspend fun refreshTasks()
+    suspend fun refresh()
 
     fun getTaskStream(taskId: String): Flow<Task?>
 

app/src/main/java/com/example/android/architecture/blueprints/todoapp/data/source/network/TaskNetworkDataSource.kt

@@ -16,15 +16,16 @@
 
 package com.example.android.architecture.blueprints.todoapp.data.source.network
 
+import javax.inject.Inject
 import kotlinx.coroutines.delay
 
 /**
  * Implementation of the data source that adds a latency simulating network.
  *
  */
-object TaskNetworkDataSource : NetworkDataSource {
+class TaskNetworkDataSource @Inject constructor() : NetworkDataSource {
 
-    private const val SERVICE_LATENCY_IN_MILLIS = 2000L
+    private val SERVICE_LATENCY_IN_MILLIS = 2000L
 
     private var TASK_SERVICE_DATA = LinkedHashMap<String, NetworkTask>(2)
 

app/src/main/java/com/example/android/architecture/blueprints/todoapp/di/CoroutinesModule.kt

@@ -21,18 +21,40 @@ import dagger.Provides
 import dagger.hilt.InstallIn
 import dagger.hilt.components.SingletonComponent
 import javax.inject.Qualifier
+import javax.inject.Singleton
 import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
 
 @Qualifier
 @Retention(AnnotationRetention.RUNTIME)
 annotation class IoDispatcher
 
+@Retention(AnnotationRetention.RUNTIME)
+@Qualifier
+annotation class DefaultDispatcher
+
+@Retention(AnnotationRetention.RUNTIME)
+@Qualifier
+annotation class ApplicationScope
+
 @Module
 @InstallIn(SingletonComponent::class)
 object CoroutinesModule {
 
     @Provides
     @IoDispatcher
     fun providesIODispatcher(): CoroutineDispatcher = Dispatchers.IO
+
+    @Provides
+    @DefaultDispatcher
+    fun providesDefaultDispatcher(): CoroutineDispatcher = Dispatchers.Default
+
+    @Provides
+    @Singleton
+    @ApplicationScope
+    fun providesCoroutineScope(
+        @DefaultDispatcher dispatcher: CoroutineDispatcher
+    ): CoroutineScope = CoroutineScope(SupervisorJob() + dispatcher)
 }

app/src/main/java/com/example/android/architecture/blueprints/todoapp/di/DataModules.kt

@@ -20,43 +20,34 @@ import android.content.Context
 import androidx.room.Room
 import com.example.android.architecture.blueprints.todoapp.data.DefaultTaskRepository
 import com.example.android.architecture.blueprints.todoapp.data.TaskRepository
+import com.example.android.architecture.blueprints.todoapp.data.source.local.TaskDao
 import com.example.android.architecture.blueprints.todoapp.data.source.local.ToDoDatabase
 import com.example.android.architecture.blueprints.todoapp.data.source.network.NetworkDataSource
 import com.example.android.architecture.blueprints.todoapp.data.source.network.TaskNetworkDataSource
+import dagger.Binds
 import dagger.Module
 import dagger.Provides
 import dagger.hilt.InstallIn
 import dagger.hilt.android.qualifiers.ApplicationContext
 import dagger.hilt.components.SingletonComponent
-import javax.inject.Qualifier
 import javax.inject.Singleton
 
-@Qualifier
-@Retention(AnnotationRetention.RUNTIME)
-annotation class NetworkTaskDataSource
-
 @Module
 @InstallIn(SingletonComponent::class)
-object RepositoryModule {
+abstract class RepositoryModule {
 
     @Singleton
-    @Provides
-    fun provideTaskRepository(
-        @NetworkTaskDataSource remoteDataSource: NetworkDataSource,
-        database: ToDoDatabase,
-    ): TaskRepository {
-        return DefaultTaskRepository(remoteDataSource, database.taskDao())
-    }
+    @Binds
+    abstract fun bindTaskRepository(repository: DefaultTaskRepository): TaskRepository
 }
 
 @Module
 @InstallIn(SingletonComponent::class)
-object DataSourceModule {
+abstract class DataSourceModule {
 
     @Singleton
-    @NetworkTaskDataSource
-    @Provides
-    fun provideTaskRemoteDataSource(): NetworkDataSource = TaskNetworkDataSource
+    @Binds
+    abstract fun bindNetworkDataSource(dataSource: TaskNetworkDataSource): NetworkDataSource
 }
 
 @Module
@@ -72,4 +63,7 @@ object DatabaseModule {
             "Tasks.db"
         ).build()
     }
+
+    @Provides
+    fun provideTaskDao(database: ToDoDatabase): TaskDao = database.taskDao()
 }

app/src/main/java/com/example/android/architecture/blueprints/todoapp/statistics/StatisticsViewModel.kt

@@ -62,7 +62,7 @@ class StatisticsViewModel @Inject constructor(
 
     fun refresh() {
         viewModelScope.launch {
-            taskRepository.refreshTasks()
+            taskRepository.refresh()
         }
     }
 

app/src/main/java/com/example/android/architecture/blueprints/todoapp/tasks/TasksViewModel.kt

@@ -140,7 +140,7 @@ class TasksViewModel @Inject constructor(
     fun refresh() {
         _isLoading.value = true
         viewModelScope.launch {
-            taskRepository.refreshTasks()
+            taskRepository.refresh()
             _isLoading.value = false
         }
     }

app/src/test/java/com/example/android/architecture/blueprints/todoapp/data/DefaultTaskRepositoryTest.kt

@@ -22,6 +22,9 @@ import com.example.android.architecture.blueprints.todoapp.data.source.network.F
 import com.google.common.truth.Truth.assertThat
 import junit.framework.TestCase.assertEquals
 import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.test.StandardTestDispatcher
+import kotlinx.coroutines.test.TestScope
+import kotlinx.coroutines.test.advanceUntilIdle
 import kotlinx.coroutines.test.runTest
 import org.junit.Before
 import org.junit.Rule
@@ -63,19 +66,18 @@ class DefaultTaskRepositoryTest {
         localDataSource = FakeTaskDao(localTasks)
         // Get a reference to the class under test
         tasksRepository = DefaultTaskRepository(
-            networkDataSource, localDataSource
+            networkDataSource = networkDataSource,
+            localDataSource = localDataSource,
+            dispatcher = StandardTestDispatcher(),
+            scope = TestScope()
         )
     }
 
     @ExperimentalCoroutinesApi
     @Test
     fun getTasks_emptyRepositoryAndUninitializedCache() = runTest {
-        val emptyRemoteSource = FakeNetworkDataSource()
-        val emptyLocalSource = FakeTaskDao()
-
-        val tasksRepository = DefaultTaskRepository(
-            emptyRemoteSource, emptyLocalSource
-        )
+        networkDataSource.tasks?.clear()
+        localDataSource.deleteAll()
 
         assertThat(tasksRepository.getTasks().size).isEqualTo(0)
     }
@@ -110,6 +112,9 @@ class DefaultTaskRepositoryTest {
         // When a task is saved to the tasks repository
         val newTaskId = tasksRepository.createTask(newTask.title, newTask.description)
 
+        // Wait for the network to be updated
+        advanceUntilIdle()
+
         // Then the remote and local sources contain the new task
         assertThat(networkDataSource.tasks?.map { it.id }?.contains(newTaskId))
         assertThat(localDataSource.tasks?.map { it.id }?.contains(newTaskId))