Bug 1649529: Deprecate GeckoSession parcelability; r=geckoview-reviewers,agi

Note: These comments reference GeckoView 82 instead of GeckoView 83 because I
plan to uplift this to GeckoView 79. Ditto for the changelog entry.

Tests that use the parcelable functionality are flagged to ignore deprecation
warnings.

Differential Revision: https://phabricator.services.mozilla.com/D81768

mobile/android/geckoview/api.txt

@@ -690,7 +690,7 @@ package org.mozilla.geckoview {
     method @AnyThread public void loadUri(@NonNull Uri, @Nullable Uri, int, @Nullable Map<String,String>);
     method @UiThread public void open(@NonNull GeckoRuntime);
     method @AnyThread public void purgeHistory();
-    method @AnyThread public void readFromParcel(@NonNull Parcel);
+    method @Deprecated @AnyThread public void readFromParcel(@NonNull Parcel);
     method @UiThread public void releaseDisplay(@NonNull GeckoDisplay);
     method @AnyThread public void reload();
     method @AnyThread public void reload(int);
@@ -710,7 +710,7 @@ package org.mozilla.geckoview {
     method @UiThread public void setSelectionActionDelegate(@Nullable GeckoSession.SelectionActionDelegate);
     method @AnyThread public void stop();
     method @UiThread protected void setShouldPinOnScreen(boolean);
-    field public static final Parcelable.Creator<GeckoSession> CREATOR;
+    field @Deprecated public static final Parcelable.Creator<GeckoSession> CREATOR;
     field public static final int FINDER_DISPLAY_DIM_PAGE = 2;
     field public static final int FINDER_DISPLAY_DRAW_LINK_OUTLINE = 4;
     field public static final int FINDER_DISPLAY_HIGHLIGHT_ALL = 1;

mobile/android/geckoview/src/androidTest/java/org/mozilla/geckoview/test/BaseSessionTest.kt

@@ -107,6 +107,8 @@ open class BaseSessionTest(noErrorCollector: Boolean = false) {
     inline fun GeckoSession.toParcel(lambda: (Parcel) -> Unit) {
         val parcel = Parcel.obtain()
         try {
+            // Bug 1650108: Remove this
+            @Suppress("DEPRECATION")
             this.writeToParcel(parcel, 0)
 
             val pos = parcel.dataPosition()

mobile/android/geckoview/src/androidTest/java/org/mozilla/geckoview/test/SessionLifecycleTest.kt

@@ -79,6 +79,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         sessionRule.session.open()
     }
 
+    @Suppress("DEPRECATION")
     @Test fun readFromParcel() {
         val session = sessionRule.createOpenSession()
 
@@ -97,6 +98,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         sessionRule.session.waitForPageStop()
     }
 
+    @Suppress("DEPRECATION")
     @Ignore //Disable test for frequent failures Bug 1532186
     @Test(expected = IllegalStateException::class)
     fun readFromParcel_throwOnAlreadyOpen() {
@@ -108,6 +110,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         }
     }
 
+    @Suppress("DEPRECATION")
     @Test fun readFromParcel_canLoadPageAfterRead() {
         var newSession: GeckoSession? = null
 
@@ -119,6 +122,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         newSession!!.waitForPageStop()
     }
 
+    @Suppress("DEPRECATION")
     @Test fun readFromParcel_closedSession() {
         val session = sessionRule.createClosedSession()
 
@@ -132,6 +136,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         sessionRule.session.waitForPageStop()
     }
 
+    @Suppress("DEPRECATION")
     @Test fun readFromParcel_closedSessionAfterParceling() {
         val session = sessionRule.createOpenSession()
 
@@ -148,6 +153,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         sessionRule.session.waitForPageStop()
     }
 
+    @Suppress("DEPRECATION")
     @Test fun readFromParcel_closedSessionAfterReadParcel() {
         // disable test on opt for frequently failing Bug 1519591
         assumeThat(sessionRule.env.isDebugBuild, equalTo(true))
@@ -166,6 +172,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         sessionRule.session.waitForPageStop()
     }
 
+    @Suppress("DEPRECATION")
     @Test fun readFromParcel_closeOpenAndLoad() {
         var newSession: GeckoSession? = null
 
@@ -180,6 +187,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         newSession!!.waitForPageStop()
     }
 
+    @Suppress("DEPRECATION")
     @Test fun readFromParcel_allowCallsBeforeUnparceling() {
         val newSession = sessionRule.createClosedSession()
 
@@ -192,6 +200,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         newSession.waitForPageStops(2)
     }
 
+    @Suppress("DEPRECATION")
     @Test fun readFromParcel_chained() {
         var session1: GeckoSession? = null
         var session2: GeckoSession? = null
@@ -211,6 +220,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         session3!!.waitForPageStop()
     }
 
+    @Suppress("DEPRECATION")
     @NullDelegate(GeckoSession.NavigationDelegate::class)
     @ClosedSessionAtStart
     @Test fun readFromParcel_moduleUpdated() {
@@ -244,6 +254,7 @@ class SessionLifecycleTest : BaseSessionTest() {
                    onLocationCount, equalTo(1))
     }
 
+    @Suppress("DEPRECATION")
     @Test fun readFromParcel_focusedInput() {
         // When an input is focused, make sure SessionTextInput is still active after transferring.
         mainSession.loadTestPath(INPUTS_PATH)
@@ -415,6 +426,7 @@ class SessionLifecycleTest : BaseSessionTest() {
         sessionRule.waitForPageStop()
     }
 
+    @Suppress("DEPRECATION")
     @Ignore // Bug 1533934 - disabled createFromParcel on pgo for frequent failures
     @Test fun createFromParcel() {
         val session = sessionRule.createOpenSession()

mobile/android/geckoview/src/main/java/org/mozilla/geckoview/GeckoSession.java

@@ -1289,12 +1289,22 @@ public class GeckoSession implements Parcelable {
         session.mWindow = null;
     }
 
+    /**
+     * @deprecated Use {@link ProgressDelegate#onSessionStateChange(GeckoSession, GeckoSession.SessionState)} and
+     * {@link #restoreState} instead. This method will be removed in GeckoView 82.
+     */
+    @Deprecated // Bug 1650108
     @Override // Parcelable
     @AnyThread
     public int describeContents() {
         return 0;
     }
 
+    /**
+     * @deprecated Use {@link ProgressDelegate#onSessionStateChange(GeckoSession, GeckoSession.SessionState)} and
+     * {@link #restoreState} instead. This method will be removed in GeckoView 82.
+     */
+    @Deprecated // Bug 1650108
     @Override // Parcelable
     @AnyThread
     public void writeToParcel(final Parcel out, final int flags) {
@@ -1304,6 +1314,11 @@ public class GeckoSession implements Parcelable {
     }
 
     // AIDL code may call readFromParcel even though it's not part of Parcelable.
+    /**
+     * @deprecated Use {@link ProgressDelegate#onSessionStateChange(GeckoSession, GeckoSession.SessionState)} and
+     * {@link #restoreState} instead. This method will be removed in GeckoView 82.
+     */
+    @Deprecated // Bug 1650108
     @AnyThread
     @SuppressWarnings("checkstyle:javadocmethod")
     public void readFromParcel(final @NonNull Parcel source) {
@@ -1317,6 +1332,11 @@ public class GeckoSession implements Parcelable {
         transferFrom(window, settings, id);
     }
 
+    /**
+     * @deprecated Use {@link ProgressDelegate#onSessionStateChange(GeckoSession, GeckoSession.SessionState)} and
+     * {@link #restoreState} instead. This field will be removed in GeckoView 82.
+     */
+    @Deprecated // Bug 1650108
     public static final Creator<GeckoSession> CREATOR = new Creator<GeckoSession>() {
         @Override
         @AnyThread

mobile/android/geckoview/src/main/java/org/mozilla/geckoview/doc-files/CHANGELOG.md

@@ -34,6 +34,8 @@ exclude: true
 - Added [`ProfilerController`][79.4], accessible via [`GeckoRuntime.getProfilerController`][79.5]
 to allow adding gecko profiler markers.
 ([bug 1624993]({{bugzilla}}1624993))
+- ⚠️ Deprecated `Parcelable` support in `GeckoSession` with the intention of removing
+  in GeckoView v82. ([bug 1649529]({{bugzilla}}1649529))
 
 [79.1]: {{javadoc_uri}}/WebExtension.TabDelegate.html#onOpenOptionsPage-org.mozilla.geckoview.WebExtension-
 [79.2]: {{javadoc_uri}}/WebNotification.html#source
@@ -740,4 +742,4 @@ to allow adding gecko profiler markers.
 [65.24]: {{javadoc_uri}}/CrashReporter.html#sendCrashReport-android.content.Context-android.os.Bundle-java.lang.String-
 [65.25]: {{javadoc_uri}}/GeckoResult.html
 
-[api-version]: a53322bd27a9a8968a3fbbc7e44ebefdd9a49ef8
+[api-version]: 3bf9118a008a2a172964a13ba3f79ff59fe1f77e