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
17package android.app.backup;
18
19import java.io.InputStream;
20import 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 */
38public 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