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

   1 /*
   2  * Copyright (C) 2009 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package android.app.backup;
  18
  19 import java.io.InputStream;
  20 import java.io.IOException;
  21
  22 /**
  23  * Provides an {@link java.io.InputStream}-like interface for accessing an
  24  * entity's data during a restore operation. Used by {@link BackupHelper} classes within the {@link
  25  * BackupAgentHelper} mechanism.
  26  * <p>
  27  * When {@link BackupHelper#restoreEntity(BackupDataInputStream) BackupHelper.restoreEntity()}
  28  * is called, the current entity's header has already been read from the underlying
  29  * {@link BackupDataInput}.  The entity's key string and total data size are available
  30  * through this class's {@link #getKey()} and {@link #size()} methods, respectively.
  31  * <p class="note">
  32  * <strong>Note:</strong> The caller should take care not to seek or close the underlying data
  33  * source, nor read more than {@link #size()} bytes from the stream.</p>
  34  *
  35  * @see BackupAgentHelper
  36  * @see BackupHelper
  37  */
  38 public class BackupDataInputStream extends InputStream {
  39
  40     String key;
  41     int dataSize;
  42
  43     BackupDataInput mData;
  44     byte[] mOneByte;
  45
  46     /** @hide */
  47     BackupDataInputStream(BackupDataInput data) {
  48         mData = data;
  49     }
  50
  51     /**
  52      * Read one byte of entity data from the stream, returning it as
  53      * an integer value.  If more than {@link #size()} bytes of data
  54      * are read from the stream, the output of this method is undefined.
  55      *
  56      * @return The byte read, or undefined if the end of the stream has been reached.
  57      */
  58     public int read() throws IOException {
  59         byte[] one = mOneByte;
  60         if (mOneByte == null) {
  61             one = mOneByte = new byte[1];
  62         }
  63         mData.readEntityData(one, 0, 1);
  64         return one[0];
  65     }
  66
  67     /**
  68      * Read up to {@code size} bytes of data into a byte array, beginning at position
  69      * {@code offset} within the array.
  70      *
  71      * @param b Byte array into which the data will be read
  72      * @param offset The data will be stored in {@code b} beginning at this index
  73      *   within the array.
  74      * @param size The number of bytes to read in this operation.  If insufficient
  75      *   data exists within the entity to fulfill this request, only as much data
  76      *   will be read as is available.
  77      * @return The number of bytes of data read, or zero if all of the entity's
  78      *   data has already been read.
  79      */
  80     public int read(byte[] b, int offset, int size) throws IOException {
  81         return mData.readEntityData(b, offset, size);
  82     }
  83
  84     /**
  85      * Read enough entity data into a byte array to fill the array.
  86      *
  87      * @param b Byte array to fill with data from the stream.  If the stream does not
  88      *   have sufficient data to fill the array, then the contents of the remainder of
  89      *   the array will be undefined.
  90      * @return The number of bytes of data read, or zero if all of the entity's
  91      *   data has already been read.
  92      */
  93     public int read(byte[] b) throws IOException {
  94         return mData.readEntityData(b, 0, b.length);
  95     }
  96
  97     /**
  98      * Report the key string associated with this entity within the backup data set.
  99      *
 100      * @return The key string for this entity, equivalent to calling
 101      *   {@link BackupDataInput#getKey()} on the underlying {@link BackupDataInput}.
 102      */
 103     public String getKey() {
 104         return this.key;
 105     }
 106
 107     /**
 108      * Report the total number of bytes of data available for the current entity.
 109      *
 110      * @return The number of data bytes available, equivalent to calling
 111      *   {@link BackupDataInput#getDataSize()} on the underlying {@link BackupDataInput}.
 112      */
 113     public int size() {
 114         return this.dataSize;
 115     }
 116 }
 117
 118