SDK: last of the backup/restore docs content (7cc08823) · Commits · e / os / android_frameworks_base

core/java/android/app/backup/BackupAgentHelper.java

+19 −7

Original line number	Diff line number	Diff line
		@@ -21,16 +21,28 @@ import android.os.ParcelFileDescriptor;
		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
		* key prefix. An application will typically extend this class in their own
		* backup agent. Then, within the agent's onBackup() and onRestore() methods, it
		* will call {@link #addHelper(String, BackupHelper)} one or more times to
		* specify the data sets, then invoke super.onBackup() or super.onRestore() to
		* have the BackupAgentHelper implementation process the data.
		* key prefix. When processing a backup or restore operation, the BackupAgentHelper
		* dispatches to one or more installed {@link BackupHelper helpers} objects, each
		* of which is responsible for a defined subset of the data being processed.
		* <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 SharedPreferencesBackupHelper
		*/

core/java/android/app/backup/BackupDataInputStream.java

+57 −2

Original line number	Diff line number	Diff line
		@@ -20,7 +20,21 @@ import java.io.InputStream;
		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 {

		String key;
		@@ -34,6 +48,13 @@ public class BackupDataInputStream extends InputStream {
		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 {
		byte[] one = mOneByte;
		if (mOneByte == null) {
		@@ -43,18 +64,52 @@ public class BackupDataInputStream extends InputStream {
		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 {
		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 {
		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() {
		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() {
		return this.dataSize;
		}

core/java/android/app/backup/BackupHelper.java

+42 −10

Original line number	Diff line number	Diff line
		@@ -19,11 +19,21 @@ package android.app.backup;
		import android.os.ParcelFileDescriptor;

		/**
		* A convenient interface to be used with the
		* {@link android.app.backup.BackupAgentHelper} class to implement backup and restore of
		* arbitrary data types.
		* This interface defines the calling interface that {@link BackupAgentHelper} uses
		* when dispatching backup and restore operations to the installed helpers.
		* Applications can define and install their own helpers as well as using those
		* provided as part of the Android framework.
		* <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 {
		/**
		@@ -31,24 +41,46 @@ public interface BackupHelper {
		* 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
		* 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,
		ParcelFileDescriptor newState);

		/**
		* Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper}
		* to restore one entity from the restore dataset.
		* <p class=note>
		* Do not close the <code>data</code> stream. Do not read more than
		* <code>data.size()</code> bytes from <code>data</code>.
		* to restore a single entity from the restore data set. This method will be
		* called for each entity in the data set that belongs to this handler.
		* <p class="note">
		* <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);

		/**
		* Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper}
		* 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);
		}