Add IRestoreSession interface for the restore flow

Restore is a fairly complicated, somewhat stateful process, so we introduce
a new interface to encapsulate the various bits and pieces into a nicely
separable component.  In particular, this will make it much cleaner to
open and interrogate an expensive-to-construct transport and then reuse it
for the actual restore process itself.

Android.mk

@@ -83,6 +83,7 @@ LOCAL_SRC_FILES += \
 	core/java/android/app/IWallpaperService.aidl \
 	core/java/android/app/IWallpaperServiceCallback.aidl \
 	core/java/android/backup/IBackupManager.aidl \
+	core/java/android/backup/IRestoreSession.aidl \
 	core/java/android/bluetooth/IBluetoothA2dp.aidl \
 	core/java/android/bluetooth/IBluetoothDevice.aidl \
 	core/java/android/bluetooth/IBluetoothDeviceCallback.aidl \

core/java/android/backup/IBackupManager.aidl

@@ -16,6 +16,8 @@
 
 package android.backup;
 
+import android.backup.IRestoreSession;
+
 /**
  * Direct interface to the Backup Manager Service that applications invoke on.  The only
  * operation currently needed is a simple notification that the app has made changes to
@@ -60,4 +62,12 @@ interface IBackupManager {
      * @return The ID of the previously selected transport.
      */
     int selectBackupTransport(int transportID);
+
+    /**
+     * Begin a restore session with the given transport (which may differ from the
+     * currently-active backup transport).
+     *
+     * @return An interface to the restore session, or null on error.
+     */
+    IRestoreSession beginRestoreSession(int transportID);
 }

core/java/android/backup/IRestoreSession.aidl

@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.backup;
+
+import android.os.Bundle;
+
+/**
+ * Binder interface used by clients who wish to manage a restore operation.  Every
+ * method in this interface requires the android.permission.BACKUP permission.
+ *
+ * {@hide}
+ */
+interface IRestoreSession {
+    /**
+     * Ask the current transport what the available restore sets are.
+     *
+     * @return A bundle containing two elements:  an int array under the key
+     *   "tokens" whose entries are a transport-private identifier for each backup set;
+     *   and a String array under the key "names" whose entries are the user-meaningful
+     *   text corresponding to the backup sets at each index in the tokens array.
+     */
+    Bundle getAvailableRestoreSets();
+
+    /**
+     * Restore the given set onto the device, replacing the current data of any app
+     * contained in the restore set with the data previously backed up.
+     *
+     * @param token The token from {@link getAvailableRestoreSets()} corresponding to
+     *   the restore set that should be used.
+     */
+    int performRestore(int token);
+
+    /**
+     * End this restore session.  After this method is called, the IRestoreSession binder
+     * is no longer valid.
+     */
+    void endRestoreSession();
+}

core/java/com/android/internal/backup/AdbTransport.java

@@ -30,7 +30,7 @@ public class AdbTransport extends IBackupTransport.Stub {
     }
 
     // Restore handling
-    public Bundle getAvailableBackups() throws android.os.RemoteException {
+    public Bundle getAvailableRestoreSets() throws android.os.RemoteException {
         // !!! TODO: real implementation
         Bundle b = new Bundle();
         b.putIntArray("tokens", new int[0]);

core/java/com/android/internal/backup/GoogleTransport.java

@@ -28,7 +28,7 @@ public class GoogleTransport extends IBackupTransport.Stub {
     }
 
     // Restore handling
-    public Bundle getAvailableBackups() throws android.os.RemoteException {
+    public Bundle getAvailableRestoreSets() throws android.os.RemoteException {
         // !!! TODO: real implementation
         Bundle b = new Bundle();
         b.putIntArray("tokens", new int[0]);

core/java/com/android/internal/backup/IBackupTransport.aidl

@@ -64,12 +64,12 @@ interface IBackupTransport {
     /**
      * Get the set of backups currently available over this transport.
      *
-     * @return backups A bundle containing two elements:  an int array under the key
+     * @return A bundle containing two elements:  an int array under the key
      *   "tokens" whose entries are a transport-private identifier for each backup set;
      *   and a String array under the key "names" whose entries are the user-meaningful
      *   names corresponding to the backup sets at each index in the tokens array.
      **/
-    Bundle getAvailableBackups();
+    Bundle getAvailableRestoreSets();
 
     /**
      * Get the set of applications from a given backup image.

services/java/com/android/server/BackupManagerService.java

@@ -42,6 +42,7 @@ import android.util.Log;
 import android.util.SparseArray;
 
 import android.backup.IBackupManager;
+import android.backup.IRestoreSession;
 import android.backup.BackupManager;
 
 import com.android.internal.backup.AdbTransport;
@@ -388,6 +389,27 @@ class BackupManagerService extends IBackupManager.Stub {
         addPackageParticipantsLockedInner(packageName, allApps);
     }
 
+    // Instantiate the given transport
+    private IBackupTransport createTransport(int transportID) {
+        IBackupTransport transport = null;
+        switch (transportID) {
+        case BackupManager.TRANSPORT_ADB:
+            if (DEBUG) Log.v(TAG, "Initializing adb transport");
+            transport = new AdbTransport();
+            break;
+
+        case BackupManager.TRANSPORT_GOOGLE:
+            if (DEBUG) Log.v(TAG, "Initializing Google transport");
+            //!!! TODO: stand up the google backup transport for real here
+            transport = new GoogleTransport();
+            break;
+
+        default:
+            Log.e(TAG, "creating unknown transport " + transportID);
+        }
+        return transport;
+    }
+
     // ----- Back up a set of applications via a worker thread -----
 
     class PerformBackupThread extends Thread {
@@ -414,31 +436,8 @@ class BackupManagerService extends IBackupManager.Stub {
             if (DEBUG) Log.v(TAG, "Beginning backup of " + mQueue.size() + " targets");
 
             // stand up the current transport
-            IBackupTransport transport = null;
+            IBackupTransport transport = createTransport(mTransport);
-            switch (mTransport) {
+            if (transport == null) {
-            case BackupManager.TRANSPORT_ADB:
-                if (DEBUG) Log.v(TAG, "Initializing adb transport");
-                transport = new AdbTransport();
-                break;
-
-            case BackupManager.TRANSPORT_GOOGLE:
-                if (DEBUG) Log.v(TAG, "Initializing Google transport");
-                //!!! TODO: stand up the google backup transport here
-                transport = new GoogleTransport();
-                break;
-
-            default:
-                Log.e(TAG, "Perform backup with unknown transport " + mTransport);
-                // !!! TODO: re-enqueue the backup queue for later?
-                return;
-            }
-
-            try {
-                transport.startSession();
-            } catch (Exception e) {
-                Log.e(TAG, "Error starting backup session");
-                e.printStackTrace();
-                // !!! TODO: re-enqueue the backup queue for later?
                 return;
             }
 
@@ -612,6 +611,11 @@ class BackupManagerService extends IBackupManager.Stub {
         }
     }
 
+    // Hand off a restore session
+    public IRestoreSession beginRestoreSession(int transportID) {
+        mContext.enforceCallingPermission("android.permission.BACKUP", "beginRestoreSession");
+        return null;
+    }
 
 
     @Override