core/java/android/app/backup/BlobBackupHelper.java

/*
 * Copyright (C) 2015 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.app.backup;

import android.os.ParcelFileDescriptor;
import android.util.ArrayMap;
import android.util.Log;

import java.io.BufferedInputStream;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.EOFException;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.util.zip.CRC32;
import java.util.zip.DeflaterOutputStream;
import java.util.zip.InflaterInputStream;

/**
 * Utility class for writing BackupHelpers whose underlying data is a
 * fixed set of byte-array blobs.  The helper manages diff detection
 * and compression on the wire.
 *
 * @hide
 */
public abstract class BlobBackupHelper implements BackupHelper {
    private static final String TAG = "BlobBackupHelper";
    private static final boolean DEBUG = Log.isLoggable(TAG, Log.DEBUG);

    private final int mCurrentBlobVersion;
    private final String[] mKeys;

    public BlobBackupHelper(int currentBlobVersion, String... keys) {
        mCurrentBlobVersion = currentBlobVersion;
        mKeys = keys;
    }

    // Client interface

    /**
     * Generate and return the byte array containing the backup payload describing
     * the current data state.  During a backup operation this method is called once
     * per key that was supplied to the helper's constructor.
     *
     * @return A byte array containing the data blob that the caller wishes to store,
     *     or {@code null} if the current state is empty or undefined.
     */
    abstract protected byte[] getBackupPayload(String key);

    /**
     * Given a byte array that was restored from backup, do whatever is appropriate
     * to apply that described state in the live system.  This method is called once
     * per key/value payload that was delivered for restore.  Typically data is delivered
     * for restore in lexical order by key, <i>not</i> in the order in which the keys
     * were supplied in the constructor.
     *
     * @param payload The byte array that was passed to {@link #getBackupPayload()}
     *     on the ancestral device.
     */
    abstract protected void applyRestoredPayload(String key, byte[] payload);


    // Internal implementation

    /*
     * State on-disk format:
     * [Int]    : overall blob version number
     * [Int=N] : number of keys represented in the state blob
     * N* :
     *     [String] key
     *     [Long]   blob checksum, calculated after compression
     */
    @SuppressWarnings("resource")
    private ArrayMap<String, Long> readOldState(ParcelFileDescriptor oldStateFd) {
        final ArrayMap<String, Long> state = new ArrayMap<String, Long>();

        FileInputStream fis = new FileInputStream(oldStateFd.getFileDescriptor());
        BufferedInputStream bis = new BufferedInputStream(fis);
        DataInputStream in = new DataInputStream(bis);

        try {
            int version = in.readInt();
            if (version <= mCurrentBlobVersion) {
                final int numKeys = in.readInt();
                for (int i = 0; i < numKeys; i++) {
                    String key = in.readUTF();
                    long checksum = in.readLong();
                    state.put(key, checksum);
                }
            } else {
                Log.w(TAG, "Prior state from unrecognized version " + version);
            }
        } catch (EOFException e) {
            // Empty file is expected on first backup,  so carry on. If the state
            // is truncated we just treat it the same way.
            state.clear();
        } catch (Exception e) {
            Log.e(TAG, "Error examining prior backup state " + e.getMessage());
            state.clear();
        }

        return state;
    }

    /**
     * New overall state record
     */
    private void writeBackupState(ArrayMap<String, Long> state, ParcelFileDescriptor stateFile) {
        try {
            FileOutputStream fos = new FileOutputStream(stateFile.getFileDescriptor());

            // We explicitly don't close 'out' because we must not close the backing fd.
            // The FileOutputStream will not close it implicitly.
            @SuppressWarnings("resource")
            DataOutputStream out = new DataOutputStream(fos);

            out.writeInt(mCurrentBlobVersion);

            final int N = (state != null) ? state.size() : 0;
            out.writeInt(N);
            for (int i = 0; i < N; i++) {
                out.writeUTF(state.keyAt(i));
                out.writeLong(state.valueAt(i).longValue());
            }
        } catch (IOException e) {
            Log.e(TAG, "Unable to write updated state", e);
        }
    }

    // Also versions the deflated blob internally in case we need to revise it
    private byte[] deflate(byte[] data) {
        byte[] result = null;
        if (data != null) {
            try {
                ByteArrayOutputStream sink = new ByteArrayOutputStream();
                DataOutputStream headerOut = new DataOutputStream(sink);

                // write the header directly to the sink ahead of the deflated payload
                headerOut.writeInt(mCurrentBlobVersion);

                DeflaterOutputStream out = new DeflaterOutputStream(sink);
                out.write(data);
                out.close();  // finishes and commits the compression run
                result = sink.toByteArray();
                if (DEBUG) {
                    Log.v(TAG, "Deflated " + data.length + " bytes to " + result.length);
                }
            } catch (IOException e) {
                Log.w(TAG, "Unable to process payload: " + e.getMessage());
            }
        }
        return result;
    }

    // Returns null if inflation failed
    private byte[] inflate(byte[] compressedData) {
        byte[] result = null;
        if (compressedData != null) {
            try {
                ByteArrayInputStream source = new ByteArrayInputStream(compressedData);
                DataInputStream headerIn = new DataInputStream(source);
                int version = headerIn.readInt();
                if (version > mCurrentBlobVersion) {
                    Log.w(TAG, "Saved payload from unrecognized version " + version);
                    return null;
                }

                InflaterInputStream in = new InflaterInputStream(source);
                ByteArrayOutputStream inflated = new ByteArrayOutputStream();
                byte[] buffer = new byte[4096];
                int nRead;
                while ((nRead = in.read(buffer)) > 0) {
                    inflated.write(buffer, 0, nRead);
                }
                in.close();
                inflated.flush();
                result = inflated.toByteArray();
                if (DEBUG) {
                    Log.v(TAG, "Inflated " + compressedData.length + " bytes to " + result.length);
                }
            } catch (IOException e) {
                // result is still null here
                Log.w(TAG, "Unable to process restored payload: " + e.getMessage());
            }
        }
        return result;
    }

    private long checksum(byte[] buffer) {
        if (buffer != null) {
            try {
                CRC32 crc = new CRC32();
                ByteArrayInputStream bis = new ByteArrayInputStream(buffer);
                byte[] buf = new byte[4096];
                int nRead = 0;
                while ((nRead = bis.read(buf)) >= 0) {
                    crc.update(buf, 0, nRead);
                }
                return crc.getValue();
            } catch (Exception e) {
                // whoops; fall through with an explicitly bogus checksum
            }
        }
        return -1;
    }

    // BackupHelper interface

    @Override
    public void performBackup(ParcelFileDescriptor oldStateFd, BackupDataOutput data,
            ParcelFileDescriptor newStateFd) {

        final ArrayMap<String, Long> oldState = readOldState(oldStateFd);
        final ArrayMap<String, Long> newState = new ArrayMap<String, Long>();

        try {
            for (String key : mKeys) {
                final byte[] payload = deflate(getBackupPayload(key));
                final long checksum = checksum(payload);
                newState.put(key, checksum);

                Long oldChecksum = oldState.get(key);
                if (oldChecksum == null || checksum != oldChecksum) {
                    if (DEBUG) {
                        Log.i(TAG, "State has changed for key " + key + ", writing");
                    }
                    if (payload != null) {
                        data.writeEntityHeader(key, payload.length);
                        data.writeEntityData(payload, payload.length);
                    } else {
                        // state's changed but there's no current payload => delete
                        data.writeEntityHeader(key, -1);
                    }
                } else {
                    if (DEBUG) {
                        Log.i(TAG, "No change under key " + key + " => not writing");
                    }
                }
            }
        } catch (Exception e) {
            Log.w(TAG,  "Unable to record notification state: " + e.getMessage());
            newState.clear();
        } finally {
            // Always recommit the state even if nothing changed
            writeBackupState(newState, newStateFd);
        }
    }

    @Override
    public void restoreEntity(BackupDataInputStream data) {
        final String key = data.getKey();
        try {
            // known key?
            int which;
            for (which = 0; which < mKeys.length; which++) {
                if (key.equals(mKeys[which])) {
                    break;
                }
            }
            if (which >= mKeys.length) {
                Log.e(TAG, "Unrecognized key " + key + ", ignoring");
                return;
            }

            byte[] compressed = new byte[data.size()];
            data.read(compressed);
            byte[] payload = inflate(compressed);
            applyRestoredPayload(key, payload);
        } catch (Exception e) {
            Log.e(TAG, "Exception restoring entity " + key + " : " + e.getMessage());
        }
    }

    @Override
    public void writeNewStateDescription(ParcelFileDescriptor newState) {
        // Just ensure that we do a full backup the first time after a restore
        writeBackupState(null, newState);
    }
}