Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5a20ea16 authored by Kenny Root's avatar Kenny Root
Browse files

Add some backup Javadoc and clean imports 

Add a bit more Javadoc to the backup infrastructure and clean up unused
imports.

Change-Id: I8ab7c3fb887ae2e8d2f1bfac42f03cb4b42685ef
parent 5386b3f9

core/java/android/app/BackupAgent.java

+60 −45
Original line number Original line Diff line number Diff line
@@ -31,10 +31,18 @@ import android.util.Log; 
import java.io.IOException;

import java.io.IOException;





/**

/**

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

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

 * settings backup mechanism.

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

 *

 * and restore actions in

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

 * {@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 {

public abstract class BackupAgent extends ContextWrapper {

    private static final String TAG = "BackupAgent";

    private static final String TAG = "BackupAgent";
@@ -51,51 +59,58 @@ public abstract class BackupAgent extends ContextWrapper { 
    }

    }





    /**

    /**

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

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

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

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

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

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

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

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

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

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

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

     * 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

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

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

     *            last backup state provided by the application. May be

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

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

     *                 perform a full backup.

     *            provided and the application should perform a full backup.

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

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

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

     *            ParcelFileDescriptor pointing to the backup data destination.

     *             backup helper classes to write to this file.

     *            Typically the application will use backup helper classes to

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

     *            write to this file.

     *                 file.  The application should record the final backup state

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

     *                 here after writing the requested data to dataFd.

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

    public abstract void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,

             ParcelFileDescriptor newState) throws IOException;

             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

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

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

     * provided in the file descriptor pointed to by the

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

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

     * of the final state to the newStateFd file descriptor,

     * 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

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

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

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

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

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

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

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

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

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

     * 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

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

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

     *            ParcelFileDescriptor pointing to a full snapshot of the

     *             application will use helper classes to read this data.

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

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

     *            classes to read this data.

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

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

     *        agent to distinguish among several possible older data versions when

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

     *        asked to perform the restore operation.

     *            for an application's agent to distinguish among several

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

     *            possible older data versions when asked to perform the restore

     *                 file.  The application should record the final backup state

     *            operation.

     *                 here after restoring its data from dataFd.

     * @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,

    public abstract void onRestore(BackupDataInput data, int appVersionCode,

            ParcelFileDescriptor newState)

            ParcelFileDescriptor newState)

core/java/android/backup/AbsoluteFileBackupHelper.java

+0 −1
Original line number Original line Diff line number Diff line
@@ -21,7 +21,6 @@ import android.os.ParcelFileDescriptor; 
import android.util.Log;

import android.util.Log;





import java.io.File;

import java.io.File;

import java.io.FileDescriptor;





/**

/**

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

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

core/java/android/backup/BackupDataInput.java

+0 −2
Original line number Original line Diff line number Diff line
@@ -16,8 +16,6 @@ 




package android.backup;

package android.backup;





import android.content.Context;



import java.io.FileDescriptor;

import java.io.FileDescriptor;

import java.io.IOException;

import java.io.IOException;

core/java/android/backup/BackupDataOutput.java

+0 −2
Original line number Original line Diff line number Diff line
@@ -16,8 +16,6 @@ 




package android.backup;

package android.backup;





import android.content.Context;



import java.io.FileDescriptor;

import java.io.FileDescriptor;

import java.io.IOException;

import java.io.IOException;

core/java/android/backup/BackupHelper.java

+9 −6
Original line number Original line Diff line number Diff line
@@ -18,16 +18,19 @@ package android.backup; 




import android.os.ParcelFileDescriptor;

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 {

public interface BackupHelper {

    /**

    /**

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

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

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

     * application's data directory need to be backed up, write them to

     * state as it exists now.

     * <code>data</code>, and fill in <code>newState</code> with the state as it

     * exists now.

     */

     */

    public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,

    public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,

            ParcelFileDescriptor newState);

            ParcelFileDescriptor newState);