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> … 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