Fix #111: Introduce question progress controller implementation

data/build.gradle

@@ -65,6 +65,7 @@ dependencies {
       'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.2.2',
       'org.mockito:mockito-core:2.19.0',
       'org.robolectric:robolectric:4.3',
+      project(":testing"),
   )
   // TODO (#59): Remove this once Bazel is introduced
   // TODO (#97): Isolate retrofit-mock dependency from production

data/src/main/java/org/oppia/data/persistence/PersistentCacheStore.kt

@@ -46,6 +46,12 @@ class PersistentCacheStore<T : MessageLite> private constructor(
   @GuardedBy("failureLock") private var deferredLoadCacheFailure: Throwable? = null
   private val cache = cacheFactory.create(CachePayload(state = CacheState.UNLOADED, value = initialValue))
 
+  init {
+    cache.observeChanges {
+      asyncDataSubscriptionManager.notifyChange(providerId)
+    }
+  }
+
   override fun getId(): Any {
     return providerId
   }
@@ -54,7 +60,7 @@ class PersistentCacheStore<T : MessageLite> private constructor(
     cache.readIfPresentAsync().await().let { cachePayload ->
       // First, determine whether the current cache has been attempted to be retrieved from disk.
       if (cachePayload.state == CacheState.UNLOADED) {
-        deferLoadFileAndNotify()
+        deferLoadFile()
         return AsyncResult.pending()
       }
 
@@ -109,7 +115,6 @@ class PersistentCacheStore<T : MessageLite> private constructor(
     val deferred = cache.updateWithCustomChannelIfPresentAsync { cachePayload ->
       if (cachePayload.state == CacheState.UNLOADED) {
         val filePayload = loadFileCache(cachePayload)
-        asyncDataSubscriptionManager.notifyChange(providerId)
         Pair(filePayload, filePayload.value)
       } else {
         Pair(cachePayload, cachePayload.value)
@@ -135,9 +140,6 @@ class PersistentCacheStore<T : MessageLite> private constructor(
    */
   fun storeDataAsync(updateInMemoryCache: Boolean = true, update: (T) -> T): Deferred<Any> {
     return cache.updateIfPresentAsync { cachedPayload ->
-      // Although it's odd to notify before the change is made, the single threaded nature of the blocking cache ensures
-      // nothing can read from it until this update completes.
-      asyncDataSubscriptionManager.notifyChange(providerId)
       val updatedPayload = storeFileCache(cachedPayload, update)
       if (updateInMemoryCache) updatedPayload else cachedPayload
     }
@@ -146,16 +148,13 @@ class PersistentCacheStore<T : MessageLite> private constructor(
   /** See [storeDataAsync]. Stores data and allows for a custom deferred result. */
   fun <V> storeDataWithCustomChannelAsync(updateInMemoryCache: Boolean = true, update: (T) -> Pair<T, V>): Deferred<V> {
     return cache.updateWithCustomChannelIfPresentAsync { cachedPayload ->
-      // Although it's odd to notify before the change is made, the single threaded nature of the blocking cache ensures
-      // nothing can read from it until this update completes.
-      asyncDataSubscriptionManager.notifyChange(providerId)
       val (updatedPayload, customResult) = storeFileCacheWithCustomChannel(cachedPayload, update)
       if (updateInMemoryCache) Pair(updatedPayload, customResult) else Pair(cachedPayload, customResult)
     }
   }
 
   /**
-   * Returns a [Deferred] indicating when the cache was cleared and its on-disk file, removed. This does not notify
+   * Returns a [Deferred] indicating when the cache was cleared and its on-disk file, removed. This does notify
    * subscribers.
    */
   fun clearCacheAsync(): Deferred<Any> {
@@ -172,10 +171,8 @@ class PersistentCacheStore<T : MessageLite> private constructor(
     }
   }
 
-  private fun deferLoadFileAndNotify() {
-    // Schedule another update to the cache that actually loads the file from memory. Record any potential failures.
+  private fun deferLoadFile() {
     cache.updateIfPresentAsync { cachePayload ->
-      asyncDataSubscriptionManager.notifyChange(providerId)
       loadFileCache(cachePayload)
     }.invokeOnCompletion {
       failureLock.withLock {

domain/build.gradle

@@ -66,12 +66,13 @@ dependencies {
       'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.2.2',
       'org.mockito:mockito-core:2.19.0',
       'org.robolectric:robolectric:4.3',
+      project(":testing"),
   )
   kapt(
-      'com.google.dagger:dagger-compiler:2.24'
+      'com.google.dagger:dagger-compiler:2.24',
   )
   kaptTest(
-      'com.google.dagger:dagger-compiler:2.24'
+      'com.google.dagger:dagger-compiler:2.24',
   )
   // TODO(#59): Avoid needing to expose data implementations to other modules in order to make Oppia symbols
   // sufficiently visible for generated Dagger code. This can be done more cleanly via Bazel since dependencies can be

domain/src/main/assets/sample_questions.json

@@ -352,7 +352,7 @@
         "defaultOutcome": {
           "dest": null,
           "feedback": {
-            "html": "",
+            "html": "Incorrect. Try again.",
             "content_id": "default_outcome"
           },
           "labelled_as_correct": false,

domain/src/main/java/org/oppia/domain/exploration/ExplorationProgress.kt

@@ -0,0 +1,85 @@
+package org.oppia.domain.exploration
+
+import org.oppia.app.model.Exploration
+import org.oppia.app.model.State
+import org.oppia.domain.state.StateDeck
+import org.oppia.domain.state.StateGraph
+
+// TODO(#186): Use an interaction repository to retrieve whether a specific ID corresponds to a terminal interaction.
+private const val TERMINAL_INTERACTION_ID = "EndExploration"
+
+/**
+ * Private class that encapsulates the mutable state of an exploration progress controller. This class is not
+ * thread-safe, so owning classes should ensure synchronized access. This class can exist across multiple exploration
+ * instances, but calling code is responsible for ensuring it is properly reset.
+ */
+internal class ExplorationProgress {
+  internal lateinit var currentExplorationId: String
+  internal lateinit var currentExploration: Exploration
+  internal var playStage = PlayStage.NOT_PLAYING
+  internal val stateGraph: StateGraph by lazy {
+    StateGraph(currentExploration.statesMap)
+  }
+  internal val stateDeck: StateDeck by lazy {
+    StateDeck(stateGraph.getState(currentExploration.initStateName), ::isTopStateTerminal)
+  }
+
+  /**
+   * Advances the current play stage to the specified stage, verifying that the transition is correct.
+   *
+   * Calling code should prevent this method from failing by checking state ahead of calling this method and providing
+   * more useful errors to UI calling code since errors thrown by this method will be more obscure. This method aims to
+   * ensure the internal state of the controller remains correct. This method is not meant to be covered in unit tests
+   * since none of the failures here should ever be exposed to controller callers.
+   */
+  internal fun advancePlayStageTo(nextPlayStage: PlayStage) {
+    when (nextPlayStage) {
+      PlayStage.NOT_PLAYING -> {
+        // All transitions to NOT_PLAYING are valid except itself. Stopping playing can happen at any time.
+        check(playStage != PlayStage.NOT_PLAYING) { "Cannot transition to NOT_PLAYING from NOT_PLAYING" }
+        playStage = nextPlayStage
+      }
+      PlayStage.LOADING_EXPLORATION -> {
+        // An exploration can only be requested to be loaded from the initial NOT_PLAYING stage.
+        check(playStage == PlayStage.NOT_PLAYING) { "Cannot transition to LOADING_EXPLORATION from $playStage" }
+        playStage = nextPlayStage
+      }
+      PlayStage.VIEWING_STATE -> {
+        // A state can be viewed after loading an exploration, after viewing another state, or after submitting an
+        // answer. It cannot be viewed without a loaded exploration.
+        check(playStage == PlayStage.LOADING_EXPLORATION
+            || playStage == PlayStage.VIEWING_STATE
+            || playStage == PlayStage.SUBMITTING_ANSWER) {
+          "Cannot transition to VIEWING_STATE from $playStage"
+        }
+        playStage = nextPlayStage
+      }
+      PlayStage.SUBMITTING_ANSWER -> {
+        // An answer can only be submitted after viewing a stage.
+        check(playStage == PlayStage.VIEWING_STATE) { "Cannot transition to SUBMITTING_ANSWER from $playStage" }
+        playStage = nextPlayStage
+      }
+    }
+  }
+
+  companion object {
+    internal fun isTopStateTerminal(state: State): Boolean {
+      return state.interaction.id == TERMINAL_INTERACTION_ID
+    }
+  }
+
+  /** Different stages in which the progress controller can exist. */
+  enum class PlayStage {
+    /** No exploration is currently being played. */
+    NOT_PLAYING,
+
+    /** An exploration is being prepared to be played. */
+    LOADING_EXPLORATION,
+
+    /** The controller is currently viewing a State. */
+    VIEWING_STATE,
+
+    /** The controller is in the process of submitting an answer. */
+    SUBMITTING_ANSWER
+  }
+}