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> … 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 */ 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 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 */ 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 */ 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 */ 107 public abstract float readFloat() throws IOException; 108 109 /** 110 * Equivalent to {@code readFully(dst, 0, dst.length);}. 111 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 240 public abstract int skipBytes(int count) throws IOException; 241 } 242
