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 119
