Javadocs, API adjustments

Author: GaryQian

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

@@ -951,21 +951,40 @@ public void setDynamicFeatureManager(@NonNull DynamicFeatureManager dynamicFeatu
     this.dynamicFeatureManager = dynamicFeatureManager;
   }
 
+  /**
+   * Called by dart's deferred load handler to request that a dart deferred library corresponding
+   * to loadingUnitId be downloaded (if necessary) and loaded into the dart vm.
+   *
+   * <p>This method delegates the task to DynamicFeatureManager, which handles the download and
+   * loading of the dart library and any assets.
+   *
+   * @param loadingUnitId The loadingUnitId is assigned during compile time by gen_snapshot and is
+   *                      automatically retrieved when loadLibrary() is called on a dart deferred
+   *                      library.
+   */
   @SuppressWarnings("unused")
   @UiThread
   public void RequestDartDeferredLibrary(int loadingUnitId) {
     dynamicFeatureManager.downloadDynamicFeature(loadingUnitId, null);
   }
 
   /**
-   * This should be called for every loading unit to be loaded into the dart isolate.
+   * Searches each of the provided paths for a valid dart shared library .so file and resolves
+   * symbols to load into the dart VM.
    *
-   * <p>abi, libName, and apkPaths are used together to search the installed apks for the desired
-   * .so library. If not found, soPath may be provided as a fallback if a pre-extracted .so exists,
-   * especially on older devices with libs compressed in the apk.
-   *
-   * <p>Successful loading of the dart library also completes the loadLibrary() future that
+   * <p>Successful loading of the dart library completes the future returned by loadLibrary() that
    * triggered the install/load process.
+   *
+   * @param loadingUnitId The loadingUnitId is assigned during compile time by gen_snapshot and is
+   *                      automatically retrieved when loadLibrary() is called on a dart deferred
+   *                      library. This is used to identify which dart deferred library the resolved
+   *                      correspond to.
+   *
+   * @param searchPaths   An array of paths in which to look for valid dart shared libraries. This
+   *                      supports paths within zipped apks as long as the apks are not compressed
+   *                      using the `path/to/apk.apk!path/inside/apk/lib.so` format. Paths will be
+   *                      tried first to last and ends when a library is sucessfully found. When the
+   *                      found library is invalid, no additional paths will be attempted.
    */
   @UiThread
   public void loadDartDeferredLibrary(
@@ -985,8 +1004,10 @@ private native void nativeLoadDartDeferredLibrary(
    * Specifies a new AssetManager that has access to the dynamic feature's assets in addition to the
    * base module's assets.
    *
-   * <p>assetBundlePath is the subdirectory that the flutter assets are stored in. The typical value
-   * is `flutter_assets`.
+   * @param assetManager    An android AssetManager that is able to access the newly downloaded assets.
+   *
+   * @param assetBundlePath The subdirectory that the flutter assets are stored in. The typical value
+   *                        is `flutter_assets`.
    */
   @UiThread
   public void updateAssetManager(
@@ -1001,19 +1022,33 @@ private native void nativeUpdateAssetManager(
       @NonNull AssetManager assetManager,
       @NonNull String assetBundlePath);
 
-  // Called when an install encounters a failure during the Android portion of installing a module.
-  // When transient is false, new attempts to install will automatically result in same error in
-  // dart before the request is passed to Android.
+  /**
+   * Indicates that a failure was encountered during the Android portion of downloading and installing
+   * a dynamic feature module.
+   *
+   * <p>This will inform dart that the future returned by loadLibrary() should complete with an error.
+   *
+   * @param loadingUnitId The loadingUnitId that corresponds to the dart deferred library that
+   *                      failed to install.
+   *
+   * @param moduleName    The name of the module that includes the loadingUnitId. This parameter is
+   *                      not necessary and used for logging purposes.
+   *
+   * @param error         The error message to display.
+   *
+   * @param isTransient   When isTransient is false, new attempts to install will automatically result in
+   *                      same error in dart before the request is passed to Android.
+   */
   @SuppressWarnings("unused")
   @UiThread
   public void dynamicFeatureInstallFailure(
-      @NonNull String moduleName, int loadingUnitId, @NonNull String error, boolean isTransient) {
+      int loadingUnitId, String moduleName, @NonNull String error, boolean isTransient) {
     ensureRunningOnMainThread();
-    nativeDynamicFeatureInstallFailure(moduleName, loadingUnitId, error, isTransient);
+    nativeDynamicFeatureInstallFailure(loadingUnitId, moduleName, error, isTransient);
   }
 
   private native void nativeDynamicFeatureInstallFailure(
-      @NonNull String moduleName, int loadingUnitId, @NonNull String error, boolean isTransient);
+      int loadingUnitId, String moduleName, @NonNull String error, boolean isTransient);
 
   // ----- End Dynamic Features Support ----
 

shell/platform/android/io/flutter/embedding/engine/dynamicfeatures/PlayStoreDynamicFeatureManager.java

@@ -58,8 +58,8 @@ public void onStateUpdate(SplitInstallSessionState state) {
                       state.sessionId(),
                       state.errorCode()));
               flutterJNI.dynamicFeatureInstallFailure(
-                  sessionIdToName.get(state.sessionId()),
                   sessionIdToLoadingUnitId.get(state.sessionId()),
+                  sessionIdToName.get(state.sessionId()),
                   "Module install failed with " + state.errorCode(),
                   true);
               sessionIdToName.remove(state.sessionId());
@@ -204,26 +204,26 @@ public void downloadDynamicFeature(int loadingUnitId, String moduleName) {
               switch (((SplitInstallException) exception).getErrorCode()) {
                 case SplitInstallErrorCode.NETWORK_ERROR:
                   flutterJNI.dynamicFeatureInstallFailure(
-                      moduleName,
                       loadingUnitId,
+                      moduleName,
                       String.format(
                           "Install of dynamic feature module \"%s\" failed with a network error",
                           moduleName),
                       true);
                   break;
                 case SplitInstallErrorCode.MODULE_UNAVAILABLE:
                   flutterJNI.dynamicFeatureInstallFailure(
-                      moduleName,
                       loadingUnitId,
+                      moduleName,
                       String.format(
                           "Install of dynamic feature module \"%s\" failed as it is unavailable",
                           moduleName),
                       false);
                   break;
                 default:
                   flutterJNI.dynamicFeatureInstallFailure(
-                      moduleName,
                       loadingUnitId,
+                      moduleName,
                       String.format(
                           "Install of dynamic feature module \"%s\" failed with error %d: %s",
                           moduleName,

shell/platform/android/platform_view_android_jni_impl.cc

@@ -521,8 +521,8 @@ static void LoadLoadingUnitFailure(intptr_t loading_unit_id,
 
 static void DynamicFeatureInstallFailure(JNIEnv* env,
                                          jobject obj,
-                                         jstring moduleName,
                                          jint jLoadingUnitId,
+                                         jstring moduleName,
                                          jstring jError,
                                          jboolean jTransient) {
   LoadLoadingUnitFailure(static_cast<intptr_t>(jLoadingUnitId),
@@ -599,6 +599,8 @@ static void LoadDartDeferredLibrary(JNIEnv* env,
   // TODO(garyq): fallback on soPath.
 }
 
+// TODO(garyq): persist additional asset resolvers by updating instead of
+// replacing with newly created asset_manager
 static void UpdateAssetManager(JNIEnv* env,
                                jobject obj,
                                jlong shell_holder,
@@ -786,7 +788,7 @@ bool RegisterApi(JNIEnv* env) {
       },
       {
           .name = "nativeDynamicFeatureInstallFailure",
-          .signature = "(Ljava/lang/String;ILjava/lang/String;Z)V",
+          .signature = "(ILjava/lang/String;Ljava/lang/String;Z)V",
           .fnPtr = reinterpret_cast<void*>(&DynamicFeatureInstallFailure),
       },
   };