Often, an app will need to backup it's data, especially if the data took time, effort or money to collect. The Android Backup Service provides a means of preserving data that is more complex than simple shared preferences or files.
In order to work with the backup API, we have to have registered our app package name with the Android Backup Service.
We do this on http://developer.android.com/google/backup/signup.html.
In this recipe, we will save a value to a file and read from a file. This can be a far more comprehensive set of actions on a larger dataset, but not necessary, for example:
- Our app is not going to do much with the data, so we can save our single value to the filesystem as a basic write operation:
File.WriteAllText(dataPath, clickCount.ToString());
- Additionally, to read the data on the app start, we will do a basic read:
if (File.Exists(dataPath)) { clickCount = int.Parse(File.ReadAllText(dataPath)); }
Now that we have the data moving in our app, we need to hook up the backup. Although this example uses a simple file stored locally, we can back up data in a database using an algorithm to determine whether a backup needs to be done. Let's take a look at the following steps:
- Just as we did when we used backup helpers (refer to the previous recipe), we need to register the agent with the application using the backup key:
[assembly: MetaData( "com.google.android.backup.api_key", Value = "AndroidBackupServiceKey")]
- In the case of our agent, we inherit it from the base
BackupAgentinstance:public class BackupHelper : BackupAgent { public override void OnBackup( ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState) { // backup logic } public override void OnRestore( BackupDataInput data, int appVersionCode, ParcelFileDescriptor newState) { // restore logic } } - We now need to create the logic that actually creates the backup logic. We do this in the
OnBackup()method in four main steps. First, we read the state or metadata associated with the last backup, if any:var stateDate = DateTime.MinValue; if (oldState != null) { using (var descr = oldState.FileDescriptor) using (var file = new FileInputStream(descr)) using (var invoker = new InputStreamInvoker(file)) using (var stream = new DataInputStream(invoker)) { stateDate = DateTime.FromBinary(stream.ReadLong()); } } - Next, we get the state of the data that we need to backup, in our case, the file's last write date:
var fileDate = DateTime.MinValue; if (File.Exists(dataPath)) { fileDate = File.GetLastWriteTimeUtc(dataPath); } else { stateDate = DateTime.MinValue; } - Now, we can compare the states, and if they differ, we perform the backup. Here, we just back up the entire contents of the file, but we can back up any data or subset of data:
if (stateDate != fileDate) { var buffer = File.ReadAllBytes(dataPath); data.WriteEntityHeader("DataHeader", buffer.Length); data.WriteEntityData(buffer, buffer.Length); } - Whether or not we do a backup, we now have to let the agent know what state we are in, and in our case, just the last time the file was modified:
using (var descr = newState.FileDescriptor) using (var file = new FileOutputStream(descr)) using (var invoker = new OutputStreamInvoker(file)) using (var stream = new DataOutputStream(invoker)) { stream.WriteLong(fileDate.ToBinary()); } - Now we need to work on the restore logic in the
OnRestore()method. We first have to go through all the bits of data that were backed up until we find the header we are looking for, that is, what we know our is app saved:while (data.ReadNextHeader()) { if (data.Key == "DataHeader") { var buffer = new byte[data.DataSize]; data.ReadEntityData(buffer, 0, data.DataSize); File.WriteAllBytes(dataPath, buffer); break; } else { data.SkipEntityData(); } } - Lastly, we have to let the agent know about the current state of the backup, and again in our case, just the time of the last modification of the file:
if (File.Exists(dataPath)) { using (var descr = newState.FileDescriptor) using (var file = new FileOutputStream(descr)) using (var invoker = new OutputStreamInvoker(file)) using (var stream = new DataOutputStream(invoker)) { var fileDate = File.GetLastWriteTimeUtc(dataPath); stream.WriteLong(fileDate.ToBinary()); } }
We can easily back up shared preferences or entire files, but sometimes, we need to have more flexibility or control. To do this, we can create an instance of the base BackupAgent instance.
There are several advantages of using the base agent directly as opposed to the helpers. The most notable advantage is the ability to version data and appropriately upgrade or downgrade the data. There is also the powerful ability to back up and restore partial data, such as a section of a larger file. We can also back up specific tables in a database. This will allow us to better version the data as well as reduce the size by excluding static data.
There are two stages to any backup process: backup and restore. The backup stage consists of four main steps:
- The first step is to read the state or metadata associated with the last backup from the
oldStateparameter. This state is used to identify the backed up data but is not the data itself; it can be anything, even a simple, last-modified timestamp of the data. If the state isnull, then no backup or restore has been performed and we should take a backup. - We now need to be able to make a decision to backup, so we need to obtain the state of the data itself. If we are backing up data only if it has changed, we need to obtain the timestamp of the last change. If we are backing up a database, we may use the last login date.
- Now that we have both the state of the backup and the state of the data, we can determine whether a backup is needed. To perform a backup, we populate the
BackupDataOutputobject with a set of key-value entities. We first write a header using theWriteEntityHeader()method, and then the actual data using theWriteEntityData()method. If we are backing up a database table, we can read the contents into an XML document and then write that. - Finally, we have to let Android know the state of the backup in the
newStateparameter. Even if nothing was backed up, we can still write a value representing the fact that nothing was done, that is, the original value. This state is passed in as theoldStateparameter the next time a backup is run. If we are backing up a table, we can write the last login date.
Performing a restore is a bit easier as we only have to execute two steps:
- We have to first go through the data in the
BackupDataInputobject and work with the keys we recognize. We can loop through the headers using theReadNextHeader()method, and if we are working with different app versions, we may choose to ignore some using theSkipEntityData()method. If we want to read the data, we use theReadEntityData()method. - After we have restored the data, we now update the state of the data by writing to the
newStateparameter. If we are restoring a section of a file, we can use the timestamp. This state is passed in as theoldStateparameter when a backup is run.
The OnBackup() method is called when the backup manager decides that it is time to run a backup. We can request a backup using the backup manager, but cannot control when it is run. The OnRestore() method is called by the backup manager as well, but is also automatically called when the app is installed. Like backups, we can request a restore but cannot directly control when it happens.