BackupAgent

Class Overview

Provides the central interface between an application and Android's data backup infrastructure. An application that wishes to participate in the backup and restore mechanism will declare a subclass of BackupAgent, implement the onBackup() and onRestore() methods, and provide the name of its backup agent class in its AndroidManifest.xml file via the <application> tag's android:backupAgent attribute.

Basic Operation

When the application makes changes to data that it wishes to keep backed up, it should call the BackupManager.dataChanged() method. This notifies the Android Backup Manager that the application needs an opportunity to update its backup image. The Backup Manager, in turn, schedules a backup pass to be performed at an opportune time.

Restore operations are typically performed only when applications are first installed on a device. At that time, the operating system checks to see whether there is a previously-saved data set available for the application being installed, and if so, begins an immediate restore pass to deliver the backup data as part of the installation process.

When a backup or restore pass is run, the application's process is launched (if not already running), the manifest-declared backup agent class (in the android:backupAgent attribute) is instantiated within that process, and the agent's onCreate() method is invoked. This prepares the agent instance to run the actual backup or restore logic. At this point the agent's onBackup() or onRestore() method will be invoked as appropriate for the operation being performed.

A backup data set consists of one or more "entities," flattened binary data records that are each identified with a key string unique within the data set. Adding a record to the active data set or updating an existing record is done by simply writing new entity data under the desired key. Deleting an entity from the data set is done by writing an entity under that key with header specifying a negative data size, and no actual entity data.

Helper Classes

An extensible agent based on convenient helper classes is available in BackupAgentHelper. That class is particularly suited to handling of simple file or SharedPreferences backup and restore.

Summary

[Expand] Inherited Constants

From class android.content.Context String ACCESSIBILITY_SERVICE Use with getSystemService(String) to retrieve a AccessibilityManager for giving the user feedback for UI events through the registered event listeners. String ACCOUNT_SERVICE Use with getSystemService(String) to retrieve a AccountManager for receiving intents at a time of your choosing. String ACTIVITY_SERVICE Use with getSystemService(String) to retrieve a ActivityManager for interacting with the global system state. String ALARM_SERVICE Use with getSystemService(String) to retrieve a AlarmManager for receiving intents at a time of your choosing. String AUDIO_SERVICE Use with getSystemService(String) to retrieve a AudioManager for handling management of volume, ringer modes and audio routing. int BIND_AUTO_CREATE Flag for bindService(Intent, ServiceConnection, int): automatically create the service as long as the binding exists. int BIND_DEBUG_UNBIND Flag for bindService(Intent, ServiceConnection, int): include debugging help for mismatched calls to unbind. int BIND_NOT_FOREGROUND Flag for bindService(Intent, ServiceConnection, int): don't allow this binding to raise the target service's process to the foreground scheduling priority. String CLIPBOARD_SERVICE Use with getSystemService(String) to retrieve a ClipboardManager for accessing and modifying the contents of the global clipboard. String CONNECTIVITY_SERVICE Use with getSystemService(String) to retrieve a ConnectivityManager for handling management of network connections. int CONTEXT_IGNORE_SECURITY Flag for use with createPackageContext(String, int): ignore any security restrictions on the Context being requested, allowing it to always be loaded. int CONTEXT_INCLUDE_CODE Flag for use with createPackageContext(String, int): include the application code with the context. int CONTEXT_RESTRICTED Flag for use with createPackageContext(String, int): a restricted context may disable specific features. String DEVICE_POLICY_SERVICE Use with getSystemService(String) to retrieve a DevicePolicyManager for working with global device policy management. String DOWNLOAD_SERVICE Use with getSystemService(String) to retrieve a DownloadManager for requesting HTTP downloads. String DROPBOX_SERVICE Use with getSystemService(String) to retrieve a DropBoxManager instance for recording diagnostic logs. String INPUT_METHOD_SERVICE Use with getSystemService(String) to retrieve a InputMethodManager for accessing input methods. String KEYGUARD_SERVICE Use with getSystemService(String) to retrieve a NotificationManager for controlling keyguard. String LAYOUT_INFLATER_SERVICE Use with getSystemService(String) to retrieve a LayoutInflater for inflating layout resources in this context. String LOCATION_SERVICE Use with getSystemService(String) to retrieve a LocationManager for controlling location updates. int MODE_APPEND File creation mode: for use with openFileOutput(String, int), if the file already exists then write data to the end of the existing file instead of erasing it. int MODE_PRIVATE File creation mode: the default mode, where the created file can only be accessed by the calling application (or all applications sharing the same user ID). int MODE_WORLD_READABLE File creation mode: allow all other applications to have read access to the created file. int MODE_WORLD_WRITEABLE File creation mode: allow all other applications to have write access to the created file. String NFC_SERVICE Use with getSystemService(String) to retrieve a NfcManager for using NFC. String NOTIFICATION_SERVICE Use with getSystemService(String) to retrieve a NotificationManager for informing the user of background events. String POWER_SERVICE Use with getSystemService(String) to retrieve a PowerManager for controlling power management, including "wake locks," which let you keep the device on while you're running long tasks. String SEARCH_SERVICE Use with getSystemService(String) to retrieve a SearchManager for handling searches. String SENSOR_SERVICE Use with getSystemService(String) to retrieve a SensorManager for accessing sensors. String STORAGE_SERVICE Use with getSystemService(String) to retrieve a StorageManager for accessing system storage functions. String TELEPHONY_SERVICE Use with getSystemService(String) to retrieve a TelephonyManager for handling management the telephony features of the device. String UI_MODE_SERVICE Use with getSystemService(String) to retrieve a UiModeManager for controlling UI modes. String VIBRATOR_SERVICE Use with getSystemService(String) to retrieve a Vibrator for interacting with the vibration hardware. String WALLPAPER_SERVICE Use with getSystemService(String) to retrieve a com.android.server.WallpaperService for accessing wallpapers. String WIFI_SERVICE Use with getSystemService(String) to retrieve a WifiManager for handling management of Wi-Fi access. String WINDOW_SERVICE Use with getSystemService(String) to retrieve a WindowManager for accessing the system's window manager.

[Expand] Inherited Methods
From class android.content.ContextWrapper void attachBaseContext(Context base) Set the base context for this ContextWrapper. boolean bindService(Intent service, ServiceConnection conn, int flags) Connect to an application service, creating it if needed. int checkCallingOrSelfPermission(String permission) Determine whether the calling process of an IPC or you have been granted a particular permission. int checkCallingOrSelfUriPermission(Uri uri, int modeFlags) Determine whether the calling process of an IPC or you has been granted permission to access a specific URI. int checkCallingPermission(String permission) Determine whether the calling process of an IPC you are handling has been granted a particular permission. int checkCallingUriPermission(Uri uri, int modeFlags) Determine whether the calling process and user ID has been granted permission to access a specific URI. int checkPermission(String permission, int pid, int uid) Determine whether the given permission is allowed for a particular process and user ID running in the system. int checkUriPermission(Uri uri, int pid, int uid, int modeFlags) Determine whether a particular process and user ID has been granted permission to access a specific URI. int checkUriPermission(Uri uri, String readPermission, String writePermission, int pid, int uid, int modeFlags) Check both a Uri and normal permission. void clearWallpaper() This method is deprecated. Use WallpaperManager.clear() instead. Context createPackageContext(String packageName, int flags) Return a new Context object for the given application name. String[] databaseList() Returns an array of strings naming the private databases associated with this Context's application package. boolean deleteDatabase(String name) Delete an existing private SQLiteDatabase associated with this Context's application package. boolean deleteFile(String name) Delete the given private file associated with this Context's application package. void enforceCallingOrSelfPermission(String permission, String message) If neither you nor the calling process of an IPC you are handling has been granted a particular permission, throw a SecurityException. void enforceCallingOrSelfUriPermission(Uri uri, int modeFlags, String message) If the calling process of an IPC or you has not been granted permission to access a specific URI, throw SecurityException. void enforceCallingPermission(String permission, String message) If the calling process of an IPC you are handling has not been granted a particular permission, throw a SecurityException. void enforceCallingUriPermission(Uri uri, int modeFlags, String message) If the calling process and user ID has not been granted permission to access a specific URI, throw SecurityException. void enforcePermission(String permission, int pid, int uid, String message) If the given permission is not allowed for a particular process and user ID running in the system, throw a SecurityException. void enforceUriPermission(Uri uri, int pid, int uid, int modeFlags, String message) If a particular process and user ID has not been granted permission to access a specific URI, throw SecurityException. void enforceUriPermission(Uri uri, String readPermission, String writePermission, int pid, int uid, int modeFlags, String message) Enforce both a Uri and normal permission. String[] fileList() Returns an array of strings naming the private files associated with this Context's application package. Context getApplicationContext() Return the context of the single, global Application object of the current process. ApplicationInfo getApplicationInfo() Return the full application info for this context's package. AssetManager getAssets() Return an AssetManager instance for your application's package. Context getBaseContext() File getCacheDir() Returns the absolute path to the application specific cache directory on the filesystem. ClassLoader getClassLoader() Return a class loader you can use to retrieve classes in this package. ContentResolver getContentResolver() Return a ContentResolver instance for your application's package. File getDatabasePath(String name) Returns the absolute path on the filesystem where a database created with openOrCreateDatabase(String, int, SQLiteDatabase.CursorFactory) is stored. File getDir(String name, int mode) Retrieve, creating if needed, a new directory in which the application can place its own custom data files. File getExternalCacheDir() Returns the absolute path to the directory on the external filesystem (that is somewhere on Environment.getExternalStorageDirectory() where the application can place cache files it owns. File getExternalFilesDir(String type) Returns the absolute path to the directory on the external filesystem (that is somewhere on Environment.getExternalStorageDirectory()) where the application can place persistent files it owns. File getFileStreamPath(String name) Returns the absolute path on the filesystem where a file created with openFileOutput(String, int) is stored. File getFilesDir() Returns the absolute path to the directory on the filesystem where files created with openFileOutput(String, int) are stored. Looper getMainLooper() Return the Looper for the main thread of the current process. String getPackageCodePath() Return the full path to this context's primary Android package. PackageManager getPackageManager() Return PackageManager instance to find global package information. String getPackageName() Return the name of this application's package. String getPackageResourcePath() Return the full path to this context's primary Android package. Resources getResources() Return a Resources instance for your application's package. SharedPreferences getSharedPreferences(String name, int mode) Retrieve and hold the contents of the preferences file 'name', returning a SharedPreferences through which you can retrieve and modify its values. Object getSystemService(String name) Return the handle to a system-level service by name. Resources.Theme getTheme() Return the Theme object associated with this Context. Drawable getWallpaper() This method is deprecated. Use WallpaperManager.get() instead. int getWallpaperDesiredMinimumHeight() This method is deprecated. Use WallpaperManager.getDesiredMinimumHeight() instead. int getWallpaperDesiredMinimumWidth() This method is deprecated. Use WallpaperManager.getDesiredMinimumWidth() instead. void grantUriPermission(String toPackage, Uri uri, int modeFlags) Grant permission to access a specific Uri to another package, regardless of whether that package has general permission to access the Uri's content provider. boolean isRestricted() Indicates whether this Context is restricted. FileInputStream openFileInput(String name) Open a private file associated with this Context's application package for reading. FileOutputStream openFileOutput(String name, int mode) Open a private file associated with this Context's application package for writing. SQLiteDatabase openOrCreateDatabase(String name, int mode, SQLiteDatabase.CursorFactory factory) Open a new private SQLiteDatabase associated with this Context's application package. Drawable peekWallpaper() This method is deprecated. Use WallpaperManager.peek() instead. Intent registerReceiver(BroadcastReceiver receiver, IntentFilter filter) Register a BroadcastReceiver to be run in the main activity thread. Intent registerReceiver(BroadcastReceiver receiver, IntentFilter filter, String broadcastPermission, Handler scheduler) Register to receive intent broadcasts, to run in the context of scheduler. void removeStickyBroadcast(Intent intent) Remove the data previously sent with sendStickyBroadcast(Intent), so that it is as if the sticky broadcast had never happened. void revokeUriPermission(Uri uri, int modeFlags) Remove all permissions to access a particular content provider Uri that were previously added with grantUriPermission(String, Uri, int). void sendBroadcast(Intent intent) Broadcast the given intent to all interested BroadcastReceivers. void sendBroadcast(Intent intent, String receiverPermission) Broadcast the given intent to all interested BroadcastReceivers, allowing an optional required permission to be enforced. void sendOrderedBroadcast(Intent intent, String receiverPermission, BroadcastReceiver resultReceiver, Handler scheduler, int initialCode, String initialData, Bundle initialExtras) Version of sendBroadcast(Intent) that allows you to receive data back from the broadcast. void sendOrderedBroadcast(Intent intent, String receiverPermission) Broadcast the given intent to all interested BroadcastReceivers, delivering them one at a time to allow more preferred receivers to consume the broadcast before it is delivered to less preferred receivers. void sendStickyBroadcast(Intent intent) Perform a sendBroadcast(Intent) that is "sticky," meaning the Intent you are sending stays around after the broadcast is complete, so that others can quickly retrieve that data through the return value of registerReceiver(BroadcastReceiver, IntentFilter). void sendStickyOrderedBroadcast(Intent intent, BroadcastReceiver resultReceiver, Handler scheduler, int initialCode, String initialData, Bundle initialExtras) Version of sendStickyBroadcast(Intent) that allows you to receive data back from the broadcast. void setTheme(int resid) Set the base theme for this context. void setWallpaper(Bitmap bitmap) This method is deprecated. Use WallpaperManager.set() instead. void setWallpaper(InputStream data) This method is deprecated. Use WallpaperManager.set() instead. void startActivity(Intent intent) Launch a new activity. boolean startInstrumentation(ComponentName className, String profileFile, Bundle arguments) Start executing an Instrumentation class. void startIntentSender(IntentSender intent, Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags) Like startActivity(Intent), but taking a IntentSender to start. ComponentName startService(Intent service) Request that a given application service be started. boolean stopService(Intent name) Request that a given application service be stopped. void unbindService(ServiceConnection conn) Disconnect from an application service. void unregisterReceiver(BroadcastReceiver receiver) Unregister a previously registered BroadcastReceiver.
From class android.content.Context abstract boolean bindService(Intent service, ServiceConnection conn, int flags) Connect to an application service, creating it if needed. abstract int checkCallingOrSelfPermission(String permission) Determine whether the calling process of an IPC or you have been granted a particular permission. abstract int checkCallingOrSelfUriPermission(Uri uri, int modeFlags) Determine whether the calling process of an IPC or you has been granted permission to access a specific URI. abstract int checkCallingPermission(String permission) Determine whether the calling process of an IPC you are handling has been granted a particular permission. abstract int checkCallingUriPermission(Uri uri, int modeFlags) Determine whether the calling process and user ID has been granted permission to access a specific URI. abstract int checkPermission(String permission, int pid, int uid) Determine whether the given permission is allowed for a particular process and user ID running in the system. abstract int checkUriPermission(Uri uri, int pid, int uid, int modeFlags) Determine whether a particular process and user ID has been granted permission to access a specific URI. abstract int checkUriPermission(Uri uri, String readPermission, String writePermission, int pid, int uid, int modeFlags) Check both a Uri and normal permission. abstract void clearWallpaper() This method is deprecated. Use WallpaperManager.clear() instead. abstract Context createPackageContext(String packageName, int flags) Return a new Context object for the given application name. abstract String[] databaseList() Returns an array of strings naming the private databases associated with this Context's application package. abstract boolean deleteDatabase(String name) Delete an existing private SQLiteDatabase associated with this Context's application package. abstract boolean deleteFile(String name) Delete the given private file associated with this Context's application package. abstract void enforceCallingOrSelfPermission(String permission, String message) If neither you nor the calling process of an IPC you are handling has been granted a particular permission, throw a SecurityException. abstract void enforceCallingOrSelfUriPermission(Uri uri, int modeFlags, String message) If the calling process of an IPC or you has not been granted permission to access a specific URI, throw SecurityException. abstract void enforceCallingPermission(String permission, String message) If the calling process of an IPC you are handling has not been granted a particular permission, throw a SecurityException. abstract void enforceCallingUriPermission(Uri uri, int modeFlags, String message) If the calling process and user ID has not been granted permission to access a specific URI, throw SecurityException. abstract void enforcePermission(String permission, int pid, int uid, String message) If the given permission is not allowed for a particular process and user ID running in the system, throw a SecurityException. abstract void enforceUriPermission(Uri uri, int pid, int uid, int modeFlags, String message) If a particular process and user ID has not been granted permission to access a specific URI, throw SecurityException. abstract void enforceUriPermission(Uri uri, String readPermission, String writePermission, int pid, int uid, int modeFlags, String message) Enforce both a Uri and normal permission. abstract String[] fileList() Returns an array of strings naming the private files associated with this Context's application package. abstract Context getApplicationContext() Return the context of the single, global Application object of the current process. abstract ApplicationInfo getApplicationInfo() Return the full application info for this context's package. abstract AssetManager getAssets() Return an AssetManager instance for your application's package. abstract File getCacheDir() Returns the absolute path to the application specific cache directory on the filesystem. abstract ClassLoader getClassLoader() Return a class loader you can use to retrieve classes in this package. abstract ContentResolver getContentResolver() Return a ContentResolver instance for your application's package. abstract File getDatabasePath(String name) Returns the absolute path on the filesystem where a database created with openOrCreateDatabase(String, int, SQLiteDatabase.CursorFactory) is stored. abstract File getDir(String name, int mode) Retrieve, creating if needed, a new directory in which the application can place its own custom data files. abstract File getExternalCacheDir() Returns the absolute path to the directory on the external filesystem (that is somewhere on Environment.getExternalStorageDirectory() where the application can place cache files it owns. abstract File getExternalFilesDir(String type) Returns the absolute path to the directory on the external filesystem (that is somewhere on Environment.getExternalStorageDirectory()) where the application can place persistent files it owns. abstract File getFileStreamPath(String name) Returns the absolute path on the filesystem where a file created with openFileOutput(String, int) is stored. abstract File getFilesDir() Returns the absolute path to the directory on the filesystem where files created with openFileOutput(String, int) are stored. abstract Looper getMainLooper() Return the Looper for the main thread of the current process. abstract String getPackageCodePath() Return the full path to this context's primary Android package. abstract PackageManager getPackageManager() Return PackageManager instance to find global package information. abstract String getPackageName() Return the name of this application's package. abstract String getPackageResourcePath() Return the full path to this context's primary Android package. abstract Resources getResources() Return a Resources instance for your application's package. abstract SharedPreferences getSharedPreferences(String name, int mode) Retrieve and hold the contents of the preferences file 'name', returning a SharedPreferences through which you can retrieve and modify its values. final String getString(int resId) Return a localized string from the application's package's default string table. final String getString(int resId, Object... formatArgs) Return a localized formatted string from the application's package's default string table, substituting the format arguments as defined in Formatter and format(String, Object...). abstract Object getSystemService(String name) Return the handle to a system-level service by name. final CharSequence getText(int resId) Return a localized, styled CharSequence from the application's package's default string table. abstract Resources.Theme getTheme() Return the Theme object associated with this Context. abstract Drawable getWallpaper() This method is deprecated. Use WallpaperManager.get() instead. abstract int getWallpaperDesiredMinimumHeight() This method is deprecated. Use WallpaperManager.getDesiredMinimumHeight() instead. abstract int getWallpaperDesiredMinimumWidth() This method is deprecated. Use WallpaperManager.getDesiredMinimumWidth() instead. abstract void grantUriPermission(String toPackage, Uri uri, int modeFlags) Grant permission to access a specific Uri to another package, regardless of whether that package has general permission to access the Uri's content provider. boolean isRestricted() Indicates whether this Context is restricted. final TypedArray obtainStyledAttributes(int[] attrs) Retrieve styled attribute information in this Context's theme. final TypedArray obtainStyledAttributes(AttributeSet set, int[] attrs) Retrieve styled attribute information in this Context's theme. final TypedArray obtainStyledAttributes(int resid, int[] attrs) Retrieve styled attribute information in this Context's theme. final TypedArray obtainStyledAttributes(AttributeSet set, int[] attrs, int defStyleAttr, int defStyleRes) Retrieve styled attribute information in this Context's theme. abstract FileInputStream openFileInput(String name) Open a private file associated with this Context's application package for reading. abstract FileOutputStream openFileOutput(String name, int mode) Open a private file associated with this Context's application package for writing. abstract SQLiteDatabase openOrCreateDatabase(String name, int mode, SQLiteDatabase.CursorFactory factory) Open a new private SQLiteDatabase associated with this Context's application package. abstract Drawable peekWallpaper() This method is deprecated. Use WallpaperManager.peek() instead. abstract Intent registerReceiver(BroadcastReceiver receiver, IntentFilter filter) Register a BroadcastReceiver to be run in the main activity thread. abstract Intent registerReceiver(BroadcastReceiver receiver, IntentFilter filter, String broadcastPermission, Handler scheduler) Register to receive intent broadcasts, to run in the context of scheduler. abstract void removeStickyBroadcast(Intent intent) Remove the data previously sent with sendStickyBroadcast(Intent), so that it is as if the sticky broadcast had never happened. abstract void revokeUriPermission(Uri uri, int modeFlags) Remove all permissions to access a particular content provider Uri that were previously added with grantUriPermission(String, Uri, int). abstract void sendBroadcast(Intent intent) Broadcast the given intent to all interested BroadcastReceivers. abstract void sendBroadcast(Intent intent, String receiverPermission) Broadcast the given intent to all interested BroadcastReceivers, allowing an optional required permission to be enforced. abstract void sendOrderedBroadcast(Intent intent, String receiverPermission, BroadcastReceiver resultReceiver, Handler scheduler, int initialCode, String initialData, Bundle initialExtras) Version of sendBroadcast(Intent) that allows you to receive data back from the broadcast. abstract void sendOrderedBroadcast(Intent intent, String receiverPermission) Broadcast the given intent to all interested BroadcastReceivers, delivering them one at a time to allow more preferred receivers to consume the broadcast before it is delivered to less preferred receivers. abstract void sendStickyBroadcast(Intent intent) Perform a sendBroadcast(Intent) that is "sticky," meaning the Intent you are sending stays around after the broadcast is complete, so that others can quickly retrieve that data through the return value of registerReceiver(BroadcastReceiver, IntentFilter). abstract void sendStickyOrderedBroadcast(Intent intent, BroadcastReceiver resultReceiver, Handler scheduler, int initialCode, String initialData, Bundle initialExtras) Version of sendStickyBroadcast(Intent) that allows you to receive data back from the broadcast. abstract void setTheme(int resid) Set the base theme for this context. abstract void setWallpaper(Bitmap bitmap) This method is deprecated. Use WallpaperManager.set() instead. abstract void setWallpaper(InputStream data) This method is deprecated. Use WallpaperManager.set() instead. abstract void startActivity(Intent intent) Launch a new activity. abstract boolean startInstrumentation(ComponentName className, String profileFile, Bundle arguments) Start executing an Instrumentation class. abstract void startIntentSender(IntentSender intent, Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags) Like startActivity(Intent), but taking a IntentSender to start. abstract ComponentName startService(Intent service) Request that a given application service be started. abstract boolean stopService(Intent service) Request that a given application service be stopped. abstract void unbindService(ServiceConnection conn) Disconnect from an application service. abstract void unregisterReceiver(BroadcastReceiver receiver) Unregister a previously registered BroadcastReceiver.
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Called before the object's memory is reclaimed by the VM. final Class<? extends Object> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.