1 /* AbstractDataInput.java -- 2 Copyright (C) 2005 Free Software Foundation, Inc. 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 39 package gnu.CORBA.CDR; 40 41 import java.io.IOException; 42 43 /** 44 * Some data input stream that can be either Big or 45 * Little Endian. 46 * 47 * This class reuses code from GNU Classpath DataInputStream. 48 * 49 * @author Audrius Meskauskas (AudriusA@Bioinformatics.org) 50 * @author Warren Levy (warrenl@cygnus.com) 51 * @author Aaron M. Renn (arenn@urbanophile.com) 52 */ 53 public interface AbstractDataInput 54 { 55 /** 56 * This method reads bytes from the underlying stream into the specified 57 * byte array buffer. It will attempt to fill the buffer completely, but 58 * may return a short count if there is insufficient data remaining to be 59 * read to fill the buffer. 60 * 61 * @param b The buffer into which bytes will be read. 62 * 63 * @return The actual number of bytes read, or -1 if end of stream reached 64 * before reading any bytes. 65 * 66 * @exception IOException If an error occurs. 67 */ read(byte[] b)68 int read(byte[] b) 69 throws IOException; 70 71 /** 72 * This method reads bytes from the underlying stream into the specified 73 * byte array buffer. It will attempt to read <code>len</code> bytes and 74 * will start storing them at position <code>off</code> into the buffer. 75 * This method can return a short count if there is insufficient data 76 * remaining to be read to complete the desired read length. 77 * 78 * @param b The buffer into which bytes will be read. 79 * @param off The offset into the buffer to start storing bytes. 80 * @param len The requested number of bytes to read. 81 * 82 * @return The actual number of bytes read, or -1 if end of stream reached 83 * before reading any bytes. 84 * 85 * @exception IOException If an error occurs. 86 */ read(byte[] b, int off, int len)87 int read(byte[] b, int off, int len) 88 throws IOException; 89 90 /** 91 * This method reads a Java boolean value from an input stream. It does 92 * so by reading a single byte of data. If that byte is zero, then the 93 * value returned is <code>false</code>. If the byte is non-zero, then 94 * the value returned is <code>true</code>. 95 * <p> 96 * This method can read a <code>boolean</code> written by an object 97 * implementing the <code>writeBoolean()</code> method in the 98 * <code>DataOutput</code> interface. 99 * 100 * @return The <code>boolean</code> value read 101 * 102 * @exception EOFException If end of file is reached before reading 103 * the boolean 104 * @exception IOException If any other error occurs 105 * 106 * @see DataOutput#writeBoolean 107 */ readBoolean()108 boolean readBoolean() 109 throws IOException; 110 111 /** 112 * This method reads a Java byte value from an input stream. The value 113 * is in the range of -128 to 127. 114 * <p> 115 * This method can read a <code>byte</code> written by an object 116 * implementing the <code>writeByte()</code> method in the 117 * <code>DataOutput</code> interface. 118 * 119 * @return The <code>byte</code> value read 120 * 121 * @exception EOFException If end of file is reached before reading the byte 122 * @exception IOException If any other error occurs 123 * 124 * @see DataOutput#writeByte 125 */ readByte()126 byte readByte() 127 throws IOException; 128 129 /** 130 * This method reads a Java <code>char</code> value from an input stream. 131 * It operates by reading two bytes from the stream and converting them to 132 * a single 16-bit Java <code>char</code>. The two bytes are stored most 133 * significant byte first (i.e., "big endian") regardless of the native 134 * host byte ordering. 135 * <p> 136 * As an example, if <code>byte1</code> and <code>byte2</code> 137 * represent the first and second byte read from the stream 138 * respectively, they will be transformed to a <code>char</code> in 139 * the following manner: 140 * <p> 141 * <code>(char)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF)</code> 142 * <p> 143 * This method can read a <code>char</code> written by an object 144 * implementing the <code>writeChar()</code> method in the 145 * <code>DataOutput</code> interface. 146 * 147 * @return The <code>char</code> value read 148 * 149 * @exception EOFException If end of file is reached before reading the char 150 * @exception IOException If any other error occurs 151 * 152 * @see DataOutput#writeChar 153 */ readChar()154 char readChar() 155 throws IOException; 156 157 /** 158 * This method reads a Java double value from an input stream. It operates 159 * by first reading a <code>long</code> value from the stream by calling the 160 * <code>readLong()</code> method in this interface, then converts 161 * that <code>long</code> to a <code>double</code> using the 162 * <code>longBitsToDouble</code> method in the class 163 * <code>java.lang.Double</code> 164 * <p> 165 * This method can read a <code>double</code> written by an object 166 * implementing the <code>writeDouble()</code> method in the 167 * <code>DataOutput</code> interface. 168 * 169 * @return The <code>double</code> value read 170 * 171 * @exception EOFException If end of file is reached before reading 172 * the double 173 * @exception IOException If any other error occurs 174 * 175 * @see DataOutput#writeDouble 176 * @see java.lang.Double#longBitsToDouble 177 */ readDouble()178 double readDouble() 179 throws IOException; 180 181 /** 182 * This method reads a Java float value from an input stream. It 183 * operates by first reading an <code>int</code> value from the 184 * stream by calling the <code>readInt()</code> method in this 185 * interface, then converts that <code>int</code> to a 186 * <code>float</code> using the <code>intBitsToFloat</code> method 187 * in the class <code>java.lang.Float</code> 188 * <p> 189 * This method can read a <code>float</code> written by an object 190 * implementing the <code>writeFloat()</code> method in the 191 * <code>DataOutput</code> interface. 192 * 193 * @return The <code>float</code> value read 194 * 195 * @exception EOFException If end of file is reached before reading the float 196 * @exception IOException If any other error occurs 197 * 198 * @see DataOutput#writeFloat 199 * @see java.lang.Float#intBitsToFloat 200 */ readFloat()201 float readFloat() 202 throws IOException; 203 204 /** 205 * This method reads raw bytes into the passed array until the array is 206 * full. Note that this method blocks until the data is available and 207 * throws an exception if there is not enough data left in the stream to 208 * fill the buffer. Note also that zero length buffers are permitted. 209 * In this case, the method will return immediately without reading any 210 * bytes from the stream. 211 * 212 * @param b The buffer into which to read the data 213 * 214 * @exception EOFException If end of file is reached before filling the 215 * buffer 216 * @exception IOException If any other error occurs 217 */ readFully(byte[] b)218 void readFully(byte[] b) 219 throws IOException; 220 221 /** 222 * This method reads a Java <code>int</code> value from an input stream 223 * It operates by reading four bytes from the stream and converting them to 224 * a single Java <code>int</code>. The bytes are stored most 225 * significant byte first (i.e., "big endian") regardless of the native 226 * host byte ordering. 227 * <p> 228 * As an example, if <code>byte1</code> through <code>byte4</code> represent 229 * the first four bytes read from the stream, they will be 230 * transformed to an <code>int</code> in the following manner: 231 * <p> 232 * <code>(int)(((byte1 & 0xFF) << 24) + ((byte2 & 0xFF) << 16) + 233 * ((byte3 & 0xFF)<< 8) + (byte4 & 0xFF)))</code> 234 * <p> 235 * The value returned is in the range of -2147483648 to 2147483647. 236 * <p> 237 * This method can read an <code>int</code> written by an object 238 * implementing the <code>writeInt()</code> method in the 239 * <code>DataOutput</code> interface. 240 * 241 * @return The <code>int</code> value read 242 * 243 * @exception EOFException If end of file is reached before reading the int 244 * @exception IOException If any other error occurs 245 * 246 * @see DataOutput#writeInt 247 */ readInt()248 int readInt() 249 throws IOException; 250 251 /** 252 * This method reads a Java <code>long</code> value from an input stream 253 * It operates by reading eight bytes from the stream and converting them to 254 * a single Java <code>long</code>. The bytes are stored most 255 * significant byte first (i.e., "big endian") regardless of the native 256 * host byte ordering. 257 * <p> 258 * As an example, if <code>byte1</code> through <code>byte8</code> represent 259 * the first eight bytes read from the stream, they will be 260 * transformed to an <code>long</code> in the following manner: 261 * <p> 262 * <code>(long)(((byte1 & 0xFF) << 56) + ((byte2 & 0xFF) << 48) + 263 * ((byte3 & 0xFF) << 40) + ((byte4 & 0xFF) << 32) + 264 * ((byte5 & 0xFF) << 24) + ((byte6 & 0xFF) << 16) + 265 * ((byte7 & 0xFF) << 8) + (byte8 & 0xFF))) 266 * </code> 267 * <p> 268 * The value returned is in the range of -9223372036854775808 to 269 * 9223372036854775807. 270 * <p> 271 * This method can read an <code>long</code> written by an object 272 * implementing the <code>writeLong()</code> method in the 273 * <code>DataOutput</code> interface. 274 * 275 * @return The <code>long</code> value read 276 * 277 * @exception EOFException If end of file is reached before reading the long 278 * @exception IOException If any other error occurs 279 * 280 * @see DataOutput#writeLong 281 */ readLong()282 long readLong() 283 throws IOException; 284 285 /** 286 * This method reads a signed 16-bit value into a Java in from the 287 * stream. It operates by reading two bytes from the stream and 288 * converting them to a single 16-bit Java <code>short</code>. The 289 * two bytes are stored most significant byte first (i.e., "big 290 * endian") regardless of the native host byte ordering. 291 * <p> 292 * As an example, if <code>byte1</code> and <code>byte2</code> 293 * represent the first and second byte read from the stream 294 * respectively, they will be transformed to a <code>short</code>. in 295 * the following manner: 296 * <p> 297 * <code>(short)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF))</code> 298 * <p> 299 * The value returned is in the range of -32768 to 32767. 300 * <p> 301 * This method can read a <code>short</code> written by an object 302 * implementing the <code>writeShort()</code> method in the 303 * <code>DataOutput</code> interface. 304 * 305 * @return The <code>short</code> value read 306 * 307 * @exception EOFException If end of file is reached before reading the value 308 * @exception IOException If any other error occurs 309 * 310 * @see DataOutput#writeShort 311 */ readShort()312 short readShort() 313 throws IOException; 314 315 /** 316 * This method reads 8 unsigned bits into a Java <code>int</code> 317 * value from the stream. The value returned is in the range of 0 to 318 * 255. 319 * <p> 320 * This method can read an unsigned byte written by an object 321 * implementing the <code>writeUnsignedByte()</code> method in the 322 * <code>DataOutput</code> interface. 323 * 324 * @return The unsigned bytes value read as a Java <code>int</code>. 325 * 326 * @exception EOFException If end of file is reached before reading the value 327 * @exception IOException If any other error occurs 328 * 329 * @see DataOutput#writeByte 330 */ readUnsignedByte()331 int readUnsignedByte() 332 throws IOException; 333 334 /** 335 * This method reads 16 unsigned bits into a Java int value from the stream. 336 * It operates by reading two bytes from the stream and converting them to 337 * a single Java <code>int</code> The two bytes are stored most 338 * significant byte first (i.e., "big endian") regardless of the native 339 * host byte ordering. 340 * <p> 341 * As an example, if <code>byte1</code> and <code>byte2</code> 342 * represent the first and second byte read from the stream 343 * respectively, they will be transformed to an <code>int</code> in 344 * the following manner: 345 * <p> 346 * <code>(int)(((byte1 & 0xFF) << 8) + (byte2 & 0xFF))</code> 347 * <p> 348 * The value returned is in the range of 0 to 65535. 349 * <p> 350 * This method can read an unsigned short written by an object 351 * implementing the <code>writeUnsignedShort()</code> method in the 352 * <code>DataOutput</code> interface. 353 * 354 * @return The unsigned short value read as a Java <code>int</code> 355 * 356 * @exception EOFException If end of file is reached before reading the value 357 * @exception IOException If any other error occurs 358 * 359 * @see DataOutput#writeShort 360 */ readUnsignedShort()361 int readUnsignedShort() 362 throws IOException; 363 364 /** 365 * Read a single byte. 366 * 367 * @return a byte, extracted from the stream or -1 if 368 * EOF has been reached. 369 * @throws IOException 370 */ read()371 public int read() 372 throws IOException; 373 374 /** 375 * This method attempts to skip and discard the specified number of bytes 376 * in the input stream. It may actually skip fewer bytes than requested. 377 * This method will not skip any bytes if passed a negative number of bytes 378 * to skip. 379 * 380 * @param n The requested number of bytes to skip. 381 * 382 * @return The requested number of bytes to skip. 383 * 384 * @exception IOException If an error occurs. 385 * @specnote The JDK docs claim that this returns the number of bytes 386 * actually skipped. The JCL claims that this method can throw an 387 * EOFException. Neither of these appear to be true in the JDK 1.3's 388 * implementation. This tries to implement the actual JDK behaviour. 389 */ skipBytes(int n)390 int skipBytes(int n) 391 throws IOException; 392 }