Loading core/java/android/app/backup/BackupAgentHelper.java +19 −7 Original line number Original line Diff line number Diff line Loading @@ -21,16 +21,28 @@ import android.os.ParcelFileDescriptor; import java.io.IOException; import java.io.IOException; /** /** * A convenient BackupAgent wrapper class that automatically manages * A convenient {@link BackupAgent} wrapper class that automatically manages * heterogeneous data sets within the backup data, each identified by a unique * heterogeneous data sets within the backup data, each identified by a unique * key prefix. An application will typically extend this class in their own * key prefix. When processing a backup or restore operation, the BackupAgentHelper * backup agent. Then, within the agent's onBackup() and onRestore() methods, it * dispatches to one or more installed {@link BackupHelper helpers} objects, each * will call {@link #addHelper(String, BackupHelper)} one or more times to * of which is responsible for a defined subset of the data being processed. * specify the data sets, then invoke super.onBackup() or super.onRestore() to * have the BackupAgentHelper implementation process the data. * <p> * <p> * STOPSHIP: document! * An application will typically extend this class in their own * backup agent. Then, within the agent's {@link BackupAgent#onCreate() onCreate()} * method, it will call {@link #addHelper(String, BackupHelper)} one or more times to * install the handlers for each kind of data it wishes to manage within its backups. * <p> * The Android framework currently provides two predefined {@link BackupHelper} classes: * {@link FileBackupHelper}, which manages the backup and restore of entire files * within an application's data directory hierarchy; and {@link SharedPreferencesBackupHelper}, * which manages the backup and restore of an application's * {@link android.content.SharedPreferences} data. * <p> * An application can also implement its own helper classes to work within the * {@link BackupAgentHelper} framework. See the {@link BackupHelper} interface * documentation for details. * * * @see BackupHelper * @see FileBackupHelper * @see FileBackupHelper * @see SharedPreferencesBackupHelper * @see SharedPreferencesBackupHelper */ */ Loading core/java/android/app/backup/BackupDataInputStream.java +57 −2 Original line number Original line Diff line number Diff line Loading @@ -20,7 +20,21 @@ import java.io.InputStream; import java.io.IOException; import java.io.IOException; /** /** * STOPSHIP: document */ * Used by {@link BackupHelper} classes within the {@link BackupAgentHelper} mechanism, * this class provides an {@link java.io.InputStream}-like interface for accessing an * entity's data during a restore operation. * <p> * When {@link BackupHelper#restoreEntity(BackupDataInputStream) BackupHelper.restoreEntity(BackupDataInputStream)} * is called, the current entity's header has already been read from the underlying * {@link BackupDataInput}. The entity's key string and total data size are available * through this class's {@link #getKey()} and {@link #size()} methods, respectively. * <p class="note"> * <em>Note:</em> The caller should take care not to seek or close the underlying data * source, or to read more than {@link #size()} bytes total from the stream.</p> * * @see BackupAgentHelper * @see BackupHelper */ public class BackupDataInputStream extends InputStream { public class BackupDataInputStream extends InputStream { String key; String key; Loading @@ -34,6 +48,13 @@ public class BackupDataInputStream extends InputStream { mData = data; mData = data; } } /** * Read one byte of entity data from the stream, returning it as * an integer value. If more than {@link #size()} bytes of data * are read from the stream, the output of this method is undefined. * * @return The byte read, or undefined if the end of the stream has been reached. */ public int read() throws IOException { public int read() throws IOException { byte[] one = mOneByte; byte[] one = mOneByte; if (mOneByte == null) { if (mOneByte == null) { Loading @@ -43,18 +64,52 @@ public class BackupDataInputStream extends InputStream { return one[0]; return one[0]; } } /** * Read up to {@code size} bytes of data into a byte array, beginning at position * {@code offset} within the array. * * @param b Byte array into which the data will be read * @param offset The data will be stored in {@code b} beginning at this index * within the array. * @param size The number of bytes to read in this operation. If insufficient * data exists within the entity to fulfill this request, only as much data * will be read as is available. * @return The number of bytes of data read, or zero if all of the entity's * data has already been read. */ public int read(byte[] b, int offset, int size) throws IOException { public int read(byte[] b, int offset, int size) throws IOException { return mData.readEntityData(b, offset, size); return mData.readEntityData(b, offset, size); } } /** * Read enough entity data into a byte array to fill the array. * * @param b Byte array to fill with data from the stream. If the stream does not * have sufficient data to fill the array, then the contents of the remainder of * the array will be undefined. * @return The number of bytes of data read, or zero if all of the entity's * data has already been read. */ public int read(byte[] b) throws IOException { public int read(byte[] b) throws IOException { return mData.readEntityData(b, 0, b.length); return mData.readEntityData(b, 0, b.length); } } /** * Report the key string associated with this entity within the backup data set. * * @return The key string for this entity, equivalent to calling * {@link BackupDataInput#getKey()} on the underlying {@link BackupDataInput}. */ public String getKey() { public String getKey() { return this.key; return this.key; } } /** * Report the total number of bytes of data available for the current entity. * * @return The number of data bytes available, equivalent to calling * {@link BackupDataInput#getDataSize()} on the underlying {@link BackupDataInput}. */ public int size() { public int size() { return this.dataSize; return this.dataSize; } } Loading core/java/android/app/backup/BackupHelper.java +42 −10 Original line number Original line Diff line number Diff line Loading @@ -19,11 +19,21 @@ package android.app.backup; import android.os.ParcelFileDescriptor; import android.os.ParcelFileDescriptor; /** /** * A convenient interface to be used with the * This interface defines the calling interface that {@link BackupAgentHelper} uses * {@link android.app.backup.BackupAgentHelper} class to implement backup and restore of * when dispatching backup and restore operations to the installed helpers. * arbitrary data types. * Applications can define and install their own helpers as well as using those * provided as part of the Android framework. * <p> * <p> * STOPSHIP: document! * Although multiple helper objects may be installed simultaneously, each helper * is responsible only for handling its own data, and will not see entities * created by other components within the backup system. Invocations of multiple * helpers are performed sequentially by the {@link BackupAgentHelper}, with each * helper given a chance to access its own saved state from within the state record * produced during the previous backup operation. * * @see BackupAgentHelper * @see FileBackupHelper * @see SharedPreferencesBackupHelper */ */ public interface BackupHelper { public interface BackupHelper { /** /** Loading @@ -31,24 +41,46 @@ public interface BackupHelper { * application's data directory need to be backed up, write them to * application's data directory need to be backed up, write them to * <code>data</code>, and fill in <code>newState</code> with the state as it * <code>data</code>, and fill in <code>newState</code> with the state as it * exists now. * exists now. * <p> * Implementing this method is much like implementing * {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)} * — the method parameters are the same. When this method is invoked the * {@code oldState} descriptor points to the beginning of the state data * written during this helper's previous backup operation, and the {@code newState} * descriptor points to the file location at which the helper should write its * new state after performing the backup operation. * <p class="note"> * <em>Note:</em> The helper should not close or seek either the {@code oldState} or * the {@code newState} file descriptors.</p> */ */ public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data, public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState); ParcelFileDescriptor newState); /** /** * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} * to restore one entity from the restore dataset. * to restore a single entity from the restore data set. This method will be * <p class=note> * called for each entity in the data set that belongs to this handler. * Do not close the <code>data</code> stream. Do not read more than * <p class="note"> * <code>data.size()</code> bytes from <code>data</code>. * <em>Note:</em> Do not close the <code>data</code> stream. Do not read more than * <code>data.size()</code> bytes from <code>data</code>.</p> */ */ public void restoreEntity(BackupDataInputStream data); public void restoreEntity(BackupDataInputStream data); /** /** * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} * after a restore operation to write the backup state file corresponding to * after a restore operation to write the backup state file corresponding to * the data as processed by the helper. * the data as processed by the helper. The data written here will be * available to the helper during the next call to its * {@link #performBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)} * method. * <p> * Note that this method will be called even if the handler's * {@link #restoreEntity(BackupDataInputStream)} method was never invoked during * the restore operation. * <p class="note"> * <em>Note:</em> The helper should not close or seek the {@code newState} * file descriptor.</p> */ */ public void writeNewStateDescription(ParcelFileDescriptor fd); public void writeNewStateDescription(ParcelFileDescriptor newState); } } Loading
core/java/android/app/backup/BackupAgentHelper.java +19 −7 Original line number Original line Diff line number Diff line Loading @@ -21,16 +21,28 @@ import android.os.ParcelFileDescriptor; import java.io.IOException; import java.io.IOException; /** /** * A convenient BackupAgent wrapper class that automatically manages * A convenient {@link BackupAgent} wrapper class that automatically manages * heterogeneous data sets within the backup data, each identified by a unique * heterogeneous data sets within the backup data, each identified by a unique * key prefix. An application will typically extend this class in their own * key prefix. When processing a backup or restore operation, the BackupAgentHelper * backup agent. Then, within the agent's onBackup() and onRestore() methods, it * dispatches to one or more installed {@link BackupHelper helpers} objects, each * will call {@link #addHelper(String, BackupHelper)} one or more times to * of which is responsible for a defined subset of the data being processed. * specify the data sets, then invoke super.onBackup() or super.onRestore() to * have the BackupAgentHelper implementation process the data. * <p> * <p> * STOPSHIP: document! * An application will typically extend this class in their own * backup agent. Then, within the agent's {@link BackupAgent#onCreate() onCreate()} * method, it will call {@link #addHelper(String, BackupHelper)} one or more times to * install the handlers for each kind of data it wishes to manage within its backups. * <p> * The Android framework currently provides two predefined {@link BackupHelper} classes: * {@link FileBackupHelper}, which manages the backup and restore of entire files * within an application's data directory hierarchy; and {@link SharedPreferencesBackupHelper}, * which manages the backup and restore of an application's * {@link android.content.SharedPreferences} data. * <p> * An application can also implement its own helper classes to work within the * {@link BackupAgentHelper} framework. See the {@link BackupHelper} interface * documentation for details. * * * @see BackupHelper * @see FileBackupHelper * @see FileBackupHelper * @see SharedPreferencesBackupHelper * @see SharedPreferencesBackupHelper */ */ Loading
core/java/android/app/backup/BackupDataInputStream.java +57 −2 Original line number Original line Diff line number Diff line Loading @@ -20,7 +20,21 @@ import java.io.InputStream; import java.io.IOException; import java.io.IOException; /** /** * STOPSHIP: document */ * Used by {@link BackupHelper} classes within the {@link BackupAgentHelper} mechanism, * this class provides an {@link java.io.InputStream}-like interface for accessing an * entity's data during a restore operation. * <p> * When {@link BackupHelper#restoreEntity(BackupDataInputStream) BackupHelper.restoreEntity(BackupDataInputStream)} * is called, the current entity's header has already been read from the underlying * {@link BackupDataInput}. The entity's key string and total data size are available * through this class's {@link #getKey()} and {@link #size()} methods, respectively. * <p class="note"> * <em>Note:</em> The caller should take care not to seek or close the underlying data * source, or to read more than {@link #size()} bytes total from the stream.</p> * * @see BackupAgentHelper * @see BackupHelper */ public class BackupDataInputStream extends InputStream { public class BackupDataInputStream extends InputStream { String key; String key; Loading @@ -34,6 +48,13 @@ public class BackupDataInputStream extends InputStream { mData = data; mData = data; } } /** * Read one byte of entity data from the stream, returning it as * an integer value. If more than {@link #size()} bytes of data * are read from the stream, the output of this method is undefined. * * @return The byte read, or undefined if the end of the stream has been reached. */ public int read() throws IOException { public int read() throws IOException { byte[] one = mOneByte; byte[] one = mOneByte; if (mOneByte == null) { if (mOneByte == null) { Loading @@ -43,18 +64,52 @@ public class BackupDataInputStream extends InputStream { return one[0]; return one[0]; } } /** * Read up to {@code size} bytes of data into a byte array, beginning at position * {@code offset} within the array. * * @param b Byte array into which the data will be read * @param offset The data will be stored in {@code b} beginning at this index * within the array. * @param size The number of bytes to read in this operation. If insufficient * data exists within the entity to fulfill this request, only as much data * will be read as is available. * @return The number of bytes of data read, or zero if all of the entity's * data has already been read. */ public int read(byte[] b, int offset, int size) throws IOException { public int read(byte[] b, int offset, int size) throws IOException { return mData.readEntityData(b, offset, size); return mData.readEntityData(b, offset, size); } } /** * Read enough entity data into a byte array to fill the array. * * @param b Byte array to fill with data from the stream. If the stream does not * have sufficient data to fill the array, then the contents of the remainder of * the array will be undefined. * @return The number of bytes of data read, or zero if all of the entity's * data has already been read. */ public int read(byte[] b) throws IOException { public int read(byte[] b) throws IOException { return mData.readEntityData(b, 0, b.length); return mData.readEntityData(b, 0, b.length); } } /** * Report the key string associated with this entity within the backup data set. * * @return The key string for this entity, equivalent to calling * {@link BackupDataInput#getKey()} on the underlying {@link BackupDataInput}. */ public String getKey() { public String getKey() { return this.key; return this.key; } } /** * Report the total number of bytes of data available for the current entity. * * @return The number of data bytes available, equivalent to calling * {@link BackupDataInput#getDataSize()} on the underlying {@link BackupDataInput}. */ public int size() { public int size() { return this.dataSize; return this.dataSize; } } Loading
core/java/android/app/backup/BackupHelper.java +42 −10 Original line number Original line Diff line number Diff line Loading @@ -19,11 +19,21 @@ package android.app.backup; import android.os.ParcelFileDescriptor; import android.os.ParcelFileDescriptor; /** /** * A convenient interface to be used with the * This interface defines the calling interface that {@link BackupAgentHelper} uses * {@link android.app.backup.BackupAgentHelper} class to implement backup and restore of * when dispatching backup and restore operations to the installed helpers. * arbitrary data types. * Applications can define and install their own helpers as well as using those * provided as part of the Android framework. * <p> * <p> * STOPSHIP: document! * Although multiple helper objects may be installed simultaneously, each helper * is responsible only for handling its own data, and will not see entities * created by other components within the backup system. Invocations of multiple * helpers are performed sequentially by the {@link BackupAgentHelper}, with each * helper given a chance to access its own saved state from within the state record * produced during the previous backup operation. * * @see BackupAgentHelper * @see FileBackupHelper * @see SharedPreferencesBackupHelper */ */ public interface BackupHelper { public interface BackupHelper { /** /** Loading @@ -31,24 +41,46 @@ public interface BackupHelper { * application's data directory need to be backed up, write them to * application's data directory need to be backed up, write them to * <code>data</code>, and fill in <code>newState</code> with the state as it * <code>data</code>, and fill in <code>newState</code> with the state as it * exists now. * exists now. * <p> * Implementing this method is much like implementing * {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)} * — the method parameters are the same. When this method is invoked the * {@code oldState} descriptor points to the beginning of the state data * written during this helper's previous backup operation, and the {@code newState} * descriptor points to the file location at which the helper should write its * new state after performing the backup operation. * <p class="note"> * <em>Note:</em> The helper should not close or seek either the {@code oldState} or * the {@code newState} file descriptors.</p> */ */ public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data, public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState); ParcelFileDescriptor newState); /** /** * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} * to restore one entity from the restore dataset. * to restore a single entity from the restore data set. This method will be * <p class=note> * called for each entity in the data set that belongs to this handler. * Do not close the <code>data</code> stream. Do not read more than * <p class="note"> * <code>data.size()</code> bytes from <code>data</code>. * <em>Note:</em> Do not close the <code>data</code> stream. Do not read more than * <code>data.size()</code> bytes from <code>data</code>.</p> */ */ public void restoreEntity(BackupDataInputStream data); public void restoreEntity(BackupDataInputStream data); /** /** * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper} * after a restore operation to write the backup state file corresponding to * after a restore operation to write the backup state file corresponding to * the data as processed by the helper. * the data as processed by the helper. The data written here will be * available to the helper during the next call to its * {@link #performBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)} * method. * <p> * Note that this method will be called even if the handler's * {@link #restoreEntity(BackupDataInputStream)} method was never invoked during * the restore operation. * <p class="note"> * <em>Note:</em> The helper should not close or seek the {@code newState} * file descriptor.</p> */ */ public void writeNewStateDescription(ParcelFileDescriptor fd); public void writeNewStateDescription(ParcelFileDescriptor newState); } }
