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 * <ul>
33 * <li>Only the one-, two-, and three-byte encodings are used.</li>
34 * <li>Code points in the range <code>U+10000</code> &hellip;
35 * <code>U+10ffff</code> are encoded as a surrogate pair, each of which is
36 * represented as a three-byte encoded value.</li>
37 * <li>The code point <code>U+0000</code> is encoded in two-byte form.</li>
38 * </ul>
39 * <p>
40 * Please refer to <a href="http://unicode.org">The Unicode Standard</a> for
41 * further information about character encoding. MUTF-8 is actually closer to
42 * the (relatively less well-known) encoding <a
43 * href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8 per se.
44 *
45 * @see DataInputStream
46 * @see RandomAccessFile
47 */
48public interface DataInput {
49    /**
50     * Reads a boolean.
51     *
52     * @return the next boolean value.
53     * @throws EOFException if the end of the input is reached before the read
54     *         request can be satisfied.
55     * @throws IOException
56     *             if an I/O error occurs while reading.
57     * @see DataOutput#writeBoolean(boolean)
58     */
59    public abstract boolean readBoolean() throws IOException;
60
61    /**
62     * Reads an 8-bit byte value.
63     *
64     * @return the next byte value.
65     * @throws EOFException if the end of the input is reached before the read
66     *         request can be satisfied.
67     * @throws IOException
68     *             if an I/O error occurs while reading.
69     * @see DataOutput#writeByte(int)
70     */
71    public abstract byte readByte() throws IOException;
72
73    /**
74     * Reads a 16-bit character value.
75     *
76     * @return the next char value.
77     * @throws EOFException if the end of the input is reached before the read
78     *         request can be satisfied.
79     * @throws IOException
80     *             if an I/O error occurs while reading.
81     * @see DataOutput#writeChar(int)
82     */
83    public abstract char readChar() throws IOException;
84
85    /**
86     * Reads a 64-bit double value.
87     *
88     * @return the next double value.
89     * @throws EOFException if the end of the input is reached before the read
90     *         request can be satisfied.
91     * @throws IOException
92     *             if an I/O error occurs while reading.
93     * @see DataOutput#writeDouble(double)
94     */
95    public abstract double readDouble() throws IOException;
96
97    /**
98     * Reads a 32-bit float value.
99     *
100     * @return the next float value.
101     * @throws EOFException if the end of the input is reached before the read
102     *         request can be satisfied.
103     * @throws IOException
104     *             if an I/O error occurs while reading.
105     * @see DataOutput#writeFloat(float)
106     */
107    public abstract float readFloat() throws IOException;
108
109    /**
110     * Reads bytes into the byte array {@code buffer}. This method will block
111     * until {@code buffer.length} number of bytes have been read.
112     *
113     * @param buffer
114     *            the buffer to read bytes into.
115     * @throws EOFException if the end of the input is reached before the read
116     *         request can be satisfied.
117     * @throws IOException
118     *             if an I/O error occurs while reading.
119     * @see DataOutput#write(byte[])
120     * @see DataOutput#write(byte[], int, int)
121     */
122    public abstract void readFully(byte[] buffer) throws IOException;
123
124    /**
125     * Reads bytes and stores them in the byte array {@code buffer} starting at
126     * offset {@code offset}. This method blocks until {@code count} number of
127     * bytes have been read.
128     *
129     * @param buffer
130     *            the byte array in which to store the bytes read.
131     * @param offset
132     *            the initial position in {@code buffer} to store the bytes
133     *            read.
134     * @param count
135     *            the maximum number of bytes to store in {@code buffer}.
136     * @throws EOFException if the end of the input is reached before the read
137     *         request can be satisfied.
138     * @throws IOException
139     *             if an I/O error occurs while reading.
140     * @see DataOutput#write(byte[])
141     * @see DataOutput#write(byte[], int, int)
142     */
143    public abstract void readFully(byte[] buffer, int offset, int count)
144            throws IOException;
145
146    /**
147     * Reads a 32-bit integer value.
148     *
149     * @return the next int value.
150     * @throws EOFException if the end of the input is reached before the read
151     *         request can be satisfied.
152     * @throws IOException
153     *             if an I/O error occurs while reading.
154     * @see DataOutput#writeInt(int)
155     */
156    public abstract int readInt() throws IOException;
157
158    /**
159     * Returns a string containing the next line of text available from this
160     * stream. A line is made of zero or more characters followed by {@code
161     * '\n'}, {@code '\r'}, {@code "\r\n"} or the end of the stream. The string
162     * does not include the newline sequence.
163     *
164     * @return the contents of the line or null if no characters have been read
165     *         before the end of the stream.
166     * @throws EOFException if the end of the input is reached before the read
167     *         request can be satisfied.
168     * @throws IOException
169     *             if an I/O error occurs while reading.
170     */
171    public abstract String readLine() throws IOException;
172
173    /**
174     * Reads a 64-bit long value.
175     *
176     * @return the next long value.
177     * @throws EOFException if the end of the input is reached before the read
178     *         request can be satisfied.
179     * @throws IOException
180     *             if an I/O error occurs while reading.
181     * @see DataOutput#writeLong(long)
182     */
183    public abstract long readLong() throws IOException;
184
185    /**
186     * Reads a 16-bit short value.
187     *
188     * @return the next short value.
189     * @throws EOFException if the end of the input is reached before the read
190     *         request can be satisfied.
191     * @throws IOException
192     *             if an I/O error occurs while reading.
193     * @see DataOutput#writeShort(int)
194     */
195    public abstract short readShort() throws IOException;
196
197    /**
198     * Reads an unsigned 8-bit byte value and returns it as an int.
199     *
200     * @return the next unsigned byte value.
201     * @throws EOFException if the end of the input is reached before the read
202     *         request can be satisfied.
203     * @throws IOException
204     *             if an I/O error occurs while reading.
205     * @see DataOutput#writeByte(int)
206     */
207    public abstract int readUnsignedByte() throws IOException;
208
209    /**
210     * Reads a 16-bit unsigned short value and returns it as an int.
211     *
212     * @return the next unsigned short value.
213     * @throws EOFException if the end of the input is reached before the read
214     *         request can be satisfied.
215     * @throws IOException
216     *             if an I/O error occurs while reading.
217     * @see DataOutput#writeShort(int)
218     */
219    public abstract int readUnsignedShort() throws IOException;
220
221    /**
222     * Reads a string encoded with {@link DataInput modified UTF-8}.
223     *
224     * @return the next string encoded with {@link DataInput modified UTF-8}.
225     * @throws EOFException if the end of the input is reached before the read
226     *         request can be satisfied.
227     * @throws IOException
228     *             if an I/O error occurs while reading.
229     * @see DataOutput#writeUTF(java.lang.String)
230     */
231    public abstract String readUTF() throws IOException;
232
233    /**
234     * Skips {@code count} number of bytes. This method will not throw an
235     * {@link EOFException} if the end of the input is reached before
236     * {@code count} bytes where skipped.
237     *
238     * @param count
239     *            the number of bytes to skip.
240     * @return the number of bytes actually skipped.
241     * @throws IOException
242     *             if a problem occurs during skipping.
243     */
244    public abstract int skipBytes(int count) throws IOException;
245}
246