Merge "Address API feedback for new fragment APIs" into oc-dev

core/java/android/app/BackStackRecord.java

@@ -621,7 +621,7 @@ final class BackStackRecord extends FragmentTransaction implements
     }
 
     @Override
-    public FragmentTransaction postOnCommit(Runnable runnable) {
+    public FragmentTransaction runOnCommit(Runnable runnable) {
         if (runnable == null) {
             throw new IllegalArgumentException("runnable cannot be null");
         }

core/java/android/app/FragmentManager.java

@@ -451,6 +451,18 @@ public abstract class FragmentManager {
          */
         public void onFragmentAttached(FragmentManager fm, Fragment f, Context context) {}
 
+        /**
+         * Called right before the fragment's {@link Fragment#onCreate(Bundle)} method is called.
+         * This is a good time to inject any required dependencies or perform other configuration
+         * for the fragment.
+         *
+         * @param fm Host FragmentManager
+         * @param f Fragment changing state
+         * @param savedInstanceState Saved instance bundle from a previous instance
+         */
+        public void onFragmentPreCreated(FragmentManager fm, Fragment f,
+                Bundle savedInstanceState) {}
+
         /**
          * Called after the fragment has returned from the FragmentManager's call to
          * {@link Fragment#onCreate(Bundle)}. This will only happen once for any given
@@ -1218,6 +1230,7 @@ final class FragmentManagerImpl extends FragmentManager implements LayoutInflate
                         dispatchOnFragmentAttached(f, mHost.getContext(), false);
 
                         if (!f.mRetaining) {
+                            dispatchOnFragmentPreCreated(f, f.mSavedFragmentState, false);
                             f.performCreate(f.mSavedFragmentState);
                             dispatchOnFragmentCreated(f, f.mSavedFragmentState, false);
                         } else {
@@ -3274,6 +3287,25 @@ final class FragmentManagerImpl extends FragmentManager implements LayoutInflate
         }
     }
 
+    void dispatchOnFragmentPreCreated(Fragment f, Bundle savedInstanceState,
+            boolean onlyRecursive) {
+        if (mParent != null) {
+            FragmentManager parentManager = mParent.getFragmentManager();
+            if (parentManager instanceof FragmentManagerImpl) {
+                ((FragmentManagerImpl) parentManager)
+                        .dispatchOnFragmentPreCreated(f, savedInstanceState, true);
+            }
+        }
+        if (mLifecycleCallbacks == null) {
+            return;
+        }
+        for (Pair<FragmentLifecycleCallbacks, Boolean> p : mLifecycleCallbacks) {
+            if (!onlyRecursive || p.second) {
+                p.first.onFragmentPreCreated(this, f, savedInstanceState);
+            }
+        }
+    }
+
     void dispatchOnFragmentCreated(Fragment f, Bundle savedInstanceState, boolean onlyRecursive) {
         if (mParent != null) {
             FragmentManager parentManager = mParent.getFragmentManager();

core/java/android/app/FragmentTransaction.java

@@ -315,14 +315,22 @@ public abstract class FragmentTransaction {
      * in this transaction may have been optimized out due to the presence of a subsequent
      * fragment transaction in the batch.
      *
-     * <p><code>postOnCommit</code> may not be used with transactions
+     *
+     * <p>If a transaction is committed using {@link #commitAllowingStateLoss()} this runnable
+     * may be executed when the FragmentManager is in a state where new transactions may not
+     * be committed without allowing state loss.</p>
+     *
+     * <p><code>runOnCommit</code> may not be used with transactions
      * {@link #addToBackStack(String) added to the back stack} as Runnables cannot be persisted
-     * with back stack state.</p>
+     * with back stack state. {@link IllegalStateException} will be thrown if
+     * {@link #addToBackStack(String)} has been previously called for this transaction
+     * or if it is called after a call to <code>runOnCommit</code>.</p>
      *
      * @param runnable Runnable to add
      * @return this FragmentTransaction
+     * @throws IllegalStateException if {@link #addToBackStack(String)} has been called
      */
-    public abstract FragmentTransaction postOnCommit(Runnable runnable);
+    public abstract FragmentTransaction runOnCommit(Runnable runnable);
 
     /**
      * Schedules a commit of this transaction.  The commit does