BackupManager.java revision 4528186e0d65fc68ef0dd1941aa2ac8aefcd55a3
1/* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.app.backup; 18 19import android.app.backup.RestoreSession; 20import android.app.backup.IBackupManager; 21import android.app.backup.IRestoreSession; 22import android.content.Context; 23import android.os.RemoteException; 24import android.os.ServiceManager; 25import android.util.Log; 26 27/** 28 * BackupManager is the interface to the system's backup service. Applications 29 * simply instantiate one, and then use that instance to communicate with the 30 * backup infrastructure. 31 * <p> 32 * When an application has made changes to data which should be backed up, a 33 * call to {@link #dataChanged()} will notify the backup service. The system 34 * will then schedule a backup operation to occur in the near future. Repeated 35 * calls to {@link #dataChanged()} have no further effect until the backup 36 * operation actually occurs. 37 * <p> 38 * The backup operation itself begins with the system launching the 39 * {@link android.app.backup.BackupAgent} subclass declared in your manifest. See the 40 * documentation for {@link android.app.backup.BackupAgent} for a detailed description 41 * of how the backup then proceeds. 42 * <p> 43 * A simple implementation of a BackupAgent useful for backing up Preferences 44 * and files is available by using {@link android.app.backup.BackupHelperAgent}. 45 * <p> 46 * STOPSHIP: more documentation! 47 * <p> 48 * <b>XML attributes</b> 49 * <p> 50 * See {@link android.R.styleable#AndroidManifestApplication 51 * AndroidManifest.xml's application attributes} 52 * 53 * @attr ref android.R.styleable#AndroidManifestApplication_allowBackup 54 * @attr ref android.R.styleable#AndroidManifestApplication_backupAgent 55 * @attr ref 56 * android.R.styleable#AndroidManifestApplication_restoreNeedsApplication 57 * @attr ref android.R.styleable#AndroidManifestApplication_killAfterRestore 58 */ 59public class BackupManager { 60 private static final String TAG = "BackupManager"; 61 62 private Context mContext; 63 private static IBackupManager sService; 64 65 private static void checkServiceBinder() { 66 if (sService == null) { 67 sService = IBackupManager.Stub.asInterface( 68 ServiceManager.getService(Context.BACKUP_SERVICE)); 69 } 70 } 71 72 /** 73 * Constructs a BackupManager object through which the application can 74 * communicate with the Android backup system. 75 * 76 * @param context The {@link android.content.Context} that was provided when 77 * one of your application's {@link android.app.Activity Activities} 78 * was created. 79 */ 80 public BackupManager(Context context) { 81 mContext = context; 82 } 83 84 /** 85 * Notifies the Android backup system that your application wishes to back up 86 * new changes to its data. A backup operation using your application's 87 * {@link android.app.backup.BackupAgent} subclass will be scheduled when you call this method. 88 */ 89 public void dataChanged() { 90 checkServiceBinder(); 91 if (sService != null) { 92 try { 93 sService.dataChanged(mContext.getPackageName()); 94 } catch (RemoteException e) { 95 Log.d(TAG, "dataChanged() couldn't connect"); 96 } 97 } 98 } 99 100 /** 101 * Convenience method for callers who need to indicate that some other package 102 * needs a backup pass. This can be relevant in the case of groups of packages 103 * that share a uid, for example. 104 * 105 * This method requires that the application hold the "android.permission.BACKUP" 106 * permission if the package named in the argument is not the caller's own. 107 */ 108 public static void dataChanged(String packageName) { 109 checkServiceBinder(); 110 if (sService != null) { 111 try { 112 sService.dataChanged(packageName); 113 } catch (RemoteException e) { 114 Log.d(TAG, "dataChanged(pkg) couldn't connect"); 115 } 116 } 117 } 118 119 /** 120 * Begin the process of restoring data from backup. See the 121 * {@link android.app.backup.RestoreSession} class for documentation on that process. 122 */ 123 public RestoreSession beginRestoreSession() { 124 RestoreSession session = null; 125 checkServiceBinder(); 126 if (sService != null) { 127 try { 128 String transport = sService.getCurrentTransport(); 129 IRestoreSession binder = sService.beginRestoreSession(transport); 130 session = new RestoreSession(mContext, binder); 131 } catch (RemoteException e) { 132 Log.w(TAG, "beginRestoreSession() couldn't connect"); 133 } 134 } 135 return session; 136 } 137} 138