Merge "Add some backup Javadoc and clean imports"

import java.io.IOException;

/**

 * This is the central interface between an application and Android's

 * settings backup mechanism.

 *

 * <p>STOPSHIP write more documentation about the backup process here.

 * This is the central interface between an application and Android's settings

 * backup mechanism. Any implementation of a backup agent should perform backup

 * and restore actions in

 * {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)}

 * and {@link #onRestore(BackupDataInput, int, ParcelFileDescriptor)}

 * respectively.

 * <p>

 * A backup agent based on convenient helper classes is available in

 * {@link android.backup.BackupHelperAgent} for less complex implementation

 * requirements.

 * <p>

 * STOPSHIP write more documentation about the backup process here.

 */

public abstract class BackupAgent extends ContextWrapper {

    private static final String TAG = "BackupAgent";

    }

    /**

     * The application is being asked to write any data changed since the

     * last time it performed a backup operation.  The state data recorded

     * during the last backup pass is provided in the oldState file descriptor.

     * If oldState is null, no old state is available and the application should perform

     * a full backup.  In both cases, a representation of the final backup state after

     * this pass should be written to the file pointed to by the newStateFd file descriptor.

     * The application is being asked to write any data changed since the last

     * time it performed a backup operation. The state data recorded during the

     * last backup pass is provided in the <code>oldState</code> file

     * descriptor. If <code>oldState</code> is <code>null</code>, no old state

     * is available and the application should perform a full backup. In both

     * cases, a representation of the final backup state after this pass should

     * be written to the file pointed to by the file descriptor wrapped in

     * <code>newState</code>.

     * 

     * @param oldState An open, read-only ParcelFileDescriptor pointing to the last backup

     *                 state provided by the application.  May be null, in which

     *                 case no prior state is being provided and the application should

     *                 perform a full backup.

     * @param data A structured wrapper around an open, read/write ParcelFileDescriptor

     *             pointing to the backup data destination.  Typically the application will use

     *             backup helper classes to write to this file.

     * @param newState An open, read/write ParcelFileDescriptor pointing to an empty

     *                 file.  The application should record the final backup state

     *                 here after writing the requested data to dataFd.

     * @param oldState An open, read-only ParcelFileDescriptor pointing to the

     *            last backup state provided by the application. May be

     *            <code>null</code>, in which case no prior state is being

     *            provided and the application should perform a full backup.

     * @param data A structured wrapper around an open, read/write

     *            ParcelFileDescriptor pointing to the backup data destination.

     *            Typically the application will use backup helper classes to

     *            write to this file.

     * @param newState An open, read/write ParcelFileDescriptor pointing to an

     *            empty file. The application should record the final backup

     *            state here after writing the requested data to dataFd.

     */

    public abstract void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,

             ParcelFileDescriptor newState) throws IOException;

    /**

     * The application is being restored from backup, and should replace any

     * The application is being restored from backup and should replace any

     * existing data with the contents of the backup. The backup data is

     * provided in the file pointed to by the dataFd file descriptor.  Once

     * the restore is finished, the application should write a representation

     * of the final state to the newStateFd file descriptor,

     *

     * <p>The application is responsible for properly erasing its old data and

     * provided in the file descriptor pointed to by the

     * {@link android.backup.BackupDataInput} instance <code>data</code>. Once

     * the restore is finished, the application should write a representation of

     * the final state to the <code>newState</code> file descriptor.

     * <p>

     * The application is responsible for properly erasing its old data and

     * replacing it with the data supplied to this method. No "clear user data"

     * operation will be performed automatically by the operating system. The

     * exception to this is in the case of a failed restore attempt:  if onRestore()

     * throws an exception, the OS will assume that the application's data may now

     * be in an incoherent state, and will clear it before proceeding.

     * exception to this is in the case of a failed restore attempt: if

     * onRestore() throws an exception, the OS will assume that the

     * application's data may now be in an incoherent state, and will clear it

     * before proceeding.

     * 

     * @param data A structured wrapper around an open, read-only ParcelFileDescriptor

     *             pointing to a full snapshot of the application's data.  Typically the

     *             application will use helper classes to read this data.

     * @param appVersionCode The android:versionCode value of the application that backed

     *        up this particular data set.  This makes it easier for an application's

     *        agent to distinguish among several possible older data versions when

     *        asked to perform the restore operation.

     * @param newState An open, read/write ParcelFileDescriptor pointing to an empty

     *                 file.  The application should record the final backup state

     *                 here after restoring its data from dataFd.

     * @param data A structured wrapper around an open, read-only

     *            ParcelFileDescriptor pointing to a full snapshot of the

     *            application's data. Typically the application will use helper

     *            classes to read this data.

     * @param appVersionCode The android:versionCode value of the application

     *            that backed up this particular data set. This makes it easier

     *            for an application's agent to distinguish among several

     *            possible older data versions when asked to perform the restore

     *            operation.

     * @param newState An open, read/write ParcelFileDescriptor pointing to an

     *            empty file. The application should record the final backup

     *            state here after restoring its data from dataFd.

     */

    public abstract void onRestore(BackupDataInput data, int appVersionCode,

            ParcelFileDescriptor newState)

import android.util.Log;

import java.io.File;

import java.io.FileDescriptor;

/**

 * Like FileBackupHelper, but takes absolute paths for the files instead of

package android.backup;

import android.content.Context;

import java.io.FileDescriptor;

import java.io.IOException;

package android.backup;

import android.content.Context;

import java.io.FileDescriptor;

import java.io.IOException;

import android.os.ParcelFileDescriptor;

import java.io.InputStream;

/**

 * STOPSHIP: document!

 * A convenient interface to be used with the

 * {@link android.backup.BackupHelperAgent} to implement backup and restore of

 * arbitrary data types.

 * <p>

 * STOPSHOP: document!

 */

public interface BackupHelper {

    /**

     * Based on oldState, determine which of the files from the application's data directory

     * need to be backed up, write them to the data stream, and fill in newState with the

     * state as it exists now.

     * Based on <code>oldState</code>, determine which of the files from the

     * 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.

     */

    public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,

            ParcelFileDescriptor newState);