DataInput.java revision dd828f42a5c83b4270d4fbf6fce2da1878f1e84a 
1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.io;
19
20/**
21 * Defines an interface for classes that are able to read typed data from some
22 * source. Typically, this data has been written by a class which implements
23 * {@link DataOutput}. Types that can be read include byte, 16-bit short, 32-bit
24 * int, 32-bit float, 64-bit long, 64-bit double, byte strings, and MUTF-8
25 * strings.
26 *
27 * <h3>MUTF-8 (Modified UTF-8) Encoding</h3>
28 * <p>
29 * When encoding strings as UTF, implementations of {@code DataInput} and
30 * {@code DataOutput} use a slightly modified form of UTF-8, hereafter referred
31 * to as MUTF-8. This form is identical to standard UTF-8, except:
32 * </p>
33 * <ul>
34 * <li>Only the one-, two-, and three-byte encodings are used.</li>
35 * <li>Code points in the range <code>U+10000</code> &hellip;
36 * <code>U+10ffff</code> are encoded as a surrogate pair, each of which is
37 * represented as a three-byte encoded value.</li>
38 * <li>The code point <code>U+0000</code> is encoded in two-byte form.</li>
39 * </ul>
40 * <p>
41 * Please refer to <a href="http://unicode.org">The Unicode Standard</a> for
42 * further information about character encoding. MUTF-8 is actually closer to
43 * the (relatively less well-known) encoding <a
44 * href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8 per se.
45 * </p>
46 *
47 * @see DataInputStream
48 * @see RandomAccessFile
49 *
50 * @since Android 1.0
51 */
52public interface DataInput {
53    /**
54     * Reads a boolean.
55     *
56     * @return the next boolean value.
57     * @throws EOFException if the end of the input is reached before the read
58     *         request can be satisfied.
59     * @throws IOException
60     *             if an I/O error occurs while reading.
61     * @see DataOutput#writeBoolean(boolean)
62     * @since Android 1.0
63     */
64    public abstract boolean readBoolean() throws IOException;
65
66    /**
67     * Reads an 8-bit byte value.
68     *
69     * @return the next byte value.
70     * @throws EOFException if the end of the input is reached before the read
71     *         request can be satisfied.
72     * @throws IOException
73     *             if an I/O error occurs while reading.
74     * @see DataOutput#writeByte(int)
75     * @since Android 1.0
76     */
77    public abstract byte readByte() throws IOException;
78
79    /**
80     * Reads a 16-bit character value.
81     *
82     * @return the next char value.
83     * @throws EOFException if the end of the input is reached before the read
84     *         request can be satisfied.
85     * @throws IOException
86     *             if an I/O error occurs while reading.
87     * @see DataOutput#writeChar(int)
88     * @since Android 1.0
89     */
90    public abstract char readChar() throws IOException;
91
92    /**
93     * Reads a 64-bit double value.
94     *
95     * @return the next double value.
96     * @throws EOFException if the end of the input is reached before the read
97     *         request can be satisfied.
98     * @throws IOException
99     *             if an I/O error occurs while reading.
100     * @see DataOutput#writeDouble(double)
101     * @since Android 1.0
102     */
103    public abstract double readDouble() throws IOException;
104
105    /**
106     * Reads a 32-bit float value.
107     *
108     * @return the next float value.
109     * @throws EOFException if the end of the input is reached before the read
110     *         request can be satisfied.
111     * @throws IOException
112     *             if an I/O error occurs while reading.
113     * @see DataOutput#writeFloat(float)
114     * @since Android 1.0
115     */
116    public abstract float readFloat() throws IOException;
117
118    /**
119     * Reads bytes into the byte array {@code buffer}. This method will block
120     * until {@code buffer.length} number of bytes have been read.
121     *
122     * @param buffer
123     *            the buffer to read bytes into.
124     * @throws EOFException if the end of the input is reached before the read
125     *         request can be satisfied.
126     * @throws IOException
127     *             if an I/O error occurs while reading.
128     * @see DataOutput#write(byte[])
129     * @see DataOutput#write(byte[], int, int)
130     * @since Android 1.0
131     */
132    public abstract void readFully(byte[] buffer) throws IOException;
133
134    /**
135     * Reads bytes and stores them in the byte array {@code buffer} starting at
136     * offset {@code offset}. This method blocks until {@code count} number of
137     * bytes have been read.
138     *
139     * @param buffer
140     *            the byte array in which to store the bytes read.
141     * @param offset
142     *            the initial position in {@code buffer} to store the bytes
143     *            read.
144     * @param count
145     *            the maximum number of bytes to store in {@code buffer}.
146     * @throws EOFException if the end of the input is reached before the read
147     *         request can be satisfied.
148     * @throws IOException
149     *             if an I/O error occurs while reading.
150     * @see DataOutput#write(byte[])
151     * @see DataOutput#write(byte[], int, int)
152     * @since Android 1.0
153     */
154    public abstract void readFully(byte[] buffer, int offset, int count)
155            throws IOException;
156
157    /**
158     * Reads a 32-bit integer value.
159     *
160     * @return the next int value.
161     * @throws EOFException if the end of the input is reached before the read
162     *         request can be satisfied.
163     * @throws IOException
164     *             if an I/O error occurs while reading.
165     * @see DataOutput#writeInt(int)
166     * @since Android 1.0
167     */
168    public abstract int readInt() throws IOException;
169
170    /**
171     * Returns a string containing the next line of text available from this
172     * stream. A line is made of zero or more characters followed by {@code
173     * '\n'}, {@code '\r'}, {@code "\r\n"} or the end of the stream. The string
174     * does not include the newline sequence.
175     *
176     * @return the contents of the line or null if no characters have been read
177     *         before the end of the stream.
178     * @throws EOFException if the end of the input is reached before the read
179     *         request can be satisfied.
180     * @throws IOException
181     *             if an I/O error occurs while reading.
182     * @since Android 1.0
183     */
184    public abstract String readLine() throws IOException;
185
186    /**
187     * Reads a 64-bit long value.
188     *
189     * @return the next long value.
190     * @throws EOFException if the end of the input is reached before the read
191     *         request can be satisfied.
192     * @throws IOException
193     *             if an I/O error occurs while reading.
194     * @see DataOutput#writeLong(long)
195     * @since Android 1.0
196     */
197    public abstract long readLong() throws IOException;
198
199    /**
200     * Reads a 16-bit short value.
201     *
202     * @return the next short value.
203     * @throws EOFException if the end of the input is reached before the read
204     *         request can be satisfied.
205     * @throws IOException
206     *             if an I/O error occurs while reading.
207     * @see DataOutput#writeShort(int)
208     * @since Android 1.0
209     */
210    public abstract short readShort() throws IOException;
211
212    /**
213     * Reads an unsigned 8-bit byte value and returns it as an int.
214     *
215     * @return the next unsigned byte value.
216     * @throws EOFException if the end of the input is reached before the read
217     *         request can be satisfied.
218     * @throws IOException
219     *             if an I/O error occurs while reading.
220     * @see DataOutput#writeByte(int)
221     * @since Android 1.0
222     */
223    public abstract int readUnsignedByte() throws IOException;
224
225    /**
226     * Reads a 16-bit unsigned short value and returns it as an int.
227     *
228     * @return the next unsigned short value.
229     * @throws EOFException if the end of the input is reached before the read
230     *         request can be satisfied.
231     * @throws IOException
232     *             if an I/O error occurs while reading.
233     * @see DataOutput#writeShort(int)
234     * @since Android 1.0
235     */
236    public abstract int readUnsignedShort() throws IOException;
237
238    /**
239     * Reads a string encoded with {@link DataInput modified UTF-8}.
240     *
241     * @return the next string encoded with {@link DataInput modified UTF-8}.
242     * @throws EOFException if the end of the input is reached before the read
243     *         request can be satisfied.
244     * @throws IOException
245     *             if an I/O error occurs while reading.
246     * @see DataOutput#writeUTF(java.lang.String)
247     * @since Android 1.0
248     */
249    public abstract String readUTF() throws IOException;
250
251    /**
252     * Skips {@code count} number of bytes. This method will not throw an
253     * {@link EOFException} if the end of the input is reached before
254     * {@code count} bytes where skipped.
255     *
256     * @param count
257     *            the number of bytes to skip.
258     * @return the number of bytes actually skipped.
259     * @throws IOException
260     *             if a problem occurs during skipping.
261     * @since Android 1.0
262     */
263    public abstract int skipBytes(int count) throws IOException;
264}
265