comments

Author: goderbauer

shell/platform/android/io/flutter/embedding/android/FlutterActivity.java

@@ -64,6 +64,7 @@
  *   <li>Chooses Flutter's initial route.
  *   <li>Renders {@code Activity} transparently, if desired.
  *   <li>Offers hooks for subclasses to provide and configure a {@link FlutterEngine}.
+     <li>Save and restore instance state, see {@code shouldRestoreAndSaveState()};
  * </ul>
  *
  * <p><strong>Dart entrypoint, initial route, and app bundle path</strong>
@@ -956,6 +957,7 @@ public boolean shouldRestoreAndSaveState() {
       return getIntent().getBooleanExtra(EXTRA_ENABLE_STATE_RESTORATION, false);
     }
     if (getCachedEngineId() != null) {
+      // Prevent overwriting the existing state in a cached engine with restoration state.
       return false;
     }
     return true;

shell/platform/android/io/flutter/embedding/android/FlutterActivityAndFragmentDelegate.java

@@ -299,19 +299,19 @@ void onActivityCreated(@Nullable Bundle bundle) {
     Log.v(TAG, "onActivityCreated. Giving framework and plugins an opportunity to restore state.");
     ensureAlive();
 
-    Bundle pluginsBundle = null;
-    byte[] frameworkBundle = null;
+    Bundle pluginState = null;
+    byte[] frameworkState = null;
     if (bundle != null) {
-      pluginsBundle = bundle.getBundle(PLUGINS_RESTORATION_BUNDLE_KEY);
-      frameworkBundle = bundle.getByteArray(FRAMEWORK_RESTORATION_BUNDLE_KEY);
+      pluginState = bundle.getBundle(PLUGINS_RESTORATION_BUNDLE_KEY);
+      frameworkState = bundle.getByteArray(FRAMEWORK_RESTORATION_BUNDLE_KEY);
     }
 
     if (host.shouldRestoreAndSaveState()) {
-      flutterEngine.getRestorationChannel().setRestorationData(frameworkBundle);
+      flutterEngine.getRestorationChannel().setRestorationData(frameworkState);
     }
 
     if (host.shouldAttachEngineToActivity()) {
-      flutterEngine.getActivityControlSurface().onRestoreInstanceState(pluginsBundle);
+      flutterEngine.getActivityControlSurface().onRestoreInstanceState(pluginState);
     }
   }
 

shell/platform/android/io/flutter/embedding/engine/FlutterEngine.java

@@ -166,26 +166,33 @@ public FlutterEngine(
    * Same as {@link #FlutterEngine(Context, String[], boolean)} with added support for configuring
    * whether the engine will receive restoration data.
    *
-   * <p>When the engine is configured to receive restoration data {@code
-   * RestorationChannel.setRestorationData(byte[] data)} must be called to provide the restoration
-   * data. All requests to get restoration data from the framework will be blocked until that method
-   * is called. If the engine is configured to wait for restoration data, but it turns out later
-   * that no restoration data has been provided by the operating system, that method must still be
-   * called with null as an argument to indicate "no data".
+   * <p>The {@code waitForRestorationData} flag controls whether the engine delays responding to
+   * requests from the framework for restoration data until that data has been provided to the
+   * engine via {@code RestorationChannel.setRestorationData(byte[] data)}. If the flag is false,
+   * the framework may temporarily initialize itself to default values before the restoration data
+   * has been made available to the engine. Setting {@code waitForRestorationData} to true avoids
+   * this extra work by delaying initialization until the data is available.
+   *
+   * <p>When {@code waitForRestorationData} is set, {@code
+   * RestorationChannel.setRestorationData(byte[] data)} must be called at a later point in time.
+   * If it later turns out that no restoration data is available to restore the framework from,
+   * that method must still be called with null as an argument to indicate "no data".
+   *
+   * <p>If the framework never requests the restoration data, this flag has no effect.
    */
   public FlutterEngine(
       @NonNull Context context,
       @Nullable String[] dartVmArgs,
       boolean automaticallyRegisterPlugins,
-      boolean willProvideRestorationData) {
+      boolean waitForRestorationData) {
     this(
         context,
         FlutterLoader.getInstance(),
         new FlutterJNI(),
         new PlatformViewsController(),
         dartVmArgs,
         automaticallyRegisterPlugins,
-        willProvideRestorationData);
+        waitForRestorationData);
   }
 
   /**
@@ -252,7 +259,7 @@ public FlutterEngine(
       @NonNull PlatformViewsController platformViewsController,
       @Nullable String[] dartVmArgs,
       boolean automaticallyRegisterPlugins,
-      boolean willProvideRestorationData) {
+      boolean waitForRestorationData) {
     this.flutterJNI = flutterJNI;
     flutterLoader.startInitialization(context.getApplicationContext());
     flutterLoader.ensureInitializationComplete(context, dartVmArgs);
@@ -275,7 +282,7 @@ public FlutterEngine(
     mouseCursorChannel = new MouseCursorChannel(dartExecutor);
     navigationChannel = new NavigationChannel(dartExecutor);
     platformChannel = new PlatformChannel(dartExecutor);
-    restorationChannel = new RestorationChannel(dartExecutor, willProvideRestorationData);
+    restorationChannel = new RestorationChannel(dartExecutor, waitForRestorationData);
     settingsChannel = new SettingsChannel(dartExecutor);
     systemChannel = new SystemChannel(dartExecutor);
     textInputChannel = new TextInputChannel(dartExecutor);

shell/platform/android/io/flutter/embedding/engine/systemchannels/RestorationChannel.java

@@ -20,10 +20,10 @@
  *
  * <p>The channel can be configured to delay responding to the framework's request for restoration
  * data via {@code waitForRestorationData} until the engine-side has provided the data. This is
- * useful for use cases where the engine is pre-warmed at a point in the application's life cycle
- * where the operating system has not been made available to the engine yet. For example, if the
- * engine is pre-warmed as part of the Application before an Activity is created, this flag should
- * be set to true because Android will only provide the restoration data to the Activity.
+ * useful when the engine is pre-warmed at a point in the application's life cycle where the
+ * restoration data is not available yet. For example, if the engine is pre-warmed as part of the
+ * Application before an Activity is created, this flag should be set to true because Android will
+ * only provide the restoration data to the Activity during the onCreate callback.
  *
  * <p>The current restoration data provided by the framework can be read via {@code
  * getRestorationData()}.
@@ -46,20 +46,26 @@ public RestorationChannel(
   }
 
   /**
-   * Whether {@code setRestorationData} will be called to provide restoration data for the
-   * framework.
+   * Whether the channel delays responding to the framework's initial request for restoration data
+   * until {@code setRestorationData} has been called.
    *
-   * <p>When this is set to true, the channel will delay answering any requests for restoration data
-   * by the framework until {@code setRestorationData} has been called. It must be set to false if
-   * the engine never calls {@code setRestorationData}. If it has been set to true, but it later
-   * turns out that there is no restoration data, {@code setRestorationData} must be called with
-   * null.
+   * <p>If the engine never calls {@code setRestorationData} this flag must be set to false.
+   * If set to true, the engine must call {@code setRestorationData} either with the actual
+   * restoration data as argument or null if it turns out that there is no restoration data.
+   *
+   * <p>If the response to the framework's request for restoration data is not delayed until the
+   * data has been set via {@code setRestorationData}, the framework may intermittently initialize
+   * itself to default values until the restoration data has been made available. Setting this flag
+   * to true avoids that extra work.
    */
   public final boolean waitForRestorationData;
 
-  private MethodChannel channel;
+  // Holds the the most current restoration data which may have been provided by the engine
+  // via "setRestorationData" or by the framework via the method channel. This is the data the
+  // framework should be restored to in case the app is terminated.
   private byte[] restorationData;
-  private MethodChannel.Result pendingResult;
+  private MethodChannel channel;
+  private MethodChannel.Result pendingFrameworkRequest;
   private boolean engineHasProvidedData = false;
   private boolean frameworkHasRequestedData = false;
 
@@ -71,11 +77,14 @@ public byte[] getRestorationData() {
   /** Set the restoration data from which the framework will restore its state. */
   public void setRestorationData(byte[] data) {
     engineHasProvidedData = true;
-    if (pendingResult != null) {
-      pendingResult.success(data);
-      pendingResult = null;
+    if (pendingFrameworkRequest != null) {
+      // If their is a pending request from the framework, answer it.
+      pendingFrameworkRequest.success(data);
+      pendingFrameworkRequest = null;
       restorationData = data;
     } else if (frameworkHasRequestedData) {
+      // If the framework has previously received the engine's restoration data, push the new data
+      // directly to it.
       channel.invokeMethod(
           "push",
           data,
@@ -101,6 +110,7 @@ public void notImplemented() {
             }
           });
     } else {
+      // Otherwise, just cache the data until the framework asks for it.
       restorationData = data;
     }
   }
@@ -121,7 +131,6 @@ public void clearData() {
         public void onMethodCall(@NonNull MethodCall call, @NonNull MethodChannel.Result result) {
           final String method = call.method;
           final Object args = call.arguments;
-          Log.v(TAG, "Received '" + method + "' message.");
           switch (method) {
             case "put":
               restorationData = (byte[]) args;
@@ -132,7 +141,7 @@ public void onMethodCall(@NonNull MethodCall call, @NonNull MethodChannel.Result
               if (engineHasProvidedData || !waitForRestorationData) {
                 result.success(restorationData);
               } else {
-                pendingResult = result;
+                pendingFrameworkRequest = result;
               }
               break;
             default: