BackupAgentHelper.java revision 61fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ec
106290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato/* 24e14a829129feee14ebe453f61a124784c870610Christopher Tate * Copyright (C) 2009 The Android Open Source Project 306290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * 406290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * Licensed under the Apache License, Version 2.0 (the "License"); 506290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * you may not use this file except in compliance with the License. 606290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * You may obtain a copy of the License at 706290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * 806290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * http://www.apache.org/licenses/LICENSE-2.0 906290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * 1006290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * Unless required by applicable law or agreed to in writing, software 1106290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * distributed under the License is distributed on an "AS IS" BASIS, 1206290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1306290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * See the License for the specific language governing permissions and 1406290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato * limitations under the License. 1506290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato */ 1606290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 174528186e0d65fc68ef0dd1941aa2ac8aefcd55a3Christopher Tatepackage android.app.backup; 1806290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 1906290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onoratoimport android.os.ParcelFileDescriptor; 2006290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 2106290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onoratoimport java.io.IOException; 2206290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 23e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate/** 247cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * A convenient {@link BackupAgent} wrapper class that automatically manages 255a20ea16d7e5b70dc7bad8700f54170e4f220d12Kenny Root * heterogeneous data sets within the backup data, each identified by a unique 267cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * key prefix. When processing a backup or restore operation, the BackupAgentHelper 27d17da43c82c4edb97514d6138bc208eeba321636Scott Main * dispatches to one or more installed {@link BackupHelper} objects, each 287cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * of which is responsible for a defined subset of the data being processed. 295a20ea16d7e5b70dc7bad8700f54170e4f220d12Kenny Root * <p> 30d17da43c82c4edb97514d6138bc208eeba321636Scott Main * An application will typically extend this class in its own 317cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * backup agent. Then, within the agent's {@link BackupAgent#onCreate() onCreate()} 32d17da43c82c4edb97514d6138bc208eeba321636Scott Main * method, it will call {@link #addHelper(String, BackupHelper) addHelper()} one or more times to 337cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * install the handlers for each kind of data it wishes to manage within its backups. 347cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p> 35d17da43c82c4edb97514d6138bc208eeba321636Scott Main * The Android framework currently provides two predefined {@link BackupHelper} classes:</p> 36d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <ul><li>{@link FileBackupHelper} - Manages the backup and restore of entire files 37d17da43c82c4edb97514d6138bc208eeba321636Scott Main * within an application's data directory hierarchy.</li> 38d17da43c82c4edb97514d6138bc208eeba321636Scott Main * <li>{@link SharedPreferencesBackupHelper} - Manages the backup and restore of an 39d17da43c82c4edb97514d6138bc208eeba321636Scott Main * application's {@link android.content.SharedPreferences} data.</li></ul> 407cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * <p> 417cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * An application can also implement its own helper classes to work within the 427cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * {@link BackupAgentHelper} framework. See the {@link BackupHelper} interface 437cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * documentation for details. 444e14a829129feee14ebe453f61a124784c870610Christopher Tate * 4561fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <div class="special reference"> 4661fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <h3>Developer Guides</h3> 4761fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <p>For more information about using BackupAgentHelper, read the 4861fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * <a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a> developer guide.</p> 4961fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * </div> 5061fd1e8d8c3ccf2d6b7d4af1c19e8f0988d5a1ecJoe Fernandez * 517cc088232d20a63d24dd1f79f529ddad1b792cdeChristopher Tate * @see BackupHelper 524e14a829129feee14ebe453f61a124784c870610Christopher Tate * @see FileBackupHelper 534e14a829129feee14ebe453f61a124784c870610Christopher Tate * @see SharedPreferencesBackupHelper 54e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate */ 55cc84c69726507a85116f5664e20e2ebfac76edbeChristopher Tatepublic class BackupAgentHelper extends BackupAgent { 56cc84c69726507a85116f5664e20e2ebfac76edbeChristopher Tate static final String TAG = "BackupAgentHelper"; 5706290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 5806290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato BackupHelperDispatcher mDispatcher = new BackupHelperDispatcher(); 5906290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 60e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate /** 61e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate * Run the backup process on each of the configured handlers. 62e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate */ 6306290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato @Override 6406290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data, 654ababd922eac5931e0222862ff082dc29e012816Joe Onorato ParcelFileDescriptor newState) throws IOException { 6606290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato mDispatcher.performBackup(oldState, data, newState); 6706290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato } 6806290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 69e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate /** 70e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate * Run the restore process on each of the configured handlers. 71e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate */ 7206290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato @Override 735cbbf5652a78902ac3382dc4a3583bc5b0351027Christopher Tate public void onRestore(BackupDataInput data, int appVersionCode, ParcelFileDescriptor newState) 7406290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato throws IOException { 755cbbf5652a78902ac3382dc4a3583bc5b0351027Christopher Tate mDispatcher.performRestore(data, appVersionCode, newState); 7606290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato } 7706290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 78e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate /** @hide */ 7906290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato public BackupHelperDispatcher getDispatcher() { 8006290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato return mDispatcher; 8106290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato } 8206290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 83e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate /** 84e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate * Add a helper for a given data subset to the agent's configuration. Each helper 85e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate * must have a prefix string that is unique within this backup agent's set of 86e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate * helpers. 87e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate * 88e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate * @param keyPrefix A string used to disambiguate the various helpers within this agent 89e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate * @param helper A backup/restore helper object to be invoked during backup and restore 90e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate * operations. 91e28290e21f908b4e917099ff2aa41e3aab9310c2Christopher Tate */ 9206290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato public void addHelper(String keyPrefix, BackupHelper helper) { 9306290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato mDispatcher.addHelper(keyPrefix, helper); 9406290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato } 9506290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato} 9606290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 9706290a4bb9b280fa14a2bbeb2d3ceb09396a78c3Joe Onorato 98