Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 9c3cee98 authored by Christopher Tate's avatar Christopher Tate
Browse files

API CHANGE: Backup/restore API changes requested by the API Council 

* @hide the android.app.backup.RestoreSession class and functionality

* Provide a public method on android.app.backup.BackupManager that apps
  can use to request a restore pass of their last-known-good dataset.
  The new method is called requestRestore().

* Provide the name of the package being restored, not just its ordinal,
  in the RestoreObserver's onUpdate() callback.

Part of bug #2545514

Change-Id: I9689bf8d6e2b808b4ee412424a36a835be0a5ca8
parent a3de7455

api/current.xml

+9 −42
Original line number Diff line number Diff line
@@ -27412,8 +27412,8 @@ 
<parameter name="context" type="android.content.Context">

</parameter>

</constructor>

<method name="beginRestoreSession"

 return="android.app.backup.RestoreSession"

<method name="dataChanged"

 return="void"

 abstract="false"

 native="false"

 synchronized="false"
@@ -27428,23 +27428,25 @@ 
 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 static="true"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

<parameter name="packageName" type="java.lang.String">

</parameter>

</method>

<method name="dataChanged"

 return="void"

<method name="requestRestore"

 return="int"

 abstract="false"

 native="false"

 synchronized="false"

 static="true"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

<parameter name="packageName" type="java.lang.String">

<parameter name="observer" type="android.app.backup.RestoreObserver">

</parameter>

</method>

</class>
@@ -27540,41 +27542,6 @@ 
>

</constructor>

</class>

<class name="RestoreSession"

 extends="java.lang.Object"

 abstract="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

<method name="endRestoreSession"

 return="void"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

</method>

<method name="restorePackage"

 return="int"

 abstract="false"

 native="false"

 synchronized="false"

 static="false"

 final="false"

 deprecated="not deprecated"

 visibility="public"

>

<parameter name="packageName" type="java.lang.String">

</parameter>

<parameter name="observer" type="android.app.backup.RestoreObserver">

</parameter>

</method>

</class>

<class name="SharedPreferencesBackupHelper"

 extends="android.app.backup.FileBackupHelperBase"

 abstract="false"

cmds/bmgr/src/com/android/commands/bmgr/Bmgr.java

+2 −2
Original line number Diff line number Diff line
@@ -278,8 +278,8 @@ public final class Bmgr { 
            System.out.println("restoreStarting: " + numPackages + " packages");

        }



        public void onUpdate(int nowBeingRestored) {

            System.out.println("onUpdate: " + nowBeingRestored);

        public void onUpdate(int nowBeingRestored, String currentPackage) {

            System.out.println("onUpdate: " + nowBeingRestored + " = " + currentPackage);

        }



        public void restoreFinished(int error) {

core/java/android/app/backup/BackupManager.java

+37 −0
Original line number Diff line number Diff line
@@ -114,9 +114,46 @@ public class BackupManager { 
        }

    }



    /**

     * Restore the calling application from backup.  The data will be restored from the

     * current backup dataset if the application has stored data there, or from

     * the dataset used during the last full device setup operation if the current

     * backup dataset has no matching data.  If no backup data exists for this application

     * in either source, a nonzero value will be returned.

     *

     * <p>If this method returns zero (meaning success), the OS will attempt to retrieve

     * a backed-up dataset from the remote transport, instantiate the application's

     * backup agent, and pass the dataset to the agent's

     * {@link android.app.backup.BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) onRestore()}

     * method.

     *

     * @return Zero on success; nonzero on error.

     */

    public int requestRestore(RestoreObserver observer) {

        int result = -1;

        checkServiceBinder();

        if (sService != null) {

            RestoreSession session = null;

            try {

                String transport = sService.getCurrentTransport();

                IRestoreSession binder = sService.beginRestoreSession(transport);

                session = new RestoreSession(mContext, binder);

                result = session.restorePackage(mContext.getPackageName(), observer);

            } catch (RemoteException e) {

                Log.w(TAG, "restoreSelf() unable to contact service");

            } finally {

                if (session != null) {

                    session.endRestoreSession();

                }

            }

        }

        return result;

    }



    /**

     * Begin the process of restoring data from backup.  See the

     * {@link android.app.backup.RestoreSession} class for documentation on that process.

     * @hide

     */

    public RestoreSession beginRestoreSession() {

        RestoreSession session = null;

core/java/android/app/backup/IRestoreObserver.aidl

+2 −1
Original line number Diff line number Diff line
@@ -37,8 +37,9 @@ interface IRestoreObserver { 
     *

     * @param nowBeingRestored The index, between 1 and the numPackages parameter

     *   to the restoreStarting() callback, of the package now being restored.

     * @param currentPackage The name of the package now being restored.

     */

    void onUpdate(int nowBeingRestored);

    void onUpdate(int nowBeingRestored, String curentPackage);



    /**

     * The restore operation has completed.

core/java/android/app/backup/RestoreObserver.java

+13 −5
Original line number Diff line number Diff line
@@ -16,6 +16,8 @@ 


package android.app.backup;



import java.lang.String;



/**

 * Callback class for receiving progress reports during a restore operation.  These

 * methods will all be called on your application's main thread.
@@ -32,17 +34,23 @@ public abstract class RestoreObserver { 


    /**

     * An indication of which package is being restored currently, out of the

     * total number provided in the restoreStarting() callback.  This method

     * is not guaranteed to be called.

     * total number provided in the {@link #restoreStarting(int)} callback.  This method

     * is not guaranteed to be called: if the transport is unable to obtain

     * data for one or more of the requested packages, no onUpdate() call will

     * occur for those packages.

     *

     * @param nowBeingRestored The index, between 1 and the numPackages parameter

     *   to the restoreStarting() callback, of the package now being restored.

     *   to the {@link #restoreStarting(int)} callback, of the package now being

     *   restored.  This may be non-monotonic; it is intended purely as a rough

     *   indication of the backup manager's progress through the overall restore process.

     * @param currentPackage The name of the package now being restored.

     */

    void onUpdate(int nowBeingRestored) {

    void onUpdate(int nowBeingRestored, String currentPackage) {

    }



    /**

     * The restore operation has completed.

     * The restore process has completed.  This method will always be called,

     * even if no individual package restore operations were attempted.

     *

     * @param error Zero on success; a nonzero error code if the restore operation

     *   as a whole failed.