Move initialization into FlutterEngine

ci/licenses_golden/licenses_flutter

@@ -597,6 +597,10 @@ FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/Flutte
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/dart/DartExecutor.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/dart/DartMessenger.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/dart/PlatformMessageHandler.java
+FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/loader/FlutterLoader.java
+FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/loader/ResourceCleaner.java
+FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/loader/ResourceExtractor.java
+FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/loader/ResourcePaths.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/plugins/FlutterPlugin.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/plugins/PluginRegistry.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/embedding/engine/plugins/activity/ActivityAware.java
@@ -666,9 +670,6 @@ FILE: ../../../flutter/shell/platform/android/io/flutter/view/FlutterMain.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/view/FlutterNativeView.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/view/FlutterRunArguments.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/view/FlutterView.java
-FILE: ../../../flutter/shell/platform/android/io/flutter/view/ResourceCleaner.java
-FILE: ../../../flutter/shell/platform/android/io/flutter/view/ResourceExtractor.java
-FILE: ../../../flutter/shell/platform/android/io/flutter/view/ResourcePaths.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/view/TextureRegistry.java
 FILE: ../../../flutter/shell/platform/android/io/flutter/view/VsyncWaiter.java
 FILE: ../../../flutter/shell/platform/android/library_loader.cc

shell/platform/android/BUILD.gn

@@ -149,6 +149,10 @@ android_java_sources = [
   "io/flutter/embedding/engine/dart/DartExecutor.java",
   "io/flutter/embedding/engine/dart/DartMessenger.java",
   "io/flutter/embedding/engine/dart/PlatformMessageHandler.java",
+  "io/flutter/embedding/engine/loader/FlutterLoader.java",
+  "io/flutter/embedding/engine/loader/ResourceCleaner.java",
+  "io/flutter/embedding/engine/loader/ResourceExtractor.java",
+  "io/flutter/embedding/engine/loader/ResourcePaths.java",
   "io/flutter/embedding/engine/plugins/FlutterPlugin.java",
   "io/flutter/embedding/engine/plugins/PluginRegistry.java",
   "io/flutter/embedding/engine/plugins/activity/ActivityAware.java",
@@ -218,9 +222,6 @@ android_java_sources = [
   "io/flutter/view/FlutterNativeView.java",
   "io/flutter/view/FlutterRunArguments.java",
   "io/flutter/view/FlutterView.java",
-  "io/flutter/view/ResourceCleaner.java",
-  "io/flutter/view/ResourceExtractor.java",
-  "io/flutter/view/ResourcePaths.java",
   "io/flutter/view/TextureRegistry.java",
   "io/flutter/view/VsyncWaiter.java",
 ]

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

@@ -14,6 +14,7 @@
 
 import io.flutter.Log;
 import io.flutter.embedding.engine.dart.DartExecutor;
+import io.flutter.embedding.engine.loader.FlutterLoader;
 import io.flutter.embedding.engine.plugins.PluginRegistry;
 import io.flutter.embedding.engine.plugins.activity.ActivityControlSurface;
 import io.flutter.embedding.engine.plugins.broadcastreceiver.BroadcastReceiverControlSurface;
@@ -34,28 +35,38 @@
 
 /**
  * A single Flutter execution environment.
- *
- * WARNING: THIS CLASS IS EXPERIMENTAL. DO NOT SHIP A DEPENDENCY ON THIS CODE.
- * IF YOU USE IT, WE WILL BREAK YOU.
- *
- * A {@code FlutterEngine} can execute in the background, or it can be rendered to the screen by
- * using the accompanying {@link FlutterRenderer}.  Rendering can be started and stopped, thus
- * allowing a {@code FlutterEngine} to move from UI interaction to data-only processing and then
- * back to UI interaction.
- *
+ * <p>
+ * WARNING: THIS CLASS IS CURRENTLY EXPERIMENTAL. USE AT YOUR OWN RISK.
+ * <p>
+ * The {@code FlutterEngine} is the container through which Dart code can be run in an Android
+ * application.
+ * <p>
+ * Dart code in a {@code FlutterEngine} can execute in the background, or it can be render to the
+ * screen by using the accompanying {@link FlutterRenderer} and Dart code using the Flutter
+ * framework on the Dart side. Rendering can be started and stopped, thus allowing a
+ * {@code FlutterEngine} to move from UI interaction to data-only processing and then back to UI
+ * interaction.
+ * <p>
  * Multiple {@code FlutterEngine}s may exist, execute Dart code, and render UIs within a single
  * Android app.
- *
- * To start running Flutter within this {@code FlutterEngine}, get a reference to this engine's
- * {@link DartExecutor} and then use {@link DartExecutor#executeDartEntrypoint(DartExecutor.DartEntrypoint)}.
- * The {@link DartExecutor#executeDartEntrypoint(DartExecutor.DartEntrypoint)} method must not be
+ * <p>
+ * To start running Dart and/or Flutter within this {@code FlutterEngine}, get a reference to this
+ * engine's {@link DartExecutor} and then use
+ * {@link DartExecutor#executeDartEntrypoint(DartExecutor.DartEntrypoint)}. The
+ * {@link DartExecutor#executeDartEntrypoint(DartExecutor.DartEntrypoint)} method must not be
  * invoked twice on the same {@code FlutterEngine}.
- *
+ * <p>
  * To start rendering Flutter content to the screen, use {@link #getRenderer()} to obtain a
- * {@link FlutterRenderer} and then attach a {@link RenderSurface}.  Consider using
- * a {@link io.flutter.embedding.android.FlutterView} as a {@link RenderSurface}.
+ * {@link FlutterRenderer} and then attach a {@link RenderSurface}.  Consider using a
+ * {@link io.flutter.embedding.android.FlutterView} as a {@link RenderSurface}.
+ * <p>
+ * Instatiating the first {@code FlutterEngine} per process will also load the Flutter engine's
+ * native library and start the Dart VM. Subsequent {@code FlutterEngine}s will run on the same VM
+ * instance but will have their own Dart <a
+ * href="https://api.dartlang.org/stable/dart-isolate/Isolate-class.html">Isolate</a> when the
+ * {@link DartExecutor} is run. Each Isolate is a self-contained Dart environment and cannot
+ * communicate with each other except via Isolate ports.
  */
-// TODO(mattcarroll): re-evaluate system channel APIs - some are not well named or differentiated
 public class FlutterEngine implements LifecycleOwner {
   private static final String TAG = "FlutterEngine";
 
@@ -110,24 +121,35 @@ public void onPreEngineRestart() {
 
   /**
    * Constructs a new {@code FlutterEngine}.
-   *
-   * {@code FlutterMain.startInitialization} must be called before constructing a {@code FlutterEngine}
-   * to load the native libraries needed to attach to JNI.
-   *
+   * <p>
    * A new {@code FlutterEngine} does not execute any Dart code automatically. See
    * {@link #getDartExecutor()} and {@link DartExecutor#executeDartEntrypoint(DartExecutor.DartEntrypoint)}
    * to begin executing Dart code within this {@code FlutterEngine}.
-   *
+   * <p>
    * A new {@code FlutterEngine} will not display any UI until a
    * {@link RenderSurface} is registered. See
    * {@link #getRenderer()} and {@link FlutterRenderer#startRenderingToSurface(RenderSurface)}.
-   *
+   * <p>
    * A new {@code FlutterEngine} does not come with any Flutter plugins attached. To attach plugins,
    * see {@link #getPlugins()}.
-   *
+   * <p>
    * A new {@code FlutterEngine} does come with all default system channels attached.
+   * <p>
+   * The first {@code FlutterEngine} instance constructed per process will also load the Flutter
+   * native library and start a Dart VM.
+   * <p>
+   * In order to pass Dart VM initialization arguments (see {@link io.flutter.embedding.engine.FlutterShellArgs})
+   * when creating the VM, manually set the initialization arguments by calling {@link FlutterLoader#startInitialization(Context)}
+   * and {@link FlutterLoader#ensureInitializationComplete(Context, String[])}.
    */
   public FlutterEngine(@NonNull Context context) {
+    this(context, FlutterLoader.getInstance());
+  }
+
+  /* package */ FlutterEngine(@NonNull Context context, @NonNull FlutterLoader flutterLoader) {
+    flutterLoader.startInitialization(context);
+    flutterLoader.ensureInitializationComplete(context, null);
+
     this.flutterJNI = new FlutterJNI();
     flutterJNI.addEngineLifecycleListener(engineLifecycleListener);
     attachToJni();
@@ -174,9 +196,9 @@ private boolean isAttachedToJni() {
   }
 
   /**
-   * Cleans up all components within this {@code FlutterEngine} and then detaches from Flutter's
-   * native implementation.
-   *
+   * Cleans up all components within this {@code FlutterEngine} and destroys the associated Dart
+   * Isolate. All state held by the Dart Isolate, such as the Flutter Elements tree, is lost.
+   * <p>
    * This {@code FlutterEngine} instance should be discarded after invoking this method.
    */
   public void destroy() {
@@ -206,10 +228,10 @@ public void removeEngineLifecycleListener(@NonNull EngineLifecycleListener liste
 
   /**
    * The Dart execution context associated with this {@code FlutterEngine}.
-   *
+   * <p>
    * The {@link DartExecutor} can be used to start executing Dart code from a given entrypoint.
    * See {@link DartExecutor#executeDartEntrypoint(DartExecutor.DartEntrypoint)}.
-   *
+   * <p>
    * Use the {@link DartExecutor} to connect any desired message channels and method channels
    * to facilitate communication between Android and Dart/Flutter.
    */
@@ -220,7 +242,7 @@ public DartExecutor getDartExecutor() {
 
   /**
    * The rendering system associated with this {@code FlutterEngine}.
-   *
+   * <p>
    * To render a Flutter UI that is produced by this {@code FlutterEngine}'s Dart code, attach
    * a {@link RenderSurface} to this
    * {@link FlutterRenderer}.