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 
18 package java.io;
19 
20 /**
21  * Defines an interface for classes that are able to read big-endian 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  */
48 public 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      */
readBoolean()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      */
readByte()71     public abstract byte readByte() throws IOException;
72 
73     /**
74      * Reads a big-endian 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      */
readChar()83     public abstract char readChar() throws IOException;
84 
85     /**
86      * Reads a big-endian 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      */
readDouble()95     public abstract double readDouble() throws IOException;
96 
97     /**
98      * Reads a big-endian 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      */
readFloat()107     public abstract float readFloat() throws IOException;
108 
109     /**
110      * Equivalent to {@code readFully(dst, 0, dst.length);}.
111      */
readFully(byte[] dst)112     public abstract void readFully(byte[] dst) throws IOException;
113 
114     /**
115      * Reads {@code byteCount} bytes from this stream and stores them in the byte
116      * array {@code dst} starting at {@code offset}. If {@code byteCount} is zero, then this
117      * method returns without reading any bytes. Otherwise, this method blocks until
118      * {@code byteCount} bytes have been read. If insufficient bytes are available,
119      * {@code EOFException} is thrown. If an I/O error occurs, {@code IOException} is
120      * thrown. When an exception is thrown, some bytes may have been consumed from the stream
121      * and written into the array.
122      *
123      * @param dst
124      *            the byte array into which the data is read.
125      * @param offset
126      *            the offset in {@code dst} at which to store the bytes.
127      * @param byteCount
128      *            the number of bytes to read.
129      * @throws EOFException
130      *             if the end of the source stream is reached before enough
131      *             bytes have been read.
132      * @throws IndexOutOfBoundsException
133      *             if {@code offset < 0} or {@code byteCount < 0}, or
134      *             {@code offset + byteCount > dst.length}.
135      * @throws IOException
136      *             if a problem occurs while reading from this stream.
137      * @throws NullPointerException
138      *             if {@code dst} is null.
139      */
readFully(byte[] dst, int offset, int byteCount)140     public abstract void readFully(byte[] dst, int offset, int byteCount) throws IOException;
141 
142     /**
143      * Reads a big-endian 32-bit integer value.
144      *
145      * @return the next int value.
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#writeInt(int)
151      */
readInt()152     public abstract int readInt() throws IOException;
153 
154     /**
155      * Returns a string containing the next line of text available from this
156      * stream. A line is made of zero or more characters followed by {@code
157      * '\n'}, {@code '\r'}, {@code "\r\n"} or the end of the stream. The string
158      * does not include the newline sequence.
159      *
160      * @return the contents of the line or null if no characters have been read
161      *         before the end of the stream.
162      * @throws EOFException if the end of the input is reached before the read
163      *         request can be satisfied.
164      * @throws IOException
165      *             if an I/O error occurs while reading.
166      */
readLine()167     public abstract String readLine() throws IOException;
168 
169     /**
170      * Reads a big-endian 64-bit long value.
171      *
172      * @return the next long value.
173      * @throws EOFException if the end of the input is reached before the read
174      *         request can be satisfied.
175      * @throws IOException
176      *             if an I/O error occurs while reading.
177      * @see DataOutput#writeLong(long)
178      */
readLong()179     public abstract long readLong() throws IOException;
180 
181     /**
182      * Reads a big-endian 16-bit short value.
183      *
184      * @return the next short value.
185      * @throws EOFException if the end of the input is reached before the read
186      *         request can be satisfied.
187      * @throws IOException
188      *             if an I/O error occurs while reading.
189      * @see DataOutput#writeShort(int)
190      */
readShort()191     public abstract short readShort() throws IOException;
192 
193     /**
194      * Reads an unsigned 8-bit byte value and returns it as an int.
195      *
196      * @return the next unsigned byte value.
197      * @throws EOFException if the end of the input is reached before the read
198      *         request can be satisfied.
199      * @throws IOException
200      *             if an I/O error occurs while reading.
201      * @see DataOutput#writeByte(int)
202      */
readUnsignedByte()203     public abstract int readUnsignedByte() throws IOException;
204 
205     /**
206      * Reads a big-endian 16-bit unsigned short value and returns it as an int.
207      *
208      * @return the next unsigned short value.
209      * @throws EOFException if the end of the input is reached before the read
210      *         request can be satisfied.
211      * @throws IOException
212      *             if an I/O error occurs while reading.
213      * @see DataOutput#writeShort(int)
214      */
readUnsignedShort()215     public abstract int readUnsignedShort() throws IOException;
216 
217     /**
218      * Reads a string encoded with {@link DataInput modified UTF-8}.
219      *
220      * @return the next string encoded with {@link DataInput modified UTF-8}.
221      * @throws EOFException if the end of the input is reached before the read
222      *         request can be satisfied.
223      * @throws IOException
224      *             if an I/O error occurs while reading.
225      * @see DataOutput#writeUTF(java.lang.String)
226      */
readUTF()227     public abstract String readUTF() throws IOException;
228 
229     /**
230      * Skips {@code count} number of bytes. This method will not throw an
231      * {@link EOFException} if the end of the input is reached before
232      * {@code count} bytes where skipped.
233      *
234      * @param count
235      *            the number of bytes to skip.
236      * @return the number of bytes actually skipped.
237      * @throws IOException
238      *             if a problem occurs during skipping.
239      */
skipBytes(int count)240     public abstract int skipBytes(int count) throws IOException;
241 }
242