Point old plugin registry accessors to new embedding plugin accessors. (flutter#44225) (flutter#13739)

Author: matthew-carroll

shell/platform/android/io/flutter/embedding/engine/plugins/FlutterPlugin.java

@@ -50,7 +50,17 @@
  * be retrieved through a {@link Context}. Developers can access the application context via
  * {@link FlutterPluginBinding#getApplicationContext()}.
  * <p>
- * TODO(mattcarroll): explain ActivityAware when it's added to the new plugin API surface.
+ * Some plugins may require access to the {@code Activity} that is displaying a Flutter experience,
+ * or may need to react to {@code Activity} lifecycle events, e.g., {@code onCreate()},
+ * {@code onStart()}, {@code onResume()}, {@code onPause()}, {@code onStop()}, {@code onDestroy()}.
+ * Any such plugin should implement
+ * {@link io.flutter.embedding.engine.plugins.activity.ActivityAware} in addition to implementing
+ * {@code FlutterPlugin}. {@code ActivityAware} provides callback hooks that expose access to an
+ * associated {@code Activity} and its {@code Lifecycle}. All plugins must respect the possibility
+ * that a Flutter experience may never be associated with an {@code Activity}, e.g., when Flutter
+ * is used for background behavior. Additionally, all plugins must respect that a {@code Activity}s
+ * may come and go over time, thus requiring plugins to cleanup resources and recreate those
+ * resources as the {@code Activity} comes and goes.
  */
 public interface FlutterPlugin {
 

shell/platform/android/io/flutter/embedding/engine/plugins/activity/ActivityPluginBinding.java

@@ -14,6 +14,10 @@
 /**
  * Binding that gives {@link ActivityAware} plugins access to an associated {@link Activity} and
  * the {@link Activity}'s lifecycle methods.
+ * <p>
+ * To obtain an instance of an {@code ActivityPluginBinding} in a Flutter plugin, implement the
+ * {@link ActivityAware} interface. A binding is provided in {@link ActivityAware#onAttachedToActivity(ActivityPluginBinding)}
+ * and {@link ActivityAware#onReattachedToActivityForConfigChanges(ActivityPluginBinding)}.
  */
 public interface ActivityPluginBinding {
 

shell/platform/android/io/flutter/plugin/common/PluginRegistry.java

@@ -7,6 +7,10 @@
 import android.app.Activity;
 import android.content.Context;
 import android.content.Intent;
+
+import io.flutter.embedding.engine.plugins.FlutterPlugin;
+import io.flutter.embedding.engine.plugins.activity.ActivityAware;
+import io.flutter.embedding.engine.plugins.activity.ActivityPluginBinding;
 import io.flutter.plugin.platform.PlatformViewRegistry;
 import io.flutter.view.FlutterNativeView;
 import io.flutter.view.FlutterView;
@@ -59,6 +63,9 @@ public interface PluginRegistry {
 
     /**
      * Receiver of registrations from a single plugin.
+     *
+     * <p>This registrar is for Flutter's v1 embedding. For instructions on migrating a plugin from
+     * Flutter's v1 Android embedding to v2, visit http://flutter.dev/go/android-plugin-migration
      */
     interface Registrar {
         /**
@@ -73,43 +80,92 @@ interface Registrar {
          * <p>When there is no foreground activity in the application, this
          * will return null. If a {@link Context} is needed, use context() to
          * get the application's context.</p>
+         *
+         * <p>This registrar is for Flutter's v1 embedding. To access an {@code Activity} from a
+         * plugin using the v2 embedding, see {@link ActivityPluginBinding#getActivity()}. To obtain
+         * an instance of an {@link ActivityPluginBinding} in a Flutter plugin, implement the
+         * {@link ActivityAware} interface. A binding is provided in {@link ActivityAware#onAttachedToActivity(ActivityPluginBinding)}
+         * and {@link ActivityAware#onReattachedToActivityForConfigChanges(ActivityPluginBinding)}.
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
          */
         Activity activity();
 
         /**
          * Returns the {@link android.app.Application}'s {@link Context}.
+         *
+         * <p>This registrar is for Flutter's v1 embedding. To access a {@code Context} from a
+         * plugin using the v2 embedding, see {@link FlutterPlugin.FlutterPluginBinding#getApplicationContext()}
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
          */
         Context context();
 
         /**
-        * Returns the active {@link Context}.
-        *
-        * @return the current {@link #activity() Activity}, if not null, otherwise the {@link #context() Application}.
-        */
+         * Returns the active {@link Context}.
+         *
+         * <p>This registrar is for Flutter's v1 embedding. In the v2 embedding, there is no
+         * concept of an "active context". Either use the application {@code Context} or an attached
+         * {@code Activity}. See {@link #context()} and {@link #activity()} for more details.
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
+         *
+         * @return the current {@link #activity() Activity}, if not null, otherwise the {@link #context() Application}.
+         */
         Context activeContext();
 
         /**
          * Returns a {@link BinaryMessenger} which the plugin can use for
          * creating channels for communicating with the Dart side.
+         *
+         * <p>This registrar is for Flutter's v1 embedding. To access a {@code BinaryMessenger} from
+         * a plugin using the v2 embedding, see {@link FlutterPlugin.FlutterPluginBinding#getBinaryMessenger()}
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
          */
         BinaryMessenger messenger();
 
         /**
          * Returns a {@link TextureRegistry} which the plugin can use for
          * managing backend textures.
+         *
+         * <p>This registrar is for Flutter's v1 embedding. To access a {@code TextureRegistry} from
+         * a plugin using the v2 embedding, see {@link FlutterPlugin.FlutterPluginBinding#getTextureRegistry()}
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
          */
         TextureRegistry textures();
 
         /**
          * Returns the application's {@link PlatformViewRegistry}.
          *
          * Plugins can use the platform registry to register their view factories.
+         *
+         * <p>This registrar is for Flutter's v1 embedding. To access a {@code PlatformViewRegistry}
+         * from a plugin using the v2 embedding, see {@link FlutterPlugin.FlutterPluginBinding#getPlatformViewRegistry()}
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
          */
         PlatformViewRegistry platformViewRegistry();
 
         /**
          * Returns the {@link FlutterView} that's instantiated by this plugin's
          * {@link #activity() activity}.
+         *
+         * <p>This registrar is for Flutter's v1 embedding. The {@link FlutterView} referenced by
+         * this method does not exist in the v2 embedding. Additionally, no {@code View} is exposed
+         * to any plugins in the v2 embedding. Platform views can access their containing
+         * {@code View} using the platform views APIs. If you have a use-case that absolutely
+         * requires a plugin to access an Android {@code View}, please file a ticket on GitHub.
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
          */
         FlutterView view();
 
@@ -119,6 +175,8 @@ interface Registrar {
          * The returned file name can be used to access the asset in the APK
          * through the {@link android.content.res.AssetManager} API.
          *
+         * TODO(mattcarroll): point this method towards new lookup method.
+         *
          * @param asset the name of the asset. The name can be hierarchical
          * @return      the filename to be used with {@link android.content.res.AssetManager}
          */
@@ -129,6 +187,8 @@ interface Registrar {
          * specified packageName. The returned file name can be used to access
          * the asset in the APK through the {@link android.content.res.AssetManager} API.
          *
+         * TODO(mattcarroll): point this method towards new lookup method.
+         *
          * @param asset       the name of the asset. The name can be hierarchical
          * @param packageName the name of the package from which the asset originates
          * @return            the file name to be used with {@link android.content.res.AssetManager}
@@ -148,6 +208,12 @@ interface Registrar {
          *
          * <p>Overwrites any previously published value.</p>
          *
+         * <p>This registrar is for Flutter's v1 embedding. The concept of publishing values from
+         * plugins is not supported in the v2 embedding.
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
+         *
          * @param value the value, possibly null.
          * @return this {@link Registrar}.
          */
@@ -158,6 +224,12 @@ interface Registrar {
          * calls to {@code Activity#onRequestPermissionsResult(int, String[], int[])}
          * or {@code android.support.v4.app.ActivityCompat.OnRequestPermissionsResultCallback#onRequestPermissionsResult(int, String[], int[])}.
          *
+         * <p>This registrar is for Flutter's v1 embedding. To listen for permission results in the
+         * v2 embedding, use {@link ActivityPluginBinding#addRequestPermissionsResultListener(RequestPermissionsResultListener)}.
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
+         *
          * @param listener a {@link RequestPermissionsResultListener} callback.
          * @return this {@link Registrar}.
          */
@@ -167,6 +239,12 @@ interface Registrar {
          * Adds a callback allowing the plugin to take part in handling incoming
          * calls to {@link Activity#onActivityResult(int, int, Intent)}.
          *
+         * <p>This registrar is for Flutter's v1 embedding. To listen for {@code Activity} results
+         * in the v2 embedding, use {@link ActivityPluginBinding#addActivityResultListener(ActivityResultListener)}.
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
+         *
          * @param listener an {@link ActivityResultListener} callback.
          * @return this {@link Registrar}.
          */
@@ -176,6 +254,12 @@ interface Registrar {
          * Adds a callback allowing the plugin to take part in handling incoming
          * calls to {@link Activity#onNewIntent(Intent)}.
          *
+         * <p>This registrar is for Flutter's v1 embedding. To listen for new {@code Intent}s in the
+         * v2 embedding, use {@link ActivityPluginBinding#addOnNewIntentListener(NewIntentListener)}.
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
+         *
          * @param listener a {@link NewIntentListener} callback.
          * @return this {@link Registrar}.
          */
@@ -185,6 +269,12 @@ interface Registrar {
          * Adds a callback allowing the plugin to take part in handling incoming
          * calls to {@link Activity#onUserLeaveHint()}.
          *
+         * <p>This registrar is for Flutter's v1 embedding. To listen for leave hints in the
+         * v2 embedding, use {@link ActivityPluginBinding#addOnUserLeaveHintListener(UserLeaveHintListener)}.
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
+         *
          * @param listener a {@link UserLeaveHintListener} callback.
          * @return this {@link Registrar}.
          */
@@ -194,9 +284,24 @@ interface Registrar {
          * Adds a callback allowing the plugin to take part in handling incoming
          * calls to {@link Activity#onDestroy()}.
          *
+         * <p>This registrar is for Flutter's v1 embedding. The concept of {@code View}
+         * destruction does not exist in the v2 embedding. However, plugins in the v2 embedding
+         * can respond to {@link ActivityAware#onDetachedFromActivityForConfigChanges()} and
+         * {@link ActivityAware#onDetachedFromActivity()}, which indicate the loss of a visual
+         * context for the running Flutter experience. Developers should implement
+         * {@link ActivityAware} for their {@link FlutterPlugin} if such callbacks are needed. Also,
+         * plugins can respond to
+         * {@link FlutterPlugin#onDetachedFromEngine(FlutterPlugin.FlutterPluginBinding)}, which
+         * indicates that the given plugin has been completely disconnected from the associated
+         * Flutter experience and should clean up any resources.
+         *
+         * <p>For instructions on migrating a plugin from Flutter's v1 Android embedding to v2,
+         * visit http://flutter.dev/go/android-plugin-migration
+         *
          * @param listener a {@link ViewDestroyListener} callback.
          * @return this {@link Registrar}.
          */
+        // TODO(amirh): Add a line in the javadoc above that points to a Platform Views website guide when one is available (but not a website API doc)
         Registrar addViewDestroyListener(ViewDestroyListener listener);
     }