Bug 1517846 - Add missing docs for GeckoView.releaseSession() r=geckoview-reviewers,esawin#geckoview-reviewers
☠☠ backed out by 0c8548aec705 ☠ ☠
authorJames Willcox <snorp@snorp.net>
Tue, 15 Jan 2019 14:53:03 +0000
changeset 453933 6f5998401e959eaf8c60862cf1349a2e3d6a0c40
parent 453932 060ca330d2aa6eaef17750f20068f96d0bf75d7c
child 453934 65b6d0b670b410489153b2086d8dc1a1b66a3231
push id35380
push userdluca@mozilla.com
push dateTue, 15 Jan 2019 22:13:12 +0000
treeherdermozilla-central@a51d26029042 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersgeckoview-reviewers, esawin
bugs1517846
milestone66.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1517846 - Add missing docs for GeckoView.releaseSession() r=geckoview-reviewers,esawin#geckoview-reviewers Differential Revision: https://phabricator.services.mozilla.com/D15753
mobile/android/geckoview/src/main/java/org/mozilla/geckoview/GeckoView.java
--- a/mobile/android/geckoview/src/main/java/org/mozilla/geckoview/GeckoView.java
+++ b/mobile/android/geckoview/src/main/java/org/mozilla/geckoview/GeckoView.java
@@ -237,16 +237,24 @@ public class GeckoView extends FrameLayo
     }
 
     /* package */ void setActive(final boolean active) {
         if (mSession != null) {
             mSession.setActive(active);
         }
     }
 
+    /**
+     * Unsets the current session from this instance and returns it, if any. You must call
+     * this before {@link #setSession(GeckoSession)} if there is already an open session
+     * set for this instance.
+     *
+     * @return The {@link GeckoSession} that was set for this instance. May be null.
+     */
+    @UiThread
     public @Nullable GeckoSession releaseSession() {
         ThreadUtils.assertOnUiThread();
 
         if (mSession == null) {
             return null;
         }
 
         // Cover the view while we are not drawing to the surface.
@@ -274,36 +282,43 @@ public class GeckoView extends FrameLayo
         }
         mSession = null;
         mRuntime = null;
         return session;
     }
 
     /**
      * Attach a session to this view. The session should be opened before
-     * attaching.
+     * attaching. If this instance already has an open session, you must use
+     * {@link #releaseSession()} first, otherwise {@link IllegalStateException}
+     * will be thrown. This is to avoid potentially leaking the currently opened session.
      *
      * @param session The session to be attached.
+     * @throws IllegalArgumentException if an existing open session is already set.
      */
     public void setSession(@NonNull final GeckoSession session) {
         ThreadUtils.assertOnUiThread();
 
         if (!session.isOpen()) {
             throw new IllegalArgumentException("Session must be open before attaching");
         }
 
         setSession(session, session.getRuntime());
     }
 
     /**
      * Attach a session to this view. The session should be opened before
      * attaching or a runtime needs to be provided for automatic opening.
+     * If this instance already has an open session, you must use
+     * {@link #releaseSession()} first, otherwise {@link IllegalStateException}
+     * will be thrown. This is to avoid potentially leaking the currently opened session.
      *
      * @param session The session to be attached.
      * @param runtime The runtime to be used for opening the session.
+     * @throws IllegalArgumentException if an existing open session is already set.
      */
     public void setSession(@NonNull final GeckoSession session,
                            @Nullable final GeckoRuntime runtime) {
         ThreadUtils.assertOnUiThread();
 
         if (mSession != null && mSession.isOpen()) {
             throw new IllegalStateException("Current session is open");
         }